菜单

快速集成

本文档为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（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";
config.debugMode = GravityEngineDebugOn;
[GravityEngineSDK startWithConfig:config];
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];

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

参数说明：

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

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

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

4.初始化

建议在用户同意网络授权弹窗，然后同意隐私协议弹窗并向用户展示过 App Tracking Transparency(ATT)许可弹窗 弹窗之后，无论用户是否允许 ATT 追踪，都要执行引力的初始化逻辑。

具体接入步骤如下：

4.1 iOS14 之前系统获取 idfa

1.导入框架

#import <AdSupport/ASIdentifierManager.h>

2.获取广告标识

// iOS14以下版本继续使用老方法
// 判断在设置-隐私里用户是否打开了广告跟踪
if ([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]) {
   NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
   NSLog(@"%@",idfa);
} else {
   NSLog(@"用户未在设置-隐私中开启广告追踪，无法获取idfa");
}

4.3 调用引力初始化

[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);
}];

参数说明：

参数名称 参数含义 参数类型 是否必传
ENABLE_ASA  是否开启 ASA 广告归因，传 YES 则开启，引力会自动获取 ASA 归因信息，传 NO 则引力不会获取。 bool 是
USER_CLIENT_ID  当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串） NSString 是
USER_CAID1_MD5  当前用户中广协 ID 的 md5 hash（20230330 版本）（可为空字符串） NSString 是
USER_CAID2_MD5  当前用户中广协 ID 的 md5 hash（20250325 版本）（可为空字符串） NSString 是
ENABLE_SYNC_ATTRIBUTION  是否开启同步获取归因信息，具体请参考同步归因 bool 是
CHANNEL  当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore NSString 是
  • 首次调用后，需要等 CallbackWithSuccess 回调成功之后，才能继续调用后续的事件上报方法
  • 调用成功之后，后续冷启动可以不再调用初始化，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
  • 以上字符串参数无值时，请传入空字符串，不要传入nil

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

4.4 最佳实践（推荐）

兼容 iOS14 系统之前和 iOS14 系统之后获取 idfa 的代码，并在无论是否获取到 idfa 时，都调用引力 SDK 的 initialize 函数完成初始化调用。

我们推荐您通过 withClientId 传入空字符串，这样引力将在 sdk 内部自动为您处理 clientId 的采集逻辑，此时会使用一个稳定的 idfv 值作为 clientId。

// 先获取idfa
if (@available(iOS 14, *)) {
   // iOS14及以上版本需要先请求权限（依赖ATT框架）
   [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
      // 获取到权限后，使用老方法获取idfa
      if (status == ATTrackingManagerAuthorizationStatusAuthorized) {
            NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
            NSLog(@"%@",idfa);
      } else {
            NSLog(@"当前用户未同意追踪或未在设置-隐私中开启广告追踪，无法获取idfa");
      }
      //无论是否获取到idfa 都要调用引力SDK initialize函数，SDK内部会尝试获取idfa，并处理idfa异常值
      [instance initializeGravityEngineWithAsaEnable:ENABLE_ASA withClientId:@"" 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);
      }];
   }];
} else {
   // iOS14以下版本继续使用老方法
   // 判断在设置-隐私里用户是否打开了广告跟踪
   if ([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]) {
      NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
      NSLog(@"%@",idfa);
   } else {
      NSLog(@"用户未在设置-隐私中开启广告追踪，无法获取idfa");
   }
   //无论是否获取到idfa 都要调用引力SDK initialize函数，SDK内部会尝试获取idfa，并处理idfa异常值
   [instance initializeGravityEngineWithAsaEnable:ENABLE_ASA withClientId:@"" 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);
   }];
}

在混合上报的场景下，如您需要获取当前用户的 clientId，您可以调用 getCurrentClientId 方法获取；代码示例如下：

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

采用最佳实践方案，并且传入的 clientId 字段为空字符串时，引力 sdk 内部会自动获取当前 app 的 version、idfa、idfv，并将首次获取的 idfv 保存到keychain中，保证当前设备后续卸载重装之后，能始终获取到最初的 idfv，并将这个稳定的 idfv 作为 client id 传给引力后台作为唯一用户 ID；

SDK 获取 version 的逻辑为：采集 CFBundleVersion 字符串，并将小数点去除转换为 int 类型上报给引力后台，代码示例如下；

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

5.事件上报

5.1 业务注册事件上报

如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。

该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）

当用户完成应用内业务注册后，您可以调用 trackRegisterEvent 方法来上报用户注册事件($AppRegister)给引力，引力会使用该事件统计指标：标准_注册数

方法示例

- (void)trackRegisterEvent;

调用示例

Objective-C

[instance trackRegisterEvent];

Swift

instance?.trackRegisterEvent();

5.2 付费事件上报

付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。

如果您需要通过后端 API 方式上报付费事件，请参考 混合上报模式 来接入事件上报接口报送付费事件。

当用户发生付费行为时，需要调用 trackPayEvent 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！

方法示例

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

5.3 广告观看事件上报

广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

方法示例

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

调用示例

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

5.4 提现事件上报

提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。

当用户发生应用内提现行为时，需要调用 trackWithdrawEvent 方法记录用户提现事件！

方法示例

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

调用示例

Objective-C

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

6.接入验证

正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！

6.1 开启 Debug 模式

开启 Debug 模式后，当出现问题时会以日志和异常的方式提示用户，您也可以去事件流中查看实时上报的数据数，辅助您判断数据接入是否正常。

以下是客户端开启 Debug 模式的示例代码:

Objective-C
GEConfig *config = [[GEConfig alloc] init];
config.debugMode = GravityEngineDebugOn;
// 初始化 SDK
GravityEngineSDK *instance = [GravityEngineSDK startWithConfig:config];

Debug 模式仅仅用于集成阶段数据校验，不要在生产模式下使用！上线前请关闭！

6.2 关键事件验证

在 SDK 中开启 Debug 模式，并在产品中触发以下几个事件。

事件名 事件英文名 触发时机 采集方式 默认映射到媒体事件 备注
用户注册 $AppRegister 用户完成业务注册之后 调用SDK的上报业务注册事件方法采集 暂无 接入了业务注册上报事件的产品均需要校验
付费 $PayEvent 用户付费之后 调用 SDK 的 上报用户付费事件 方法采集 付费 接入了付费事件上报事件的的产品均需要校验
广告展示 $AdShow 用户观看广告之后 调用 SDK 的 上报广告展示事件 方法采集 暂无 接入了广告事件上报事件的产品均需要校验

用户提现

 $UserWithdraw 用户提现之后 调用 SDK 的 上报用户提现事件 方法采集 暂无 接入了用户提现上报事件的产品均需要校验

测试完成之后，在 事件流 界面过滤测试用户的 Client ID ，查看对应事件的校验状态是否为 "校验通过" ，当事件有数据并且状态为校验通过后，则表明接入成功。

6.3 避免重复上报

如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！

至此验证无误之后，您可以正常上线了。

 

 

 

 

上一个
iOS
下一个
行为事件上报
最近修改: 2025-09-24Powered by