快速集成

本文档为iOS接入 引力引擎 的技术接入方案，在开始接入前，建议您先阅读 接入前准备以了解接入必备的基础概念。

1. 获取 AccessToken和产品 ID

您可以在设置-应用管理页面点击 查看参数 按钮获取当前应用的 AccessToken和产品 APP_ID ，请妥善保存避免泄露。

2.集成引力引擎 SDK

2.1 CocoaPods 自动集成

1. 创建并编辑 Podfile 内容（如果已有，直接编辑）：

创建 Podfile，项目工程（.xcodeproj）文件同目录下命令行执行命令：

pod init

编辑 Podfile 的内容如下：

platform :ios, '9.0'
target 'YourProjectTarget' do
  pod 'GravityEngineSDK'
end

2.执行安装命令

pod install

导入成功，启动工程

命令执行成功后，会生成 .xcworkspace 文件，说明您已成功导入 iOS SDK。打开 .xcworkspace 文件以启动工程（注意：此时不能同时开启 .xcodeproj 文件）

2.2 手动集成 SDK

下载并解压最新 iOS SDK 包，您可以在SDK下载页获取最新版本 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 需要）

以上依赖项，必须全部添加，否则会导致编译失败！

3. 配置并启动 SDK

Objective-C

GEConfig *config = [GEConfig new];
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
[GravityEngineSDK startWithConfig:config];
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];

// 开启自动采集
[instance enableAutoTrack:GravityEngineEventTypeAll];

let config = GEConfig();
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";

GravityEngineSDK.start(with: config);
let instance = GravityEngineSDK.sharedInstance(withAppid: config.appid);

// 开启自动采集
instance?.enableAutoTrack(GravityEngineAutoTrackEventType.eventTypeAll);

参数说明：

• APP_ID : 在第一步中获取的项目通行证 APP_ID
• ACCESS_TOKEN : 在第一步中获取的项目通行证 AccessToken

应用每次启动都要执行 SDK 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。

请一定注意，要按照文档要求，开启自动采集，否则可能会导致买量问题！

4.初始化

在用户可以获取到用户唯一性 ID 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。

4.1 添加 att 弹窗描述

需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致  idfa  获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！

<key>NSUserTrackingUsageDescription</key>
<string>此标识符将用于向您推荐个性化广告。</string>

4.2 调用引力初始化

注意：请确保用户已经同意网络授权弹窗之后，才能调用引力初始化接口，如果提前调用，将因为网络不通导致初始化失败！导致首次启动归因失败！

[instance initializeGravityEngineWithAsaEnable:ENABLE_ASA withClientId:USER_CLIENT_ID withCaid1:USER_CAID1_MD5 withCaid2:USER_CAID2_MD5 withSyncAttribution:ENABLE_SYNC_ATTRIBUTION withChannel:CHANNEL 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);
}];

参数说明：

• 首次调用后，需要等 CallbackWithSuccess 回调成功之后，才能继续调用后续的事件上报方法
• 调用成功之后，后续冷启动可以不再调用初始化，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
• 以上字符串参数无值时，请传入空字符串，不要传入nil

4.3 最佳实践（推荐）

引力 sdk 内部在采集 idfa 数据之前，会尝试弹出 App Tracking Transparency(ATT)许可弹窗 （如果之前已经弹出过，则不会重新弹出，会自动复用之前的用户选择），用户点击允许之后，才可以采集到  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；

// instance 为启动 SDK 时获取的引力实例对象
NSString *clientId= [instance getCurrentClientId];

NSString *buildVersion = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleVersion"];

- (void)trackRegisterEvent;

[instance trackRegisterEvent];

instance?.trackRegisterEvent();

- (void)trackPayEventWithAmount:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;

[instance trackPayEventWithAmount:1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"月卡" withPayMethod:@"支付宝"];

instance?.trackPayEvent(withAmount: 1000, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "月卡", withPayMethod: "支付宝");

- (void)trackAdShowEventWithUninType:(NSString *)adUnionType withPlacementId:(NSString *)adPlacementId withSourceId:(NSString *)adSourceId withAdType:(NSString *)adType withAdnType:(NSString *)adAdnType withEcpm:(NSNumber *)ecpm;

[instance trackAdShowEventWithUninType:@"topon" withPlacementId:@"placement_id" withSourceId:@"ad_source_id" withAdType:@"reward" withAdnType:@"csj" withEcpm:@1000];

instance?.trackAdShowEvent(withUninType: "topon", withPlacementId: "placement_id", withSourceId: "ad_source_id", withAdType: "reward", withAdnType: "csj",withEcpm:1000);

- (void)trackWithdrawEvent:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;

[instance trackWithdrawEventWithAmount:@1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"用户首次提现" withPayMethod:@"支付宝"];

instance?.trackWithdrawEvent(withAmount: 300, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "用户首次提现", withPayMethod: "支付宝");