一、说明
1.适用范围
热云TrackingIO作为国内第三方移动广告监测平台，能够更好的帮助广告主更精准的评估每次广告投放效果，以及帮助广告网络做广告系统的投放优化或业务数据的完善。
本文档适用于iOS 9.0及以上的操作系统。
2.SDK下载
- 下载地址
- 最新SDK版本为：1.9.11
- 更新日期：2023.01.31
- 更新内容：
修复获取到error字符串问题
3.统计说明
为了能够在接入过程中保持概念统一，针对通用概念做如下说明：
- 设备
指某台安装了IOS应用的终端，例如iPhone、iPad、iTouch等。
- 账号
指用户在某台设备上安装了应用之后，在应用中的唯一标识。
通常用作账号的标识符可以是用户注册应用时的唯一用户名（如邮件地址），也可以是用户注册时自动生成的唯一字符串。
二、接入流程
1.申请APPKEY
1)打开https://new.trackingio.com，使用您的热云账号进行登录。
2)进入“产品中心”，点击左上方**“新建应用”**，完成产品创建，您将获得一串32位的16进制APPKEY；
如果您已经完成产品创建，请在如下位置获取APPKEY：全部产品按钮”-“对应产品”-APPKEY
APPKEY为应用的唯一标识，用于集成到SDK中。
注：为了保证您的数据安全,请勿泄露您的APPKEY。
2.导入SDK
1)前往SDK下载地址，下载SDK压缩包，解压至本地目录。
2)将目录中的全部文件和文件夹导入到您的工程中。
导入方法：在工程目录结构中，右键选择Add->Existing Files...，选择全部文件及文件夹（或将文件拖入Xcode工程目录结构中）文件，在弹出的界面中勾选Copy items into destination group's folder(if needed)，并确保Add To Targets勾选相应target。
3.接入SDK
- 详见“三、接入方法说明”
4.测试
1)在开发环境中进行Debug测试：
+(void) setPrintLog :(BOOL)print;
注：热云SDK所有API接口的http response均以status：0表示成功
2)进入热云调试页面查看调试数据：
“全部产品” - “待调试产品”–“调试”
三、接入方法说明
1.添加SDK所需依赖框架
(1) 添加必要的系统库文件：
使用Security.framework来存储设备标识,
使用CoreTelephony.framework来获取运营商信息,
使用AdSupport.framework来获取Advertising Identifier信息,
使用SystemConfiguration.framework来检查当前网络环境,
使用CoreMotion.framework来获取陀螺仪数据
使用libsqlite3.dylib用来存储数据。
使用iAd.framework、AdServices.framework(optional形式引入)、AVFoundation.framework来获取数据。
使用libz.tbd来压缩数据。
使用libresolv.9.tbd来获取相关信息。
使用libresolv.tbd来获取相关信息。
使用libc++.tbd来获取相关信息。
使用CFNetwork.framework来获取相关信息。
使用WebKit.framework来获取相关信息。
- 添加方法：
在工程目录中,选择
TARGETS-->Build Phases-->Link Binary With Libraries-->+ -->选择Security.framework、CoreTelephony.framework、AdSupport.framework、libsqlite3.dylib、iAd.framework 、AdServices.framework(optional形式引入)、AVFoundation.framework、libz.tbd、libresolv.tbd、CFNetwork.framework、WebKit.framework、libresolv.9.tbd、libc++.tbd、SystemConfiguration.framework、CoreMotion.framework等库文件。
新版xcode .dylib以.tbd为后缀，添加对应动态库。
注：
1)如上动态库请全部配置，避免报错。
2)xcode 7及以上版本，.dylib后缀结尾的系统库均更改为.tbd后缀结尾
(2) 关闭bitcode：
选择⼯程-> Build Settings -> 搜索bitcode ->设置为NO
2.ASA接口开关
1)如需投放ASA，请在初始化接口之前调用：
+(void) setASAEnable :(BOOL)enable;
3.MobDNA接口开关
1)是否关闭或开启MobDNA防作弊，请在初始化接口之前调用：
+(void) setMobDNAEnable :(BOOL)enable;
注：是否开启MobDNA防作弊，主动调用传入false关闭，默认开启.
4.初始化热云SDK
- 方法用途：
用于应用启动后，初始化热云SDK。报送应用安装或启动事件。
- 使用方法：
在application:didFinishLaunchingWithOptions方法中调用
+ (void)initWithAppKey:(NSString *)appKey withChannelId:(NSString *)channelId withCAID:(nullable NSString *)caid
withCAID2:(nullable NSString *)caid2 withMobDNAOid:(nullable NSString *)oid withParams:(nullable NSDictionary *)customParams;方法进行初始化
- 方法接口：
+ (void)initWithAppKey:(NSString *)appKey withChannelId:(NSString *)channelId withCAID:(nullable NSString *)caid
withCAID2:(nullable NSString *)caid2 withMobDNAOid:(nullable NSString *)oid withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| appkey | NSString* | 是 | 32位 | 创建产品时获得的32位字符长度的APPKEY |
| channelId | NSString* | 是 | 最长64位 | 填写_default_ |
| caid | NSString* | 否 | 最长64位 | 当前版本的中国广告协会互联网广告标识；如果无法获取caid的值，则传nil |
| caid2 | NSString* | 否 | 最长64位 | 上一版本的中国广告协会互联网广告标识；如果无法获取caid2的值，则传nil |
| oid | NSString* | 否 | 最长64位 | 热云mobdna反作弊SDK需要参数，如果无法获取oid的值，则传nil |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
#import “Tracking.h”
-(BOOL)application:(UIApplication *)applicationdidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[Tracking initWithAppKey:@"53807f356112863846c689afde503752" withChannelId:@"_default_" withCAID:nil
withCAID2:nil withMobDNAOid:nil withParams:@{@"param1":@"initvalue"}];
}
5.统计用户注册数据
- 方法用途：
用于用户注册完成，报送应用注册事件。
- 使用方法：
在用户注册完成时调用Tracking setRegisterWithAccountID:withParams:方法。
如果开发者没有自己的用户系统，希望使用用户设备ID作为accountId，直接调用Tracking.getDeviceId()方法获取设备ID即可。
注意该方法一定要在调用初始化接口之后间隔5s以上再使用，否则会影响取值。
- 方法接口：
+ (void)setRegisterWithAccountID:(NSString *)account withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| account | NSString | 是 | 最长64位 | 账号唯一标识，仅支持英文、数字、下划线 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking setRegisterWithAccountID:@"Tracking Account 01" withParams:@{@"param1":@"regvalue"}];
6.统计用户登录数据
- 方法用途：
用于用户登录完成、切换账号时，报送应用登录事件。
- 使用方法：
调用Tracking setLoginWithAccountID:withParams:方法。
- 方法接口：
+ (void)setLoginWithAccountID:(NSString *)account withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| account | NSString | 是 | 最长64位 | 账号唯一标识，仅支持英文、数字、下划线 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking setLoginWithAccountID:@"TrackingAccount01" withParams:@{@"param1":@"loginvalue"}];
7.统计用户订单数据
- 方法用途：
用于用户提交订单后，统计订单数据。
- 使用方法：
用户提交订单后调用Tracking setDD方法。
- 方法接口：
+(void)setDD:(NSString *)ryTID hbType:(NSString*)hbType hbAmount:(float)hbAmount withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| ryTID | NSString | 是 | 最长64位 | 交易流水号，请务必确保唯一。 |
| hbType | NSString | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| hbAmount | float | 是 | 最长16位 | 订单的真实货币金额，人民币单位：元 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
示例代码：
[Tracking setDD:@"trans-id-123"hbType:@"CNY"hbAmount:12.5 withParams:@{@"param1":@"ordervalue"}];
8.统计用户充值成功数据（建议使用服务器REST报送）
- 方法用途：
用于用户充值成功，统计充值数据，所有付费相关分析的数据报表均依赖此方法。
注：前端报送支付有掉单风险，收入数据会出现误差，为确保支付数据准确，建议使用服务器报送支付（请参考“REST”文档）。
- 使用方法：
用户充值成功且后端发货成功后调用Tracking setRyzf方法。
- 方法接口：
+(void)setRyzf:(NSString *)ryTID ryzfType:(NSString*)ryzfType hbType:(NSString*)hbType hbAmount:(float)hbAmount withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| ryTID | NSString | 是 | 最长64位 | 付费数据按此参数排重，交易流水号，请务必确保唯一。。 |
| ryzfType | NSString | 是 | 最长16位 | 支付类型，例如支付宝(alipay)，银联(unionpay)，微信支付（weixinpay）,易宝支付（yeepay），paymentType不能填写：FREE（FREE不统计付费） |
| hbType | NSString | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| hbAmount | float | 是 | 最长16位 | 支付的真实货币金额，人民币单位：元 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking setRyzf:@"trans-id-123"ryzfType:@"alipay"hbType:@"CNY"hbAmount:12.5 withParams:@{@"param1":@"paymentvalue"}];
9.统计广告展示事件
- 方法用途：
当App内的变现广告被展示时调用此方法进行事件上报。 - 方法接口：
+(void)onAdShow:(NSString *)adPlatform adId:(NSString *)adId isSuccess:(int)playSuccess withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| adPlatform | String | 是 | 最长16位 | 填充广告的变现平台(传括号中的值)： 穿山甲(csj)、 优量汇(ylh)、 百青藤(bqt)、 快手(ks)、 Sigmob(sigmob)、 Mintegral(mintegral)、 OneWay(oneway)、 Vungle(vungle)、 Facebook(facebook)、 AdMob(admob)、 UnityAds(unity)、 IronSource(is)、 AdTiming(adtiming)、 游可赢(klein) |
| adId | String | 是 | 最长32位 | 填充广告在变现平台的广告位ID。 注意：若您使用聚合平台且需要通过聚合平台API获取收入时，需传聚合平台对应的值，TopOn传“adsource_id”；AdTiming传“placementId”；TradPlus传“placementId”；GroMore传“ad_unit_id” |
| playSuccess | int | 是 | 最长1位 | 本次展示广告是否填充成功，1成功、2失败，无法确定填充是否成功时，请传1 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking onAdShow:@"csj" adId:@"aid123456" isSuccess:1 withParams:@{@"param1":@"adshowvalue"}];
10.统计广告点击事件
- 方法用途：
当App内的变现广告被点击时调用此方法进行事件上报。 - 方法接口：
+(void)onAdClick:(NSString *)adPlatform adId:(NSString *)adId withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| adPlatform | String | 是 | 最长16位 | 填充广告的变现平台(传括号中的值)： 穿山甲(csj)、 优量汇(ylh)、 百青藤(bqt)、 快手(ks)、 Sigmob(sigmob)、 Mintegral(mintegral)、 OneWay(oneway)、 Vungle(vungle)、 Facebook(facebook)、 AdMob(admob)、 UnityAds(unity)、 IronSource(is)、 AdTiming(adtiming)、 游可赢(klein) |
| adId | String | 是 | 最长32位 | 填充广告在变现平台的广告位ID。 注意：若您使用聚合平台且需要通过聚合平台API获取收入时，需传聚合平台对应的值，TopOn传“adsource_id”；AdTiming传“placementId”；TradPlus传“placementId”；GroMore传“ad_unit_id” |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking onAdClick:@"csj" adId:@"adid123456" withParams:@{@"param10":@"adclickvalue"}];
11.统计App使用时长事件
- 方法用途：
监测APP使用时长。
TrackingIO SDK提供的是手动计算方案，即您需要自行计算使用时长，并将计算的时长按照下方的方法上报。 - 推荐的时长计算方法：
1.进入前台时记一个时间T1；
2.置于后台时记一个时间T2，则本次在前台的时长duration1=T2-T1；
3.再次进入前台时记一个时间T3，T3-T2=置于后台的时间（需要统计后台时间就算这个数，不需要的话就不算）；
4.强制杀掉app时，会有上滑动作，上滑时记录时间T4，在杀掉app的情况下，本次在前台的时长duration2=T4-T3。 - 方法接口：
+(void)setTrackAppDuration:(long)duration withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| duration | long | 是 | 传入APP启动到结束运行的时间长度，单位为秒（s） | |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking setTrackAppDuration:20 withParams:@{@"param1":@(1213)}];
12.统计App内页面浏览时长事件
- 方法用途：
监测App内页面浏览时长 - 方法接口：
+(void)trackViewName:(NSString *)pageID duration:(long)duration withParams:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| pageID | NSString | 是 | 最长64位 | pageID代表页面唯一标识，请确保pageID的唯一性 |
| duration | long | 是 | 页面展示时长，单位秒(s) | |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
[Tracking trackViewName:@"mainview" duration:10 withParams:@{@"param2":@(456)}];
13.统计用户自定义事件
- 方法用途：
用于统计用户在应用内的任意行为，如打开某个面板、点击某个Button、参与某个活动等。
- 使用方法：
在自定义用户行为的地方，调用Tracking setEvent方法。
- 方法接口：
+(void)setEvent:(NSString *)eventName param:(nullable NSDictionary *)customParams;
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| eventName | NSString* | 是 | 最长32位 | 自定义事件名称，必须为event_1到event_30 |
| customParams | NSDictionary * | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
注：
1.eventName必须为event_1到event_30
2. params为自定义事件上报的自定义参数，仅支持param1-param10
3. 如需使用快手关键行为回传，请严格按照以下文档将指定参数上传至param1、param2中，自定义参数名称固定
4. 如需投放穿山甲LTV指标，请严格按照以下文档将LTV值上传至param3中
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| param1 | String | 快手关键行为必传 | 最长10位 | 根据行为类型回传对应枚 举值）：1 广告观看/2 通过关 卡/3 游戏时长/4 LTV/0 其他 Eg:param1=1 |
| param2 | String | 快手关键行为必传 | 最长10位 | 根据关键行为定义的次数/ 数量/等级回传具体数值 Eg:param2=15 |
| param3 | String | 投放穿山甲LTV必传 | 最长32位 | 针对穿山甲渠道回传所用到的ltv0值，同一设备24小时内产生的ltv累加值。例如：当前广告展示收益ltv0=5;则上报param3=5，单位为分。关于LTV累加值详情可参考文档：https://bytedance.feishu.cn/docs/doccnJubvtVfwztRJn98uihfsWh#LM2k80 |
- 示例代码：
NSDictionary *dict = @{
@"param1":@"aaa",@"param2":@"bbb",
};
[Tracking setEvent:@"event_1" param:dict];
14.获取设备ID
- 方法用途：
用于获取唯一设备标识符。
- 使用方法：
调用getDeviceid方法，用以获取唯一设备标识符
方法接口：
+(NSString*)getDeviceId;
- 注：
1)该接口返回首次调用initWithAppKey: withChannelId:函数时获取的系统idfa（当用户未允许App请求跟踪时，获取的为系统idfv的值，具体格式为deviceid=IFV_(idfv)），只要安装过应用且调用过初始化函数，通过该接口返回的字符串基本不会变化（包括删除APP,重置idfa，开启、关闭广告追踪等操作），此值作为首次安装设备标识符参考。
2)如需获取实时idfa，请勿使用该接口，用户需自行通过系统函数获取。
15.技术支持
如有任何问题，请及时联系我们的技术支持工程师：
技术支持邮箱：support@reyun.com
技术支持QQ：2785608528