一、说明
1.适用范围
热云TrackingIO作为国内第三方移动广告监测平台，能够更好的帮助广告主更精准的评估每次广告投放效果，以及帮助广告网络做广告系统的投放优化或业务数据的完善。
本文档适用于Android 2.3（API Level 9）及以上的操作系统。
2.SDK下载
- 下载地址
- 最新SDK版本为：1.9.0
- 更新日期：2022.11.07
- 更新内容：
1.socket连接增加了120秒的自动断开，避免出现异常
2.读取mac地址，只调用一次系统接口
3.TrackingHttpListener回调失败接口的时参数从null改为“”，以应对unity的情况
4.给unity增加带String类型json自定义参数的上报数据接口
5.去掉百度剪切板代码
3.统计说明
为了能够在接入过程中保持概念统一，针对通用概念做如下说明：
- 设备
指某台安装了Android应用的终端，例如SAMSUNG Galaxy Note 8、HTC U11、SAMSUNG Galaxy S8等。
- 账号
指用户在某台设备上安装了应用之后，在应用中的唯一标识。
通常用作账号的标识符可以是用户注册应用时的唯一用户名（如邮件地址），也可以是用户注册时自动生成的唯一字符串。
二、接入流程
1.申请APPKEY
1)打开https://new.trackingio.com，使用您的热云账号进行登录。
2)进入“产品中心”，点击左上方**“新建应用”**，完成产品创建，您将获得一串32位的16进制APPKEY；
如果您已经完成产品创建，请在如下位置获取APPKEY：“全部产品按钮”-“对应产品”-APPKEY
3)APPKEY为应用的唯一标识，用于集成到SDK中。
注：为了保证您的数据安全，请勿泄露您的APPKEY。
2.导入SDK
1)前往SDK下载地址，下载SDK压缩包，解压至本地目录。
2)将目录中tracking1.x.x.jar（sdk核心包），tkdna_vx.x.x.aar(mobDNA包)以及oaid_sdk_x.x.x.aar(设备id包) 和bcprov-jdkxx-xxx.jar(加密辅助包，也可用接入方自己的版本)导入到您的工程目录下的libs文件夹中。
导入方法：在工程目录结构中，右键选择Properties->Java Build Path，点击右侧Libraries选项卡，点击Add JARs按钮在Project/libs目录选择tracking1.x.x.jar，点击OK导入。
3)将supplierconfig.json文件放入到assets文件夹下
3.接入SDK
详见“三、接入方法说明”
4.测试
1)在开发环境中进行Debug测试，日志TAG为Tracking：
Tracking.setDebugMode(true);
注：热云SDK所有API接口的http response均以status：0表示成功
2)进入热云调试页面查看调试数据：
“全部产品按钮” - “待调试产品”–“调试”
三、接入方法说明
1.在AndroidManifest.xml文件中添加如下权限
1.1权限列表
//网络访问权限
<uses-permissionandroid:name="android.permission.INTERNET"/>
//获取网络状态权限
<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE"/>
//获取wifi状态权限
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>
//读取手机IMEI的权限，须在获得此权限后再初始化sdk，如果缺少此权限，会以AndroidID作为设备唯一标识符
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"/>
注：Android系统版本6.0以上，必须先获取权限，再调用初始化接口。反之，会影响激活数据精准度。
1.2在应用的build.gradle下增加如下配置
ndk { abiFilters 'armeabi-v7a','x86','arm64-v8a','x86_64','armeabi' }
packagingOptions {
doNotStrip "*/armeabi-v7a/*.so"
doNotStrip "*/x86/*.so"
doNotStrip "*/arm64-v8a/*.so"
doNotStrip "*/x86_64/*.so"
doNotStrip "armeabi.so"
}
注：具体配置项可根据app自身清空删减。
1.3如需混淆，则加入如下配置
###针对移动智能终端补充设备标识体系统一调用SDK###
# bouncycastle
-dontwarn org.bouncycastle.**
-keep class org.bouncycastle.** {*;}
# reyun sdk
-dontwarn com.reyun.tracking.**
-keep class com.reyun.tracking.** {*;}
# msa sdk
-keep class com.bun.miitmdid.** { *; }
-keep interface com.bun.supplier.** { *; }
# asus
-keep class com.asus.msa.SupplementaryDID.** { *; }
-keep class com.asus.msa.sdid.** { *; }
# freeme
-keep class com.android.creator.** { *; }
-keep class com.android.msasdk.** { *; }
# huawei
-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** {*; }
# lenovo
-keep class com.zui.deviceidservice.** { *; }
-keep class com.zui.opendeviceidlibrary.** { *; }
# meizu
-keep class com.meizu.flyme.openidsdk.** { *; }
# nubia
-keep class com.bun.miitmdid.provider.nubia.NubiaIdentityImpl { *; }
# oppo
-keep class com.heytap.openid.** { *; }
# samsung
-keep class com.samsung.android.deviceidservice.** { *; }
# vivo
-keep class com.vivo.identifier.** { *; }
# xiaomi
-keep class com.bun.miitmdid.provider.xiaomi.IdentifierManager { *; }
# zte
-keep class com.bun.lib.** { *; }
# coolpad
-keep class com.coolpad.deviceidsupport.** { *; }
# mobDNA
-dontwarn com.reyun.dna.**
-keep class com.reyun.dna.** {*;}
1.4安卓SDK默认报文加密
- SDK使用了全新的加密规则，保证SDK报文在请求上报和接收返回的过程中不被恶意脚本劫持、抓包。
2.初始化热云SDK
- 方法用途：
用于应用启动后，初始化热云 SDK，报送应用安装或启动事件。
- 使用方法：
调用Tracking.initWithKeyAndChannelId方法进行初始化。
- 方法接口：
Tracking.initWithKeyAndChannelId(getApplication(), parameters);
- 关于OAID的获取，目前TrackingIO支持两种OAID的获取方式：
第一种：APP自身集成移动安全联盟统一SDK获取OAID并传值至指定参数中；需要使用trackingIO_Android_1.8.1及以上版本，并且需要msa 1.0.13及以上版本，
否则将影响OAID的获取。移动安全联盟统一SDK获取地址：http://www.msa-alliance.cn/col.jsp?id=120
第二种： 引入TrackingIO SDK文件中的所有文件，由TrackingIO调用移动安全联盟统一SDK来获取OAID。
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| application | Application | 是 | 应用程序的引用 | |
| parameters.appKey | String | 是 | 32位 | 创建产品时获得的32位字符长度的APPKEY |
| parameters.channelId | String | 是 | 最长64位 | 用于标识推广渠道，支持英文、数字、下划线，默认填写_default_；分包（应用市场）模式，该值必须与热云后台“配置”-“推广活动管理”-新建推广活动（分包）填写的渠道ID一一对应。 |
| parameters.oaid | String | 否 | 传oaid的值，如果无法正确获取oaid的值，则传null | |
| parameters.assetFileName | String | 否 | 使用oaid版本1.0.26+以上时，需要此参数，如果传入了oaid参数则不需要此参数（该参数需向msa申请证书进行获取） | |
| parameters.oaidLibraryString | String | 否 | 使用oaid版本1.0.26+以上时，需要此参数，如果传入了oaid参数则不需要此参数，根据msa文档1.0.26对应值为 nllvm1623827671，1.0.27对应值为 nllvm1630571663641560568，1.0.30及以上对应值为msaoaidsec | |
| parameters.oid | String | 否 | 热云mobdna反作弊SDK需要参数，如果不使用mobdna产品，则传null | |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
// 创建初始化参数对象
InitParameters parameters = new InitParameters();
// 初始化参数appkey，必须
parameters.appKey = ”appkey“;
// 初始化参数channelId, 必须
parameters.channelId = "320110";
// 初始化参数oid, 如果不传入oid，则不会调用mobDNA的aar
parameters.oid = "fdsf";
// 初始化参数oaid，如果传入oaid，那么热云sdk不再调用msa相关接口获取oaid
parameters.oaid = "hahahahahahaha";
// 初始化参数assetFileName, 使用oaid版本1.0.26+以上时，需要此参数
（该参数需向msa申请证书进行获取）
parameters.assetFileName = "com.reyun.chicken.cert.pem";
// 初始化参数oaidLibraryString, 使用oaid版本1.0.26+以上时，需要此参数
// 根据msa文档1.0.26对应值为 nllvm1623827671，1.0.27对应值为 nllvm1630571663641560568，1.0.30及以上对应值为msaoaidsec
parameters.oaidLibraryString = "msaoaidsec";
Tracking.initWithKeyAndChannelId(getApplication(), parameters);
3.统计用户注册数据
- 方法用途：
用于用户注册完成，报送应用注册事件。
- 使用方法：
在用户注册完成时调用Tracking.setRegisterWithAccountID方法。
如果开发者没有自己的用户系统，希望使用用户设备ID作为accountId，直接调用Tracking.getDeviceId()方法获取设备ID即可。
注意该方法一定要在调用初始化接口之后间隔5s以上再使用，否则会影响取值。
- 方法接口：
Tracking.setRegisterWithAccountID(String accountId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| accountId | String | 是 | 最长64位 | 账号唯一标识，仅支持英文、数字、下划线 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setRegisterWithAccountID(“123456”);
4.统计用户登录数据
- 方法用途：
用于用户登录完成、切换账号时，报送应用登录事件。
- 使用方法：
调用Tracking.setLoginSuccessBusiness方法。
- 方法接口：
Tracking.setLoginSuccessBusiness(String accountId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| accountId | String | 是 | 最长64位 | 账号唯一标识，仅支持英文、数字、下划线 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setLoginSuccessBusiness(“123456”);
5.统计用户充值成功数据（建议使用服务器REST报送）
- 方法用途：
用于用户充值成功，统计充值数据，所有付费相关分析的数据报表均依赖此方法。
注：前端报送支付有掉单风险，收入数据会出现误差，为确保支付数据准确，建议使用服务器报送支付（请参考“REST”文档）。
- 使用方法：
用户充值成功且后端发货成功后调用Tracking.setPayment方法。
- 方法接口：
Tracking.setPayment(String transactionId,String paymentType,String currencyType,float currencyAmount);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| transactionId | String | 是 | 最长64位 | 付费数据按此参数排重，交易流水号，请务必确保唯一。 |
| paymentType | String | 是 | 最长16位 | 支付类型，例如支付宝(alipay)，银联(unionpay)，微信支付（weixinpay）,易宝支付（yeepay），paymentType不能填写：FREE（FREE不统计付费） |
| currencyType | String | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| currencyAmount | float | 是 | 最长16位 | 支付的真实货币金额，人民币单位：元 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setPayment(“0062001242”,“alipay”,“CNY”,1000.00f);
6.统计用户自定义事件
- 方法用途：
用于统计用户在应用内的任意行为，如打开某个面板、点击某个Button、参与某个活动等。
- 使用方法：
在自定义用户行为的地方，调用Tracking.setEvent方法。
- 方法接口：
setEvent(final String eventName, Map<String, Object> extra);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| eventName | String | 是 | 最长32位 | 自定义事件名称，必须为event_1到event_30 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
注：
1.eventName必须为event_1到event_30
2. params为自定义事件上报的自定义参数，仅支持param1-param10
3. 如需使用快手关键行为回传，请严格按照以下文档将指定参数上传至param1、param2中，自定义参数名称固定
4. 如需投放穿山甲LTV指标，请严格按照以下文档将LTV值上传至param3中
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| param1 | String | 快手关键行为必传 | 最长32位 | 根据行为类型回传对应枚 举值）：1 广告观看/2 通过关 卡/3 游戏时长/4 LTV/0 其他 Eg:param1=1 |
| param2 | String | 快手关键行为必传 | 最长32位 | 根据关键行为定义的次数/ 数量/等级回传具体数值 Eg:param2=15 |
| param3 | String | 投放穿山甲LTV必传 | 最长32位 | 针对穿山甲渠道回传所用到的ltv0值，同一设备24小时内产生的ltv累加值。例如：当前广告展示收益ltv0=5;则上报param3=5，单位为分。关于LTV累加值详情可参考文档：https://bytedance.feishu.cn/docs/doccnJubvtVfwztRJn98uihfsWh#LM2k80 |
- 示例代码：
HashMap<String, Object> params = new HashMap<>();
params.put("param1", "value1");
params.put("param2", "value2");
params.put("param3", "value3");
Tracking.setEvent("event_1", params);
7.上报订单事件
- 方法用途：
上报订单事件。
- 使用方法：
当订单产生成功时调用此方法进行事件上报。
- 方法接口：
Tracking.setOrder(String transactionId, String currencyType, float currencyAmount);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| transactionId | String | 是 | 最长64位 | 交易流水号，请确保唯一。 |
| currencyType | String | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| currencyAmount | float | 是 | 最长16位 | 支付的真实货币金额，人民币单位：元 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setOrder(“f93182bc6”, “CNY”, 9.04f);
8.统计广告展示事件
- 方法用途：
当App内的变现广告被展示时调用此方法进行事件上报。 - 方法接口：
Tracking.setAdShow(String adPlatform, String adId, String fill);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| 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” |
| fill | String | 是 | 1位 | 本次展示广告是否填充成功，1成功、2失败，无法确定填充是否成功时，请传1 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setAdShow (“csj”, “adid123456”, “1”);
9.统计广告点击事件
- 方法用途：
当App内的变现广告被点击时调用此方法进行事件上报。 - 方法接口：
Tracking.setAdClick(String adPlatform, String adId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| 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” |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setAdClick (“csj”, “adid123456”);
10.统计App使用时长事件
- 方法用途：
用于统计App的使用时长, 当App退出时进行调用 - 方法接口：
Tracking.setAppDuration(long duration)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| duration | long | 是 | - | App使用时长，单位：毫秒 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking. setAppDuration (3);
11.统计App页面停留时长事件
- 方法用途：
用于统计App的页面停留时长 - 方法接口：
Tracking.setPageDuration(String activityName, long duration)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| activityName | String | 是 | 最长64位 | 页面名称或ID，请确保唯一性，推荐使用包名+页面名 |
| duration | long | 是 | - | App使用时长，单位：毫秒 |
| extras | Map<String,Object> | 否 | 最多十个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字。 |
- 示例代码：
Tracking.setPageDuration(“com.test.MainActivity”, 3);
12.退出SDK
- 方法用途：
应用退出时释放sdk占用资源。
- 使用方法：
用于程序退出时调用Tracking.exitSdk方法。
- 方法接口：
Tracking.exitSdk();
- 示例代码：
Tracking.exitSdk();
13.技术支持
如有任何问题，请及时联系我们的技术支持工程师：
技术支持邮箱：support@reyun.com
技术支持QQ：2785608528