# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/quickstart
> 介绍 Gravity Engine iOS SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**iOS**接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. 获取 AccessToken 和产品 ID [#1-获取-accesstoken-和产品-id]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken 和产品 APP\_ID，请妥善保存避免泄露。
## 2. 集成引力引擎 SDK [#2-集成引力引擎-sdk]
### 2.1 CocoaPods 自动集成 [#21-cocoapods-自动集成]
**1. 创建并编辑 `Podfile` 内容（如果已有，直接编辑）：**
创建 `Podfile`，项目工程（.xcodeproj）文件同目录下命令行执行命令：
```bash
pod init
```
编辑 `Podfile` 的内容，按您的发行地区选择：
```ruby
platform :ios, '9.0'
target 'YourProjectTarget' do
pod 'GravityEngineSDK','${LATEST_VERSION}'
end
```
```ruby
platform :ios, '9.0'
target 'YourProjectTarget' do
pod 'GravityEngineOverseaSDK','${LATEST_VERSION}'
end
```
> `${LATEST_VERSION}` 请参见[发版记录](/docs/client-sdk/ios/changelog) 请使用其中最新版本的 version 以保证获得引力及时的更新支持。
**2. 执行安装命令**
```bash
pod install
```
**3. 导入成功，启动工程**
命令执行成功后，会生成 .xcworkspace 文件，说明您已成功导入 iOS SDK。打开 .xcworkspace 文件以启动工程（注意：此时不能同时开启 .xcodeproj 文件）
### 2.2 手动集成 SDK [#22-手动集成-sdk]
下载并解压最新 iOS SDK 包，您可以在[SDK下载](/docs/client-sdk/sdk-overview)页获取最新版本 SDK包
将 `GravityEngineSDK.xcframework` 拖入 XCode Project Workspace 工程项目中
找到 Targets，在 Build Settings 菜单的 `Other linker flags` 选项添加 `-ObjC`
切换到 `Build Phases` 选项卡，在 `Link Binary With Libraries` 栏目下添加如下依赖项：
1. `libz.tbd`（进行数据压缩）
2. `Security.framework`（用于存储设备标识）
3. `AdServices.framework`（Apple Search Ads 归因，optional 形式引入）
4. `SystemConfiguration.framework`（检测网络状况）
5. `libsqlite3.tbd`
6. `AppTrackingTransparency.framework`（获取 idfa 需要）
7. `AdSupport.framework`（获取 idfa 需要）
8. `libc++.tbd`
> **以上依赖项，必须全部添加，否则会导致编译失败！**
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
> **应用每次启动都要执行 `SDK` 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。**
**Objective-C**
```objective-c
GEConfig *config = [GEConfig new];
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = @{
@"testSuperKey":@"testSuperValue"
};
[GravityEngineSDK startWithConfig:config];
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];
```
**Swift**
```swift
let config = GEConfig();
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = [
"testSuperKey": "testSuperValue"
];
GravityEngineSDK.start(with: config);
let instance = GravityEngineSDK.sharedInstance(withAppid: config.appid);
```
**Objective-C**
```objective-c
GEConfig *config = [GEConfig new];
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = @{
@"testSuperKey":@"testSuperValue"
};
[GravityEngineSDK startWithConfig:config];
config.isGDPRArea = NO;//是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置 isGDPRArea = YES
config.isCoppaEnabled = NO;//是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = YES
config.isKidsAppEnabled = NO;//是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = YES
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];
```
**Swift**
```swift
let config = GEConfig();
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = [
"testSuperKey": "testSuperValue"
];
config.isGDPRArea = false;//是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置true
config.isCoppaEnabled = false;//是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 true
config.isKidsAppEnabled = false;//是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置true
GravityEngineSDK.start(with: config);
let instance = GravityEngineSDK.sharedInstance(withAppid: config.appid);
```
参数说明：
* `APP_ID` : 在第一步中获取的项目通行证 APP\_ID
* `ACCESS_TOKEN` : 在第一步中获取的项目通行证 AccessToken
## 4. 初始化 [#4-初始化]
在用户可以获取到用户唯一性 `ID` 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。
### 4.1 添加 att 弹窗描述 [#41-添加-att-弹窗描述]
需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致 `idfa` 获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！
```xml
NSUserTrackingUsageDescription
此标识符将用于向您推荐个性化广告。
```
### 4.2 调用引力初始化 [#42-调用引力初始化]
> **避免在 ATT 授权弹窗或其他系统权限弹窗的回调中调用初始化方法，这可能导致权限请求阻塞或初始化异常。**
```objective-c
//caidStr 仅为示例
//NSString * caidStr = @"[{\"version\":\"20220111\",\"caid\":\"912ec803b2ce49e4a541068d495ab570\"},{\"version\":\"20211207\",\"caid\":\"e332a76c29654fcb7f6e6b31ced090c7\"}]";
[instance initializeGravityEngineWithClientId:@"" withCaidInfo:caidStr withSyncAttribution:NO withChannel:@"appstore" withAdData:@{@"testAdKey":@"testAdValue"} withSuccessCallback:^(NSDictionary * _Nonnull response) {
NSLog(@"gravity engine initialize success, response is %@", response);
} withErrorCallback:^(NSError * _Nonnull error) {
NSLog(@"gravity engine initialize failed, and error is %@", error);
}];
```
参数说明：
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | ------------------------------------------------------------------------------------------- | -------- | ---- |
| ENABLE\_ASA | 是否开启 ASA 广告归因，传 YES 则开启，引力会自动获取 ASA 归因信息，传 NO 则引力不会获取。5.0.24版本已移除，改为默认采集 | bool | 是 |
| USER\_CLIENT\_ID | 当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串） | NSString | 是 |
| CAID\_STR | 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串)。已支持20250325，20260506版本 | NSString | 是 |
| ENABLE\_SYNC\_ATTRIBUTION | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | bool | 是 |
| CHANNEL | 当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore | NSString | 是 |
| adData | 预设归因信息 | object | 否 |
> * **首次调用后，需要等 `CallbackWithSuccess` 回调成功之后，才能继续调用后续的事件上报方法**
> * **调用成功之后，后续冷启动可以不再调用初始化，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）**
> * **以上字符串参数无值时，请传入空字符串，不要传入 `nil`**
### 4.3 最佳实践（推荐） [#43-最佳实践推荐]
引力 sdk 内部在采集 `idfa` 数据之前，会尝试弹出 [App Tracking Transparency(ATT)许可弹窗](https://developer.apple.com/documentation/apptrackingtransparency) （如果之前已经弹出过，则不会重新弹出，会自动复用之前的用户选择），用户点击允许之后，才可以采集到 `idfa` ，引力已经兼容了 iOS14 系统之前和 iOS14 系统之后获取 `idfa` 的代码（引力 ios sdk 5.0.8 及以上支持，unity sdk 5.0.22 及以上支持），并在无论是否获取到 `idfa` 时，都会继续调用引力 SDK 的 `initialize` 函数完成初始化调用。
我们推荐您通过 `withClientId` 传入空字符串，这样引力 sdk 内部会自动获取当前 app 的 `version`、`idfa`、`idfv`，并将首次获取的 `idfv` 保存到keychain中，保证当前设备后续卸载重装之后，能始终获取到最初的 `idfv`，并将这个稳定的 `idfv` 作为 client id 传给引力后台作为唯一用户 ID；
在[混合上报](/docs/client-sdk/hybrid-reporting)的场景下，如您需要获取当前用户的 `clientId`，您可以调用 `getCurrentClientId` 方法获取；代码示例如下：
```objective-c
// instance 为启动 SDK 时获取的引力实例对象
NSString *clientId= [instance getCurrentClientId];
```
SDK 获取 version 的逻辑为：采集 `CFBundleVersion` 字符串，并将小数点去除转换为 int 类型上报给引力后台，代码示例如下；
```objective-c
NSString *buildVersion = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleVersion"];
```
## 5. 事件上报 [#5-事件上报]
### 5.1 业务注册事件上报 [#51-业务注册事件上报]
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 方法示例 [#方法示例]
```objective-c
- (void)trackRegisterEvent;
```
#### 调用示例 [#调用示例]
```objective-c
[instance trackRegisterEvent];
```
```swift
instance?.trackRegisterEvent();
```
### 5.2 付费事件上报 [#52-付费事件上报]
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```objective-c
- (void)trackPayEventWithAmount:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;
```
#### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | NSString | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | NSString | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | NSString | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | NSString | 是 |
#### 调用示例 [#调用示例-1]
```objective-c
[instance trackPayEventWithAmount:1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"月卡" withPayMethod:@"支付宝"];
```
```swift
instance?.trackPayEvent(withAmount: 1000, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "月卡", withPayMethod: "支付宝");
```
### 5.3 广告观看事件上报 [#53-广告观看事件上报]
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```objective-c
- (void)trackAdShowEventWithUninType:(NSString *)adUnionType withPlacementId:(NSString *)adPlacementId withSourceId:(NSString *)adSourceId withAdType:(NSString *)adType withAdnType:(NSString *)adAdnType withEcpm:(NSNumber *)ecpm;
```
#### 参数说明 [#参数说明-1]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| adUnionType | 广告聚合平台类型 （取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合） | NSString | 否 |
| adPlacementId | 广告瀑布流ID（广告位ID） | NSString | 否 |
| adSourceId | 广告源ID（代码位ID） | NSString | 否 |
| adType | 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video\_feed(视频信息流)、video\_begin(贴片广告)） | NSString | 是 |
| adnType | 广告平台类型（取值为：csj、gdt、ks、 mint 、baidu、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台） | NSString | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） 请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | NSNumber | 建议填写 |
#### 调用示例 [#调用示例-2]
```objective-c
[instance trackAdShowEventWithUninType:@"topon" withPlacementId:@"placement_id" withSourceId:@"ad_source_id" withAdType:@"reward" withAdnType:@"csj" withEcpm:@1000];
```
```swift
instance?.trackAdShowEvent(withUninType: "topon", withPlacementId: "placement_id", withSourceId: "ad_source_id", withAdType: "reward", withAdnType: "csj", withEcpm: 1000);
```
### 5.4 提现事件上报 [#54-提现事件上报]
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```objective-c
- (void)trackWithdrawEvent:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | NSString | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必传入！ | NSString | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | NSString | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | NSString | 是 |
#### 调用示例 [#调用示例-3]
```objective-c
[instance trackWithdrawEventWithAmount:@1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"用户首次提现" withPayMethod:@"支付宝"];
```
```swift
instance?.trackWithdrawEvent(withAmount: 300, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "用户首次提现", withPayMethod: "支付宝");
```
## 6. 接入验证 [#6-接入验证]
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ----------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件** 方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> 至此验证无误之后，您可以正常上线了。