# 热云 TrackingIO 集成方案
本文将介绍如何在 TE 后台接入热云 TrackingIO 数据，TE 后台支持接入热云 TrackingIO 实时回调数据
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 集成类型 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|
| 实时回调 | 回传 | 用户级别 | ✅ |
在开始接入热云 TrackingIO 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
目前，热云 TrackingIO 提供了激活、注册、登录、付费回调四个回调接口，以下是热云 TrackingIO 回调链接文档。
我们建议您只接入注册回调数据，获取客户的归因信息。由于回调链接需要由热云技术人员进行操作，因此请按照本节内容获取所有必要信息后，联系热云技术人员配置回调。
# 集成流程
- 接入热云 TrackingIO SDK 与 TE SDK，在调用热云 SDK 注册方法时传入 TE SDK 的访客 ID
- 登录 TE 后台，进入三方集成模块，新增热云 TrackingIO 集成，完成相关配置，并复制回调地址
- 将应用的 APP_ID 与 Secret、回调地址以及回调数据类型提供给热云技术人员，热云技术人员将协助您配置数据回传
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
首先，您需要在应用中引入热云 TrackingIO SDK 以及 TE SDK，并完成初始化配置。热云 TrackingIO SDK 与 TE SDK 的接入文档如下：
# 1.1 方案一（自动集成）
- 如果您接入的 TE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
- 如果您接入的 TE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
本方案是自动集成方案，请在初始化 TE 客户端 SDK 后调用以下代码开启：
// 初始化TA SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
//开启Tracking id关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TRACKING)；
// 初始化 Tracking SDK
Tracking.initWithKeyAndChannelId(getApplication(), parameters);
该方案的原理就是内部自动调用 Tracking的setRegisterWithAccountID 方法，传入 TE 访客 ID。
# 1.2 方案二（手动集成）
手动集成方案，需要您在热云 SDK 调用 setRegisterWithAccountID() 时传入 TE 访客 ID。请注意，TE SDK 的初始化必须在热云的 SDK 初始化之前完成。以下是安卓端的代码样例：
// 获取 TE 的访客 ID, 即 TE 的 #distinct_id
String ta_distinct_id = ThinkingAnalyticsAPI.GetDistinctId()
// 通过 setEvent 上报自定义参数的形式将 TE 的 #account_id ，即账号 ID 上报给热云服务器
HashMap<String, Object> params = new HashMap<>();
params.put("ta_account_id", ta_account_id);
Tracking.setEvent("event_name", params);
// 将 TE 中的 #distinct_id 设置为热云的账号 ID, 上报给热云服务器
Tracking.setRegisterWithAccountID(ta_distinct_id);
# 二、TE 系统后台配置
# 2.1 用户识别与关联
由于热云回传的是用户级别数据，因此需要为其设置用户识别规则，即回传数据中与 #distinct_id 和 #account_id 对应的字段。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，可以直接使用默认值：
- 账号 ID 关联字段：不填写
- 访客 ID 关联字段：account
# 2.2 事件数据入库与配置
打开「事件表入库设置」开关后，热云回传的数据都将写入到事件表中，我们建议您开启事件数据入库。
# 2.3 用户属性入库规则
在默认情况下，TE 系统会自动将热云回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| 热云字段 | 入库 TA 后用户属性名称 | 说明 |
|---|---|---|
| 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 中配置的数据上报地址。配置后再回到热云配置页的「数据源」复制终端地址。
#
# 三、联系热云技术人员配置回传
接下来，您需要联系热云工作人员开启回调，一般来说，您需要向热云提供以下四个信息：
| 信息 | 说明 | 举例 |
|---|---|---|
| 回调数据类型 | 您需要接入的回调数据 | 激活回调或注册回调（二选一） |
| 回调链接 | TE 系统接收回调数据的地址，在集成配置页面获取 | https:// {receiver-host} /attribution/callback/reyun/ {app-id} |
| appkey | 广告主在热云后台产品的唯一表示，从热云后台获取 | f819f9cac******812b2067d0cf8 |
| securitykey | 安全校验字段，目前 TE 不支持，可由广告主自定义 | abc123 |
# 四、数据入库
# 4.1 用户识别规则
TE 系统将根据「用户识别与关联」中的配置，对回传数据进行用户识别，将热云回传的用户粒度数据能够关联在 TE 项目中的对应用户身上。
默认规则为：
- 访客 ID：检查回传数据中是否存在 account，如果存在，将其设置为 #distinct_id，如果没有，则该条数据将被视作无效数据，直接丢弃
# 4.2 事件入库规则
- 使用数据中的 activetime 字段，作为事件的 #event_time
- 注册回调的事件名为 reyun_sign_up
- 回调链接中配置的其他字段将全数入库
# 4.3 事件属性及标准化字段
以下是热云注册回调事件回传的所有事件属性，其中部分字段会进行标准化处理：
| 热云回传字段 | 标准化字段 | 说明 | 备注 |
|---|---|---|---|
| spreadurl | 推广活动短链 | 点击参数，ASA 归因或自然量用户不会返回这些字段 | |
| spreadname | 推广活动名称 | ||
| channel | te_ads_object.media_source | 渠道名称 | |
| clicktime | 点击接收时间 | ||
| uip | 点击 IP | ||
| 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 | 巨量2.0独有参数 |
| advert_name | te_ads_object.ad_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 | 事件类型 | 注册为：reged | |
| osversion | 系统版本 | ||
| ryos | te_ads_object.platform | 操作系统 | |
| 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 | 即 TE 访客 ID |
# 4.4 用户属性入库规则
- 根据用户识别规则，将事件数据关联到对应的 TE 用户身上
- 根据用户属性入库规则，确定用户属性设置逻辑是 user_set、user_setOnce 或 user_add
- 从指定事件或全事件中获取需要写入用户属性的字段，并将其以给定属性名与类型写入用户表
# 五、后续使用
# 5.1 数据入库检查
最后，请您检查 TE 系统是否接收到了热云的回传数据，您可以按照以下方法进行检查：
- 在详细数据中查看
若平台接入状态为「已接入」，则说明已经从该平台接收到了数据，且数据已经入库。此时，您可以直接在集成页的「详情」TAB 页查看收到的最近 1000 条数据。点击具体的一行可查看该数据的明细信息，包括转化前与转化后的数据，可以复制或导出该条数据，或者点击右上角下载完整数据：
- 在其他产品模块查看
除了集成页以外，您还可以在「数据管理」页面查看回传事件、用户属性是否被创建。
您也可以在分析模型，如事件分析模型、用户属性分析模型中通过分析的方式检查数据是否入库。
# 5.2 报表建议
以下提供几个构建报表的建议：
- 在各个模型中使用热云回传的用户归因字段进行人群对比，分析不同来源用户的游戏内行为差异
- 在留存分析模型中，使用热云回传的归因信息对比分析不同来源用户的 LTV 情况