Android_SDK_接入说明文档

一、说明

1.适用范围

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

本文档适用于Android 2.3(API Level 9)及以上的操作系统。

2.SDK下载

3.统计说明

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

  • 设备

指某台安装了Android应用的终端,例如SAMSUNG Galaxy Note 8、HTC U11、SAMSUNG Galaxy S8等。

  • 账号

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

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

二、接入流程

1.申请APPKEY

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

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

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

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

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

2.导入SDK

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

2)将目录中tracking1.x.x.jar(sdk核心包)以及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###
-dontwarn org.bouncycastle.**
-keep class org.bouncycastle.** {*;}
-keep class XI.CA.XI.**{*;}
-keep class XI.K0.XI.**{*;}
-keep class XI.XI.K0.**{*;}
-keep class XI.xo.XI.XI.**{*;}
-keep class com.asus.msa.SupplementaryDID.**{*;}
-keep class com.asus.msa.sdid.**{*;}
-keep class com.bun.lib.**{*;}
-keep class com.bun.miitmdid.**{*;}
-keep class com.huawei.hms.ads.identifier.**{*;}
-keep class com.samsung.android.deviceidservice.**{*;}
-keep class com.zui.opendeviceidlibrary.**{*;}
-keep class org.json.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public <methods>;}
-dontwarn com.reyun.tracking.**
-keep class com.reyun.tracking.** {*;}

1.4安卓SDK默认报文加密

  • SDK使用了全新的加密规则,保证SDK报文在请求上报和接收返回的过程中不被恶意脚本劫持、抓包。

2.初始化热云SDK

  • 方法用途:

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

  • 使用方法:

调用Tracking.initWithKeyAndChannelId方法进行初始化。

  • 方法接口:
Tracking.initWithKeyAndChannelId(Application application,InitParameters 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。

  • 参数说明:
参数类型是否必填长度说明
applicationApplication应用程序的引用
parameters.appKeyString32位创建产品时获得的32位字符长度的APPKEY
parameters.channelIdString最长64位用于标识推广渠道,支持英文、数字、下划线,默认填写_default_;分包(应用市场)模式,该值必须与热云后台“配置”-“推广活动管理”-新建推广活动(分包)填写的渠道ID一一对应。
parameters.oaidString自行获取OAID传入的值。
parameters.assetFileNameString使用oaid版本1.0.26+以上时,需要此参数,如果传入了oaid参数则不需要此参数(该参数需向msa申请证书进行获取
parameters.oaidLibraryStringString使用oaid版本1.0.26+以上时,需要此参数,如果传入了oaid参数则不需要此参数,根据msa文档1.0.26对应值为 nllvm1623827671,1.0.27对应值为 nllvm1630571663641560568,1.0.30对应值为msaoaidsec
  • 示例代码:
// 创建初始化参数对象
InitParameters parameters = new InitParameters();
// 初始化参数appkey,必须
parameters.appKey = ”appkey“;
// 初始化参数channelId, 必须
parameters.channelId = "320110";
// 初始化参数oaid,如果传入oaid,那么热云sdk不再调用msa相关接口获取oaid
parameters.oaid = "hahahahahahaha,oaid";
// 初始化参数assetFileName, 使用oaid版本1.0.26+以上时,需要此参数
parameters.assetFileName = "com.reyun.chicken.cert.pem";
// 初始化参数oaidLibraryString, 使用oaid版本1.0.26+以上时,需要此参数(该参数需向msa申请证书进行获取)
// 根据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()方法即可。

  • 方法接口:
Tracking.setRegisterWithAccountID(String accountId);
  • 参数说明:
参数类型是否必填长度说明
accountIdString最长64位账号唯一标识,仅支持英文、数字、下划线
  • 示例代码:
Tracking.setRegisterWithAccountID(123456);

4.统计用户登录数据

  • 方法用途:

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

  • 使用方法:

调用Tracking.setLoginSuccessBusiness方法。

  • 方法接口:
Tracking.setLoginSuccessBusiness(String accountId);
  • 参数说明:
参数类型是否必填长度说明
accountIdString最长64位账号唯一标识,仅支持英文、数字、下划线
  • 示例代码:
Tracking.setLoginSuccessBusiness(123456);

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

  • 方法用途:

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

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

  • 使用方法:

用户充值成功且后端发货成功后调用Tracking.setPayment方法。

  • 方法接口:
Tracking.setPayment(String transactionId,String paymentType,String  currencyType,float currencyAmount);
  • 参数说明:
参数类型是否必填长度说明
transactionIdString最长64位付费数据按此参数排重,交易流水号,请务必确保唯一。
paymentTypeString最长16位支付类型,例如支付宝(alipay),银联(unionpay),微信支付(weixinpay),易宝支付(yeepay),paymentType不能填写:FREE(FREE不统计付费)
currencyTypeString最长3位货币类型,按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
currencyAmountfloat最长16位支付的真实货币金额,人民币单位:元
  • 示例代码:
Tracking.setPayment(0062001242,“alipay”,“CNY”,1000.00f);

6.统计用户自定义事件

  • 方法用途:

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

eventName必须为event_1到event_12。

  • 使用方法:

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

  • 方法接口:
setEvent(final String eventName);
  • 参数说明:
参数类型是否必填长度说明
eventNameString最长32位自定义事件名称,必须为event_1到event_12
  • 示例代码:
Tracking.setEvent(“event_1”);

7.上报订单事件

  • 方法用途:

上报订单事件。

  • 使用方法:

当订单产生成功时调用此方法进行事件上报。

  • 方法接口:
Tracking.setOrder(String transactionId, String currencyType, float currencyAmount);
  • 参数说明:
参数类型是否必填长度说明
transactionIdString最长64位交易流水号,请确保唯一。
currencyTypeString最长3位货币类型,按照国际标准组织ISO 4217中规范的3位字母,例如CNY人民币、USD美金等
currencyAmountfloat最长16位支付的真实货币金额,人民币单位:元
  • 示例代码:
Tracking.setOrder(“f93182bc6”, “CNY”, 9.04f);

8.统计广告展示事件

  • 方法用途:
    当App内的变现广告被展示时调用此方法进行事件上报。
  • 方法接口:
Tracking.setAdShow(String adPlatform, String adId, String fill);
  • 参数说明:
参数类型是否必填长度说明
adPlatformString最长16位填充广告的变现平台(传括号中的值):
穿山甲(csj)、
优量汇(ylh)、
百青藤(bqt)、
快手(ks)、
Sigmob(sigmob)、
Mintegral(mintegral)、
OneWay(oneway)、
Vungle(vungle)、
Facebook(facebook)、
AdMob(admob)、
UnityAds(unity)、
IronSource(is)、
AdTiming(adtiming)、
游可赢(klein)
adIdString最长32位填充广告在变现平台的广告位ID。
注意:若您使用聚合平台且需要通过聚合平台API获取收入时,需传聚合平台对应的值,TopOn传“adsource_id”;AdTiming传“placementId”;TradPlus传“placementId”
fillString1位本次展示广告是否填充成功,1成功、2失败,无法确定填充是否成功时,请传1
  • 示例代码:
Tracking.setAdShow (“csj”, “adid123456”,1);

9.统计广告点击事件

  • 方法用途:
    当App内的变现广告被点击时调用此方法进行事件上报。
  • 方法接口:
Tracking.setAdClick(String adPlatform, String adId);
  • 参数说明:
参数类型是否必填长度说明
adPlatformString最长16位填充广告的变现平台(传括号中的值):
穿山甲(csj)、
优量汇(ylh)、
百青藤(bqt)、
快手(ks)、
Sigmob(sigmob)、
Mintegral(mintegral)、
OneWay(oneway)、
Vungle(vungle)、
Facebook(facebook)、
AdMob(admob)、
UnityAds(unity)、
IronSource(is)、
AdTiming(adtiming)、
游可赢(klein)
adIdString最长32位填充广告在变现平台的广告位ID。
注意:若您使用聚合平台且需要通过聚合平台API获取收入时,需传聚合平台对应的值,TopOn传“adsource_id”;AdTiming传“placementId”;TradPlus传“placementId”
  • 示例代码:
Tracking.setAdClick (“csj”, “adid123456”);

10.统计App使用时长事件

  • 方法用途:
    用于统计App的使用时长, 当App退出时进行调用
  • 方法接口:
Tracking.setAppDuration(long duration)
  • 参数说明:
参数类型是否必填长度说明
durationlong-App使用时长,单位:
毫秒
  • 示例代码:
Tracking. setAppDuration (3);

11.统计App页面停留时长事件

  • 方法用途:
    用于统计App的页面停留时长
  • 方法接口:
Tracking.setPageDuration(String activityName, long duration)
  • 参数说明:
参数类型是否必填长度说明
activityNameString最长64位页面名称或ID,请确保唯一性,推荐使用包名+页面名
durationlong-App使用时长,单位:毫秒
  • 示例代码:
Tracking.setPageDuration(“com.test.MainActivity”, 3);

12.退出SDK

  • 方法用途:

应用退出时释放sdk占用资源。

  • 使用方法:

用于程序退出时调用Tracking.exitSdk方法。

  • 方法接口:
Tracking.exitSdk();
  • 示例代码:
Tracking.exitSdk();

13.技术支持

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

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

  • 技术支持QQ:2785608528