广点通转化 iOS SDK 开发指引

SDK 信息

SDK名称：广点通转化 SDK
开发者：深圳市腾讯计算机系统有限公司
版本号：2.1.0
主要功能：用于广告分析、营销分析
合规使用说明：https://datanexus.qq.com/doc/develop/compliance/android/compliance_guide
个人信息处理规则：https://datanexus.qq.com/doc/develop/compliance/android/privacy_policy

1 前置条件

1.1 完成 SDK 接入流程文档阅读

查看 SDK 接入流程。

1.2 拥有开发者账号

如未有开发者账号，请进入苹果开发者中心，点击左侧<Certificates, IDs & Profiles>菜单进入，在 App IDs 子菜单下创建 AppID。

1.3 SDK 要求的系统版本

SDK 要求最低系统版本为 iOS 11.0。

2 接入开发

2.1 下载 SDK

点击下载 iOS SDK 压缩包并解压，压缩包中的 LibGDTActionSDK-x.x.x.zip（注：x.x.x为SDK版本号）包含您的 App 需要嵌入的 SDK 文件，压缩包中的 GDTActionSDKSample 是我们提供的 SDK 接入示例工程。

2.2 导入SDK

这里以压缩包中的 GDTActionSDKSample 示例程序导入 SDK 为例。

1. 将 LibGDTActionSDK-x.x.x.zip 解压，获得静态库 libGDTActionSDK.a 文件及 GDTAction.h、GDTAction+convenience.h 两个头文件，添加到示例程序项目 lib 文件夹内。

2. 通过 xcode 开发工具，设置示例项目程序的 Build Setting中的Other Linker Flags 为 -ObjC、iOS Deployment Target为 11.0 以上。

3. 在需要调用 SD K方法上报行为数据的文件中导入 SDK 头文件。

#import 'GDTAction.h'
#import 'GDTAction_convenience.h'

2.3 初始化 SDK

1. 找到您的 App 的入口文件（AppDelegate.m）并导入 SDK 头文件。

#import 'GDTAction.h'
#import 'GDTAction_convenience.h'

2. App 入口文件的 didFinishLaunchingWithOptions 方法中调用 [GDTAction init] 方法进行初始化 SDK，允许SDK开始收集数据，方法入参为获取 数据源 ID 和密钥 。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /*
     * 请在App启动的时候调用初始化方法
     * 方法入参为见 数据源ID和密钥 文档
     */
    [GDTAction init:@"yourActionSetId" secretKey:@"yourSecretKey"];

    return YES;
}

2.4 启动 SDK

App 入口文件的 didFinishLaunchingWithOptions 方法中调用 [GDTAction start] 方法启动SDK（备注：SDK版本号>=2.1.0才需要调用start方法）。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /*
     * 请在App启动的时候调用初始化方法
     * 方法入参为步骤2获取的数据源ID和密钥
     */
    [GDTAction init:@"yourActionSetId" secretKey:@"yourSecretKey"];
    
    
    /*
     * SDK版本号>=2.1.0才需要调用start方法
     * 调用start方法前，请先调用init方法初始化SDK
     */
    [GDTAction start];

    return YES;
}

2.5 按行为清单埋点上报数据

在 App 内发生转化行为时，可以调用预定义上报方法或通用上报方法上报行为数据，传入行为类型名称和行为参数。每个预定义上报方法包含若干个行为参数（优化广告投放所需参数），建议优先使用预定义上报方法，若预定义上报方法无法满足上报需求时，则使用通用上报方法。

2.5.1 上报启动应用行为

1. 在 App 入口文件的 applicationDidBecomeActive 方法中调用 [GDTAction logAction] 方法上报 START_APP（启动应用）行为。

- (void)applicationDidBecomeActive:(UIApplication *)application {
    /*
     * 在应用启动的时候请上报GDTSDKActionNameStartApp行为
     * SDK内部会判断此次启动行为是否为激活行为并上报，开发者无需另外作判断逻辑
     */
    [GDTAction logAction:@"START_APP" actionParam:@{@"value":@(123)}];
}

2. 如果 App 是被第三方应用唤起，请在 App 入口文件的唤起回调方法中调用 [GDTAction logAction] 方法上报 START_APP（应用启动）行为，并将 openURL 链接传入行为参数 actionParam 对象中。

-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    /*
     * 在应用被呼起的时候请上报GDTSDKActionNameStartApp行为，并带上呼起的openURL链接
     */
    [GDTAction logAction:@"START_APP" actionParam:@{@"open_url":url.absoluteString}];
    
    return YES;    
}

2.5.2 预置行为

• TICKET（心跳）
• ENTER_FOREGROUND（APP进入前台）
• ENTER_BACKGROUND（APP退到后台）

以上 3 种行为无需您手动上报。

2.5.3 预定义上报方法

方法名	功能
+ (void)reportRegisterActionWithMethod:(NSString *)method isSuccess:(BOOL)isSuccess	用户注册完成时调用此接口 @param method 表示注册方式，业务方可以传任意可标识注册方式的值，如注册方式为手机号（method = @"phone" ）、微信注册（method = @“WeChat” ）、邮箱（method = @"mail"）等；方便业务方在数据平台以method为key查询数据 @param isSuccess 是否注册成功
+ (void)reportLoginActionWithMethod:(NSString *)method isSuccess:(BOOL)isSuccess	用户登录完成时调用此接口 @param method 表示登录的方式，如游戏账号、手机号等 @param isSuccess 是否登录成功
+ (void)reportBindSocialAccountActionWithType:(NSString *)type isSuccess:(BOOL)isSuccess	绑定社交账户时调用此接口 @param type 社交账号类型 如如微信、微博等 @param isSuccess 是否绑定成功
+ (void)reportFinishQuestActionWithQuestID:(NSString )questID questType:(NSString )type questName:(NSString )name questNumer:(NSUInteger)number description:(NSString )desc isSuccess:(BOOL)isSuccess	完成节点（如教学/任务/副本）时调用此接口 @param questID 教学/任务/副本等关卡标识符 @param type 节点类型 @param name 教学/任务/副本等关卡名称 @param number 第几个任务节点 @param desc 节点描述 @param isSuccess 节点是否完成
+ (void)reportCreateRoleActionWithRole:(NSString *)role	用户创建游戏角色后调用此接口 @param role 游戏角色
+ (void)reportUpgradeLevelActionWithLevel:(NSUInteger)level	用户升级后调用此接口 @param level 当前用户等级
+ (void)reportViewContentActionWithContentType:(NSString )type contentName:(NSString )name contentID:(NSString *)contentID	查看内容/商品详情时调用此接口 @param type 内容类型如“配备”、“皮肤” @param name 商品或内容名称 @param contentID 商品或内容标识符
+ (void)reportAddingToCartActionWithContentType:(NSString )type contentName:(NSString )name contentID:(NSString *)contentID contentNumber:(NSUInteger)number isSuccess:(BOOL)isSuccess	加入购物车时调用此接口 @param type 内容类型如“配备”、“皮肤” @param name 商品或内容名称 @param contentID 商品或内容标识符 @param number 商品数量 @param isSuccess 加入购买/购物车是否成功
+ (void)reportCheckoutActionWithContentType:(NSString )type contentName:(NSString )name contentID:(NSString )contentID contentNumber:(NSUInteger)number isVirtualCurrency:(BOOL)isVirtualCurrency virtualCurrencyType:(NSString )virtualCurrencyType realCurrencyType:(NSString *)realCurrencyType isSuccess:(BOOL)isSuccess	提交购买/下单时调用此接口 @param type 内容类型如“配备”、“皮肤" @param name 商品或内容名称 @param contentID 商品或内容标识符 @param number 商品数量 @param isVirtualCurrency 是否使用的是虚拟货币 @param virtualCurrencyType 虚拟货币类型，如"元宝"、“金币”等 @param realCurrencyType 真实货币类型，ISO 4217代码，如：“USD” @param isSuccess 提交购买/下单是否成功
+ (void)reportPurchaseActionWithContentType:(NSString )type contentName:(NSString )name contentID:(NSString )contentID contentNumber:(NSUInteger)number paymentChannel:(NSString )channel realCurrency:(NSString *)realCurrency currencyAmount:(unsigned long long)amount isSuccess:(BOOL)isSuccess	支付时调用此接口 @param type 内容类型如“配备”、“皮肤” @param name 商品或内容名称 @param contentID 商品或内容标识符 @param number 商品数量 @param channel 支付渠道名，如支付宝、微信等 @param realCurrency 真实货币类型，ISO 4217代码，如：“USD” @param amount 本次支付的真实货币的金额 @param isSuccess 支付是否成功
+ (void)reportAddPaymentChannelActionWithChannel:(NSString *)channel isSuccess:(BOOL)isSuccess	添加支付渠道时调用此接口 @param channel 支付渠道名，如支付宝、微信支付等 @param isSuccess 添加支付渠道是否成功
+ (void)reportRateActionWithRate:(CGFloat)rate	对APP进行应用商店评分时调用此接口 @param rate 评分
+ (void)reportShareActionWithChannel:(NSString *)channel isSuccess:(BOOL)isSuccess	分享至社交媒体时调用此接口 @param channel 社交媒体 @param isSuccess 分享是否成功

2.5.4 通用上报方法

方法名	功能
+(void)logAction:(NSString )actionName actionParam:(NSDictionary )actionParam	行为上报方法 @param actionName : 行为类型名，系统支持的actionName如下 a @param actionParam : 行为参数，actionParam格式如下 b

a. 行为类型（ActionType）

全量 行为枚举值。

b. 行为参数（ActionParam）

• 行为参数是 "Key-Value" 类型；Key 只可以为 String 类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过255；Value可以是 String/Number/Boolean/JSONArray 其中一种，当 Value 为 JSONArray 时，它的元素只能为 String/Number/Boolean 中的一种，且所有元素必须是同一个类型。
• 广告主在调用上报 START_APP 行为时，SDK 会自主判断此次行为是否为激活行为。若广告主需要自主控制上报激活启动行为时，可以在 ActionParam 中设置 audience_type 的 Key，Value 为 1。当带有该标识的启动行为上报时，我们会默认此次行为为老客户的应用启动行为。
• 广告主在上报时需要做自定义去重时可以在 ActionParam 中设置 outer_action_id 的 Key，value 为任意自定义如订单号的字符串作为自定义去重id，系统会根据该 id 进行去重。
• 当用户需要指定上报用户次日留存指标时，可以在上报 START_APP 行为时，在 ActionParam 中设置 length_of_stay 的 key，值为1，系统会指定该次上报为留存数据。

分行业上报行为类型和行为参数规范

为优化广告投放效果，不同行业需上报特定的行为类型，且需携带对应行为的相关参数。如 转化归因 - 金融 - 保险行业接入规范 。

2.6 获取设备 CAID

备注：SDK版本号 ≥ 2.0.11才支持该功能。

（1）在需要调用 SDK 方法获取CAID的文件中导入 SDK 头文件。

#import 'GDTAction.h'

（2）调用 SDK 方法获取 CAID 。

NSDictionary *caidDic = [GDTAction getCaid];
/*
 * 以下内容为caidDic对应数据格式，里面的data值为设备的CAID：
 * {
 *      "data": [
 *          { "value": "5ad74747f0e7eaadf159f4b9424e752f", "version": "20220111" },
 *          { "value": "3b4eedfb7e74c4517c95078d705dc2de", "version": "20230330" }
 *      ],
 *      "code": 0,
 *      "message": "OK"
 * }
 */

FAQ

Q：SDK上报数据接口（a.gdt.qq.com/sdk）返回 code 码 51000

A：当开发者使用模拟器运行App通过SDK上报数据时，服务端会对上报的数据做检测，判断该数据为无效数据，接口返回 code 码 51000。

Q：按照以上步骤接入SDK后，抓包工具未发现上报数据接口请求记录

A：检查本地电脑是否有安装网络拦截工具，如果有，请查看是否有拦截SDK上报数据接口，或者直接关闭网络拦截工具并重新运行App查看SDK上报数据接口是否请求正常。

该内容是否有帮助？