Unity_SDK_接入说明文档
一、说明
1.适用范围
热云TrackingIO作为国内第三方移动广告监测平台，能够更好的帮助广告主更精准的评估每次广告投放效果，以及帮助广告网络做广告系统的投放优化或业务数据的完善。
本文档适用于使用Unity来开发的产品。
本文档适用于Android2.3（APILevel9）及以上的安卓系统，及IOS9.0及以上的苹果系统
2.SDK下载
- 下载地址
- 最新SDK版本为：1.7.0
- 更新日期：2022.08.31
- 更新内容：
1.各事件接口增加自定义传参。
2.针对近期应用宝推出的获取个人信息频次规范，优化了设备信息获取频次。
3.统计说明
为了能够在接入过程中保持概念统一，针对通用概念做如下说明：
- 设备
指某台安装了Unity应用的终端。
- 账号
指用户在某台设备上安装了应用之后，在应用中的唯一标识。
通常用作账号的标识符可以是用户注册应用时的唯一用户名（如邮件地址），也可以是用户注册时自动生成的唯一字符串。
二、接入流程
1.申请APPKEY
1)打开https://new.trackingio.com，使用您的热云账号进行登录。
2)进入“产品中心”，点击左上方**“+新建产品”**，完成产品创建，您将获得一串32位的16进制APPKEY；
如果您已经完成产品创建，请在如下位置获取APPKEY：全部产品按钮”-“对应产品”-APPKEY
APPKEY为应用的唯一标识，用于集成到SDK中。
注：为了保证您的数据安全,请勿泄露您的APPKEY。
2.导入SDK
1)前往最新SDK下载地址，下载SDK压缩包，解压至本地目录。
2)导入方法：将zip包解压缩后将包内Assets文件夹下的文件拷贝到项目Assets下。
3.接入SDK
详见“三、接入方法说明”
4.测试
1)在开发环境中进行Debug测试，日志TAG为Tracking：
public void setPrintLog (bool print)
注：热云SDK所有API接口的http response均以status：0表示成功，若不成功，会在返回的json里提示详细错误信息
2)进入热云调试页面查看调试数据：
“全部产品按钮” - “待调试产品”–“调试”
三、接入方法说明
1.添加权限和依赖框架
1)Android
1.1权限列表
在AndroidManifest.xml文件中添加如下权限
//网络访问权限
<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.** {*;}
2)添加sdk所需依赖框架（IOS）
使用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.初始化热云SDK
- 方法用途：
用于应用启动后，初始化热云SDK。报送应用安装或启动事件。
- 使用方法：
调用Tracking.Instance.init方法进行初始化。
- 方法接口：
public void init (string appKey, string channelId,string caid1 = null,string caid2 = null,string oid = null,
string oaid = null,string assetFileName = null, string oaidLibraryString = null,Dictionary<string,object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| appKey | String | 是 | 32位 | 创建产品时获得的32位字符长度的APPKEY |
| channelId | String | 是 | 最长64位 | 用于标识推广渠道，支持英文、数字、下划线，默认填写_default_；分包（应用市场）模式，该值必须与热云后台“广告监”-“推广管理”-“推广活动管理”-新建推广活动（分包）填写的渠道ID一一对应。 |
| caid1(iOS 专用) | string | 否 | 当前版本的中国广告协会互联网广告标识；如果无法获取caid的值，则传null或采用默认值null | |
| caid2(iOS 专用) | string | 否 | 上一版本的中国广告协会互联网广告标识；如果无法获取caid2的值，则传null或采用默认值null | |
| oid | string | 否 | 热云mobdna反作弊SDK需要参数，如果无法获取oid的值，则传null或采用默认值null | |
| oaid(Android 专用) | string | 否 | 传oaid的值，如果无法正确获取oaid的值，则传null或采用默认值null | |
| assetFileName(Android 专用) | string | 否 | 使用oaid版本1.0.26+以上时，需要此参数，如果传入了oaid参数则不需要此参数（该参数需向msa申请证书进行获取），若不需要该参数，则传null或采用默认值null | |
| oaidLibraryString(Android 专用) | string | 否 | 使用oaid版本1.0.26+以上时，需要此参数，如果传入了oaid参数则不需要此参数，根据msa文档1.0.26对应值为 nllvm1623827671，1.0.27对应值为 nllvm1630571663641560568，1.0.30及以上对应值为msaoaidsec，若不需要该参数，则传null或采用默认值null | |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "initvalue";
Tracking.Instance.init(appkey, "_default_",caid1,caid2,oid,oaid:null,assetFileName: "com.reyun.chicken.cert.pem",
oaidLibraryString: "msaoaidsec",customParams: dict);
3.统计用户注册数据
- 方法用途：
用于用户注册完成，报送应用注册事件。
- 使用方法：
在用户注册完成时调用Tracking.Instance.register方法。
如果开发者没有自己的用户系统，希望使用用户设备ID作为accountId，直接调用getDeviceId()方法即可。
- 方法接口
public void register (string account, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| account | String | 是 | 最长64位 | 账号唯一标识，支持英文、数字、下划线 |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = 123456789;
Tracking.Instance.register("nsername_reg",dict);
4.统计用户登录数据
- 方法用途：
用于用户登录完成、切换账号时，报送应用登录事件。
- 使用方法：
调用Tracking.Instance.login方法。
- 方法接口：
public void login (string account,string serverId = null, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| account | String | 是 | 最长64位 | 账号唯一标识，支持英文、数字、下划线 |
| serverId | String | 否 | 最长64位 | 服务器标识，支持英文、数字、下划线 |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "loginservervalue";
dict["param2"] = 123456789.1233456;
Tracking.Instance.login("user-ser", "server2",dict);
5.统计用户充值成功数据（建议使用服务器REST报送）
- 方法用途：
用于用户充值成功，统计充值数据，所有付费相关分析的数据报表均依赖此方法。
注：前端报送支付有掉单风险，收入数据会出现误差，为确保支付数据准确，建议使用服务器报送支付（请参考“REST”文档）。
- 使用方法：
用户充值成功且后端发货成功后调用Tracking.Instance.setryzf方法。
- 方法接口：
public void setryzf (string ryTID, string ryzfType, string hbType, float hbAmount, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| ryTID | String | 是 | 最长64位 | 交易流水号，请确保唯一。 |
| ryzfType | String | 是 | 最长16位 | 支付类型，例如支付宝(alipay)，银联(unionpay)，微信支付（weixinpay）,易宝支付（yeepay），paymentType不能填写：FREE（FREE不统计付费） |
| hbType | String | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| hbAmount | float | 是 | 最长16位 | 支付的真实货币金额，人民币单位：元 |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = 123d;
Tracking.Instance.setryzf("transactionId-123"," alipay ","CNY",1234,dict);
6.统计用户自定义事件
- 方法用途：
用于统计用户在应用内的任意行为，如打开某个面板、点击某个Button、参与某个活动等。
- 使用方法：
在自定义用户行为的地方，调用Tracking.Instance.setEvent方法。
eventName必须为event_1到event_30。
- 方法接口：
public void setEvent (string eventName, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 描述 |
|---|---|---|---|---|
| eventName | String | 是 | 最长32位 | 自定义事件的名称必须为event_1到event_30 |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = 12;
dict["param2"] = level;
Tracking.Instance.setEvent("event_10",dict);
7.统计用户订单数据
- 方法用途：
用于用户提交订单后，统计订单数据。
- 使用方法：
用户提交订单后调用Tracking.Instance.setDD方法。
- 方法接口：
public void setDD (string ryTID, string hbType, float hbAmount, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| ryTID | string | 是 | 最长64位 | 订单流水号，请确保唯一。 |
| hbType | string | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| hbAmount | float | 是 | 最长16位 | 订单的真实货币金额，人民币单位：元 |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "123456789";
Tracking.Instance.setOrder ("transactionId-11","CNY",100001,dict);
8.统计广告展示事件
- 方法用途：
当App内的变现广告被展示时调用此方法进行事件上报。 - 方法接口：
public public void setTrackAdShow(string adPlatform,string adId,bool playSuccess, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| 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” |
| playSuccess | bool | 是 | 1位 | 本次展示广告是否填充成功，true成功、false失败，无法确定填充是否成功时，请传true |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "adshow___00001";
Tracking.Instance.setTrackAdShow("csj", "123566", true,dict);
9.统计广告点击事件
- 方法用途：
当App内的变现广告被点击时调用此方法进行事件上报。 - 方法接口：
public void setTrackAdClick(string adPlatform, string adId, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| 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” |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "adclick___00001";
Tracking.Instance.setTrackAdClick("csj", "123566",dict);
10.统计App使用时长事件
- 方法用途：
·监测APP使用时长。
TrackingIO SDK提供的是手动计算方案，即您需要自行计算使用时长，并将计算的时长按照下方的方法上报。
·推荐的时长计算方法：
1.进入前台时记一个时间T1；
2.置于后台时记一个时间T2，则本次在前台的时长duration1=T2-T1；
3.再次进入前台时记一个时间T3，T3-T2=置于后台的时间（需要统计后台时间就算这个数，不需要的话就不算）；
4.强制杀掉app时，会有上滑动作，上滑时记录时间T4，在杀掉app的情况下，本次在前台的时长duration2=T4-T3。
- 方法接口：
public void setTrackAppDuration(long duration, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| duration | long | 是 | - | 传入APP启动到结束运行的时间长度，单位为秒（s） |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "appdurationValue";
Tracking.Instance.setTrackAppDuration(100,dict);
11.统计App内页面浏览时长事件
- 方法用途：
监测App内页面浏览时长 - 方法接口：
public void setTrackViewDuration(string pageID,long duration, Dictionary<string, object> customParams = null)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| pageID | String | 是 | 最长64位 | pageID代表页面唯一标识，请确保pageID的唯一性 |
| duration | long | 是 | - | 页面展示时长，单位秒(s) |
| customParams | Dictionary<string,object> | 否 | 10个键值对 | 自定义属性key只能为string类型，名称为param1-param10，value支持字符串、数字，不超过64位。，若不需要该参数，则传null或采用默认值null |
- 示例代码：
Dictionary<string, object> dict = new Dictionary<string, object>();
dict["param1"] = "viewDurationValue";
dict["param2"] = 123;
Tracking.Instance.setTrackViewDuration("mainview",20,dict);
12.获取激活归因结果
- 方法用途：
获取激活归因结果,请在调用接口init (string appKey, string channelId)前调用该函数，如示例代码所示。 - 方法接口：
public void setAttributionCalllbackDelegate(AttributionCalllback callback)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| callback | AttributionCalllback | 是 | - | Delegate 类型 |
- 示例代码：
private void Awake() {
string appkey = "your appkey";
Tracking.Instance.setAttributionCalllbackDelegate(OnAttibutionCallback);
Tracking.Instance.init(appkey, "_default_");
}
private void OnAttibutionCallback(string result, int status)
{
}
13.获取延迟深度链接回调信息
- 方法用途：
获取延迟深度链接回调信息,请在调用接口init (string appKey, string channelId)前调用该函数，如示例代码所示。请查看Application.deepLinkActivated框架API使用方法，查看热云deeplink相关文档，严格测试该功能逻辑。如有疑问，请联系我们的技术支持工程师。 - 方法接口：
public void setDeferredDeeplinkCalllbackDelegate(DeferredDeeplinkCallBack callback)
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| callback | DeferredDeeplinkCallBack | 是 | - | Delegate 类型 |
- 示例代码：
private void Awake() {
string appkey = "your appkey";
Application.deepLinkActivated += onDeepLinkActivated;
Tracking.Instance.setDeferredDeeplinkCalllbackDelegate(OnDeeplinkCallback);
Tracking.Instance.init(appkey, "_default_");
if (!string.IsNullOrEmpty(Application.absoluteURL))
{
onDeepLinkActivated(Application.absoluteURL);
}
}
private void OnDeeplinkCallback(string msg)
{
}
private void onDeepLinkActivated(string url)
{
Tracking.Instance.setEvent("invoke");
Debug.Log("onDeepLinkActivated function call from unity url:" + url);
}
14、技术支持
如有任何问题，请及时联系我们的技术支持工程师：
技术支持邮箱：support@reyun.com
技术支持QQ：2785608528