# 热云 TrackingIO 集成方案
本文将介绍如何在 TE 后台接入热云 TrackingIO 数据，TE 后台支持接入热云 TrackingIO 实时回调数据
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 实时回调 | 回传 | 用户级别 | ✅ |
在开始接入热云 TrackingIO 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
目前，热云 TrackingIO 提供了激活、注册、登录、付费、自定义事件的回调能力，您可以点击此处查看热云 TrackingIO 回调链接文档 (opens new window)。
我们建议您接入激活或者注册回调数据，获取客户的归因信息。由于回调链接需要由热云技术人员进行操作，因此请按照本节内容获取所有必要信息后，请联系热云技术人员配置回调。
# 集成流程
- 接入热云 TrackingIO SDK 与 TE SDK，在调用热云 SDK 注册方法时传入 TE SDK 的访客 ID
- 登录 TE 后台，进入三方集成模块，新增热云 TrackingIO 集成，完成相关配置，并复制回调地址
- 将应用的 APP_ID 与 Secret、回调地址以及回调数据类型提供给热云技术人员，热云技术人员将协助您配置数据回传
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
# 1.1 引入热云 SDK 与 TE SDK
首先，您需要在应用中引入热云 TrackingIO SDK 以及 TE SDK，并完成初始化配置。热云 TrackingIO SDK 与 TE SDK 的接入文档如下：
# 1.2 进行 SDK 配置
在引入 SDK 后，接下来需要做的就是将 TE SDK 的访客 ID 与账号 ID 设置到热云 SDK 中，请提前确定您想要回传的事件，并按照本章节相应部分完成 SDK 配置
# 1.2.1 激活事件
在激活事件中可以将 TE SDK 的访客 ID 设置成自定义属性，以下是安卓端的代码样例：
// 完成 TE SDK 的初始化
//...
// 热云上报激活事件
// 创建初始化参数对象
InitParameters parameters = new InitParameters();
// 初始化参数appkey，必须
parameters.appKey = "appkey";
// 初始化参数channelId, 必须
parameters.channelId = "320110";
// 初始化参数oaid，如果传入oaid，那么热云sdk不再调用msa相关接口获取oaid
parameters.oaid = "hahahahahahaha";
// 初始化参数assetFileName, 使用oaid版本1.0.26+以上时，需要此参数
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";
// 获取 TE SDK 的访客 ID
String te_distinct_id = instance.getDistinctId();
// 在自定义参数中设置 TE SDK 的访客 ID
HashMap<String, Object> params = new HashMap<>();
params.put("param6", te_distinct_id);
parameters.installParams = params;
Tracking.initWithKeyAndChannelId(getApplication(), parameters);
# 1.2.2 注册事件
同理，上报注册事件时可以通过自定义属性的方式，将 TE SDK 的账号 ID 与访客 ID 传入：
// 初始化 TE SDK 与热云 SDK
// ...
// 获取 TE SDK 的账号 ID 与访客 ID
String teAccountId = "account_id";
String teDistinctId = instance.getDistinctId();
// 上报注册事件，并传输 TE SDK 的账号 ID 与访客 ID
HashMap<String, Object> params = new HashMap<>();
params.put("param6", teDistinctId);
params.put("param7", teAccountId);
Tracking.setRegisterWithAccountID("account_id", params);
# 1.2.3 自定义事件
上报自定义事件与注册事件类似，获取 TE SDK 的账号 ID 与访客 ID 后在热云 SDK 的自定义事件上报接口中传输即可：
// 初始化 TE SDK 与热云 SDK
// ...
// 获取 TE SDK 的账号 ID 与访客 ID
String teAccountId = "account_id";
String teDistinctId = instance.getDistinctId();
// 上报自定义事件，并传输 TE SDK 的账号 ID 与访客 ID
HashMap<String, Object> params = new HashMap<>();
params.put("param6", teDistinctId);
params.put("param7", teAccountId);
Tracking.setEvent("event_1", params);
# 二、方案配置
完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成热云 TrackingIO 的配置。下图是热云 TrackingIO 的配置界面，请您按照本章节内容完成方案的创建：
# 2.1 用户识别字段
由于热云回传的是用户级别数据，因此需要为其设置用户识别规则，即回传数据中与 #distinct_id 和 #account_id 对应的字段。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，可以直接使用默认值：
- 账号 ID 关联字段：param7
- 访客 ID 关联字段：param6
# 2.2 事件表入库设置
打开「事件表入库设置」开关后，热云回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.3 用户属性入库规则
在默认情况下，TE 系统会自动将热云回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| 热云字段 | 入库 TE 后用户属性名称 | 说明 |
|---|---|---|
| ry_adgroup_name | te_ads_object.ad_group_name | 文本 |
| channel | te_ads_object.media_source | 文本 |
| ry_adplan_name | te_ads_object.campaign_name | 文本 |
| ry_adcreative_name | te_ads_object.ad_name | 文本 |
注意
旧版本的用户属性入库默认规则与当前不一致，请注意分辨。如果需要将新老属性合并，可以使用虚拟属性功能
如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示
在此，您可以修改用户属性从哪些事件来以及入库方式。入库方式默认是 user_setOnce，也就是只会保留首次上报的信息。
您可以点击「属性映射」按钮添加需要写入用户属性的字段；也可以点击左侧的「规则」按钮增添一套新的规则。
如果您希望关闭用户属性入库，可以停止所有规则：
# 2.4 数据源配置
若您配置了系统和项目级别数据上报地址，则显示如下链接；您可以直接复制该地址：
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到热云配置页的「数据源」复制终端地址。
# 2.5 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制，比如入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping |
入库后的事件名，可以自定义。
支持的 Key 为：
|
# 2.6 事件入库规则
- 使用数据中的 activetime 字段，作为事件的 #event_time
- 回调数据默认的事件名为，您可以修改 sink_event.event_mapping 对默认事件名进行修改：
- 激活事件：reyun_init
- 注册事件：reyun_sign_up
- 登录事件：reyun_login
- 付费事件：reyun_payment
- 自定义事件：事件名前缀加 reyun_，如 reyun_event_1
- 其他字段将全数入库，热云的回传数据中会有以下字段：
| 热云回传字段 | 类型 | 说明 | 备注 |
|---|---|---|---|
| spreadurl | 文本 | 推广活动短链 | 点击参数，ASA 归因或自然量用户不会返回这些字段 |
| spreadname | 文本 | 推广活动名称 | |
| channel | 文本 | 渠道名称 | |
| clicktime | 文本 | 点击接收时间 | |
| uip | 文本 | 点击 IP | |
| csite | 文本 | 广告位 ID | |
| ry_adgroup_id | 文本 | 广告组 ID | |
| ry_adgroup_name | 文本 | 广告组名称 | |
| ry_adplan_id | 文本 | 广告计划 ID | |
| ry_adplan_name | 文本 | 广告计划名称 | |
| ry_adcreative_id | 文本 | 广告创意 ID | |
| ry_adcreative_name | 文本 | 广告创意名称 | |
| advert_id | 文本 | 广告 ID | 巨量2.0独有参数 |
| advert_name | 文本 | 广告名称 | 巨量2.0独有参数 |
| project_id | 文本 | 项目 ID | 巨量2.0独有参数 |
| project_name | 文本 | 项目名称 | 巨量2.0独有参数 |
| mid1 | 文本 | 图片素材 ID | 巨量2.0独有参数 |
| mid2 | 文本 | 标题素材 ID | 巨量2.0独有参数 |
| mid3 | 文本 | 视频素材 ID | 巨量2.0独有参数 |
| mid4 | 文本 | 搭配试玩素材 ID | 巨量2.0独有参数 |
| mid5 | 文本 | 落地页素材 ID | 巨量2.0独有参数 |
| mid6 | 文本 | 安卓下载详情页素材 ID | 巨量2.0独有参数 |
| accountid | 文本 | 投放账号 ID | 媒体侧投放账号 |
| requestid | 文本 | 请求下发 ID | 巨量引擎通用参数 |
| convertid | 文本 | 转化 ID | 巨量引擎通用参数 |
| appkey | 文本 | 热云应用唯一标识 | |
| activetime | 文本 | 事件接收时间 | |
| what | 文本 | 事件类型 | 激活为：install |
| osversion | 文本 | 系统版本 | |
| ryos | 文本 | 操作系统 | |
| devicetype | 文本 | 设备类型 | |
| deviceid | 文本 | 设备 ID | |
| Idfa | 文本 | iOS 的 IDFA | |
| idfv | 文本 | iOS 的 IDFV | |
| imei | 文本 | 安卓的IMEI，Android 10 及以上无法获取 | |
| oaid | 文本 | OAID | |
| androidid | 文本 | Android ID | |
| aip | 文本 | 转化事件 IP | |
| skey | 文本 | 即请求参数 securitykey，无意义 | |
| attribution | 文本 | ASA 归因 | ASA 参数，ASA 广告归因是才会返回 |
| orgid | 文本 | 广告活动组 ID | |
| campaignid | 文本 | 活动 ID | |
| clickdate | 文本 | ASA 广告点击时间 | |
| adgroupid | 文本 | 广告组 ID | |
| keywordid | 文本 | 关键词 ID | |
| creativesetid | 文本 | 素材 ID（创意 ID） | |
| conversiontype | 文本 | 转化类型，新增或重装 | |
| account | 文本 | 注册时设置的账号 ID | 只有注册事件才会带有 |
| param1~param10 | 文本 | 自定义参数 | 默认情况下，建议使用 param6 对应 TE SDK 的访客 ID，param7 对应账号 ID |
# 2.7 标准化字段
以下是热云回调数据中进行标准化的字段：
| 回传字段 | 标准化字段 | 说明 |
|---|---|---|
| channel | te_ads_object.media_source | 渠道名称 |
| csite | te_ads_object.placement | 广告位 ID |
| ry_adgroup_id | te_ads_object.ad_group_id | 广告组 ID |
| ry_adgroup_name | te_ads_object.ad_group_name | 广告组名称 |
| ry_adplan_id | te_ads_object.campaign_id | 广告计划 ID |
| ry_adplan_name | te_ads_object.campaign_name | 广告计划名称 |
| ry_adcreative_id | te_ads_object.ad_id | 广告创意 ID |
| ry_adcreative_name | te_ads_object.ad_name | 广告创意名称 |
| advert_id | te_ads_object.ad_id | 广告 ID |
| advert_name | te_ads_object.ad_name | 广告名称 |
# 三、联系热云技术人员配置回传
接下来，您需要联系热云工作人员开启回调，一般来说，您需要向热云提供以下四个信息：
| 信息 | 说明 | 举例 |
|---|---|---|
| 回调数据类型 | 您需要接入的回调数据 | |
| 回调链接 | TE 系统接收回调数据的地址，在集成配置页面获取 |
https://{receiver-host}/attribution/callback/reyun/{app-id} |
| appkey | 广告主在热云后台产品的唯一表示，从热云后台获取 | f819f9cac******812b2067d0cf8 |
| securitykey | 安全校验字段，目前 TE 不支持，可由广告主自定义 | abc123 |
# 四、后续使用
# 4.1 数据入库检查
最后，请您检查 TE 系统是否接收到了热云的回传数据，您可以按照以下方法进行检查：
- 在详细数据中查看
若平台接入状态为「已接入」，则说明已经从该平台接收到了数据，且数据已经入库。此时，您可以直接在集成页的「详情」TAB 页查看收到的最近 1000 条数据。点击具体的一行可查看该数据的明细信息，包括转化前与转化后的数据，可以复制或导出该条数据，或者点击右上角下载完整数据：
- 在其他产品模块查看
除了集成页以外，您还可以在「数据管理」页面查看回传事件、用户属性是否被创建。
您也可以在分析模型，如事件分析模型、用户属性分析模型中通过分析的方式检查数据是否入库。
# 4.2 报表建议
以下提供几个构建报表的建议：
- 在各个模型中使用热云回传的用户归因字段进行人群对比，分析不同来源用户的游戏内行为差异
- 在留存分析模型中，使用热云回传的归因信息对比分析不同来源用户的 LTV 情况