IOS_SDK_接入说明文档

一、说明

1.适用范围

热云TrackingIO作为国内第三方移动广告监测平台,能够更好的帮助广告主更精准的评估每次广告投放效果,以及帮助广告网络做广告系统的投放优化或业务数据的完善。

本文档适用于IOS 7.0及以上的操作系统。

2.SDK下载

3.统计说明

为了能够在接入过程中保持概念统一,针对通用概念做如下说明:

  • 设备

指某台安装了IOS应用的终端,例如iPhone、iPad、iTouch等。

  • 账号

指用户在某台设备上安装了应用之后,在应用中的唯一标识。

通常用作账号的标识符可以是用户注册应用时的唯一用户名(如邮件地址),也可以是用户注册时自动生成的唯一字符串。

二、接入流程

1.申请APPKEY

1)打开https://www.trackingio.com,使用您的热云账号进行登录。

2)进入“产品中心”,点击左上方**“+新建产品”**,完成产品创建,您将获得一串32位的16进制APPKEY;

如果您已经完成产品创建,请在如下位置获取APPKEY:全部产品按钮”-“对应产品”-APPKEY

APPKEY为应用的唯一标识,用于集成到SDK中。

注:为了保证您的数据安全,请勿泄露您的APPKEY。

2.导入SDK

1)前往SDK下载地址下载SDK压缩包,解压至本地目录。

2)将目录中的ReYunTracking.a和Tracking.h导入到您的工程中。

导入方法:在工程目录结构中,右键选择Add->Existing Files...,选择ReYunTracking.a和Tracking.h(或将文件拖入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表示成功

返回值错误信息
status:100context can not be null !
status:101param can not be null !
status:102appid can only contain 32 letters or numbers !
status:103context No more than 96 keys !
status:104context param can not be null !
status:105This ip was intercepted !
status:106tkio debug mode without this appid !
status:107tkio debug appid the total num is over 1000 !
status:108batch restful data can not be null !
status:109what can not be null !
status:110batch data request error !
status:111method not support !
status:112Content type is not validated! Please set Content-Type application/json !
status:113The data you send decrypt error !
status:114The data you send can not be null !
status:115The data you send is not a validated json !
status:116system error !
status:117param length invalid !
status:118_currencyamount param must be float !
status:119event1-event12 _isreyundefaultevent param must be equal 1 !

2)进入热云调试页面查看调试数据:

“全部产品” - “待调试产品”–“调试”

三、接入方法说明

1.添加SDK所需依赖框架

使用Security.framework来存储设备标识,

使用CoreTelephony.framework来获取运营商信息,

使用AdSupport.framework来获取Advertising Identifier信息,

使用SystemConfiguration.framework来检查当前网络环境,

使用CoreMotion.framework来获取陀螺仪数据

使用libsqlite3.dylib用来存储数据。

使用iAd.framework、AVFoundation.framework来获取数据。

使用libz.tbd来压缩数据。

  • 添加方法:

在工程目录中,选择

TARGETS-->Build Phases-->Link Binary With Libraries-->+ -->选择Security.framework、CoreTelephony.framework、AdSupport.framework、libsqlite3.dylib、iAd.framework 、AVFoundation.framework、libz.tbd等库文件。

新版xcode .dylib以.tbd为后缀,添加对应动态库。

注:

1)如上动态库请全部配置,避免报错。

2)xcode 7及以上版本,.dylib后缀结尾的系统库均更改为.tbd后缀结尾

2.初始化热云SDK

  • 方法用途:

用于应用启动后,初始化热云SDK。报送应用安装或启动事件。

  • 使用方法:

在application:didFinishLaunchingWithOptions方法中调用

+ (void)initWithAppKey: withChannelId:方法进行初始化
  • 方法接口:
+ (void)initWithAppKey:(NSString *)appKey withChannelId:(NSString *)channelId;
  • 参数说明:
参数类型是否必填长度说明
appkeyNSString32位创建产品时获得的32位字符长度的APPKEY
channelIdNSString最长64位填写_default_
  • 示例代码:
#import “Tracking.h”
-(BOOL)application:(UIApplication *)applicationdidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[TrackinginitWithAppKey:@"475938c702f7451a88eaffb524962649"withChannelId:@"_default_"];
}

3.统计用户注册数据

  • 方法用途:

用于用户注册完成,报送应用注册事件。

  • 使用方法:

在用户注册完成时调用TrackingsetRegisterWithAccountID方法。

  • 方法接口:
+(void) setRegisterWithAccountID:(NSString *)account;
  • 参数说明:
参数类型是否必填长度说明
accountNSString最长64位账号唯一标识,仅支持英文、数字、下划线
  • 示例代码:
[TrackingsetRegisterWithAccountID:@"hero"];

4.统计用户登录数据

  • 方法用途:

用于用户登录完成、切换账号时,报送应用登录事件。

  • 使用方法:

调用TrackingsetLoginWithAccountID方法。

  • 方法接口:
+ (void)setLoginWithAccountID:(NSString *)account;
  • 参数说明:
参数类型是否必填长度说明
accountNSString最长64位账号唯一标识,仅支持英文、数字、下划线
  • 示例代码:
[TrackingsetLoginWithAccountID:@"hero"];

5.统计用户订单数据

  • 方法用途:

用于用户提交订单后,统计订单数据。

  • 使用方法:

用户提交订单后调用TrackingsetDD方法。

  • 方法接口:
+(void)setDD:(NSString *)ryTID hbType:(NSString*)hbType hbAmount:(float)hbAmount;
  • 参数说明:
参数类型是否必填长度说明
ryTIDNSString最长64位交易流水号,请务必确保唯一。
hbTypeNSString最长3位货币类型,按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
hbAmountfloat最长16位订单的真实货币金额,人民币单位:元
  • 示例代码:
[TrackingsetDD:@"trans-id-123"hbType:@"CNY"hbAmount:12.5];

6.统计用户充值成功数据(建议使用服务器REST报送)

  • 方法用途:

用于用户充值成功,统计充值数据,所有付费相关分析的数据报表均依赖此方法。

注:前端报送支付有掉单风险,收入数据会出现误差,为确保支付数据准确,建议使用服务器报送支付(请参考“REST”文档)。

  • 使用方法:

用户充值成功且后端发货成功后调用TrackingsetRyzf方法。

  • 方法接口:
+(void)setRyzf:(NSString *)ryTID ryzfType:(NSString*)ryzfType hbType:(NSString*)hbType hbAmount:(float)hbAmount;
  • 参数说明:
参数类型是否必填长度说明
ryTIDNSString最长64位付费数据按此参数排重,交易流水号,请务必确保唯一。。
ryzfTypeNSString最长16位支付类型,例如支付宝(alipay),银联(unionpay),微信支付(weixinpay),易宝支付(yeepay),paymentType不能填写:FREE(FREE不统计付费)
hbTypeNSString最长3位货币类型,按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
hbAmountfloat最长16位支付的真实货币金额,人民币单位:元
  • 示例代码:
[TrackingsetRyzf:@"trans-id-123"ryzfType:@"alipay"hbType:@"CNY"hbAmount:12.5];

7.统计广告展示事件

  • 方法用途:
    当App内的变现广告被展示时调用此方法进行事件上报。
  • 方法接口:
+(void)onAdShow:(NSString *)adPlatform adId:(NSString *)adId;
  • 参数说明:
参数类型是否必填长度说明
adPlatformNSString最长16位填充广告的变现平台,例如穿山甲(csj)、优量汇(ylh)、百青藤(bqt)等
adIdNSString最长32位填充广告在变现平台的广告位ID
  • 示例代码:
[Tracking onAdShow:@"csj" adId:@"adid123456"];

8.统计广告点击事件

  • 方法用途:
    当App内的变现广告被点击时调用此方法进行事件上报。
  • 方法接口:
+(void)onAdClick:(NSString *)adPlatform adId:(NSString *)adId;
  • 参数说明:
参数类型是否必填长度说明
adPlatformNSString最长16位填充广告的变现平台,例如穿山甲(csj)、优量汇(ylh)、百青藤(bqt)等
adIdNSString最长32位填充广告在变现平台的广告位ID
  • 示例代码:
[Tracking onAdClick:@"csj" adId:@"adid123456"];

9.统计App使用时长事件

  • 方法用途:
    如需监测APP使用时长请在调用initWithAppKey:withChannelId:函数前调用该函数,并传入true作为参数,如不需监测APP时长,可不做任何接入处理。

注:热云SDK总共包含配置类接口三个,如需调用相关配置函数,都需在调用initWithAppKey:withChannelId:初始化函数前调用,以免遗漏相关数据报送,导致数据出现问题。该三个接口为:setPrintLog:setTrackAppDuration:setDeferredDeeplinkCalllbackDelegate:

  • 方法接口:
+(void)setTrackAppDuration:(BOOL)track;
  • 参数说明:
参数类型是否必填长度说明
trackBOOLtrue:开启,false:不开启
  • 示例代码:
[Tracking setTrackAppDuration:true];

10.统计App内页面浏览时长事件

  • 方法用途:
    如需监测App内页面浏览时长,请在页面展示时调用函数trackViewAppear:,页面销毁,消失时调用函数trackViewDisAppear:,请确保函数成对调用;pageID代表页面唯一标识,请确保pageID的唯一性。
  • 方法接口:
+(void)trackViewAppear:(NSString *)pageID;
+(void)trackViewDisAppear:(NSString *)pageID;
  • 参数说明:
参数类型是否必填长度说明
pageIDNSString最长64位pageID代表页面唯一标识,请确保pageID的唯一性
  • 示例代码:
[Tracking trackViewAppear:@"HomeView"];
[Tracking trackViewDisAppear:@"HomeView"];

11.统计用户自定义事件

  • 方法用途:

用于统计用户在应用内的任意行为,如打开某个面板、点击某个Button、参与某个活动等。

eventName必须为event_1到event_12。

  • 使用方法:

在自定义用户行为的地方,调用Tracking setEvent方法。

  • 方法接口:
+(void)setEvent:(NSString *)eventName;
  • 参数说明:
参数类型是否必填长度说明
eventNameNSString最长32位自定义事件名称,必须为event_1到event_12
  • 示例代码:
[TrackingsetEvent:@"event_1"];

12.获取设备ID

  • 方法用途:

用于获取已缓存到钥匙链的设备广告标识符。

  • 使用方法:

统计用户profile的地方,调用getDeviceid方法。

方法接口:

+(NSString*)getDeviceId;
  • 注:

1)该接口返回首次调用initWithAppKey: withChannelId:函数时获取的系统idfa,只要安装过应用且调用过初始化函数,通过该接口返回的字符串基本不会变化(包括删除APP,重置idfa,开启、关闭广告追踪等操作),此值作为首次安装设备标识符参考。

2)如需获取实时idfa,请勿使用该接口,用户需自行通过系统函数获取。

9、技术支持

如有任何问题,请及时联系我们的技术支持工程师:

  • 技术支持邮箱:support@reyun.com

  • 技术支持QQ:2785608528