# 热力引擎集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 实时 API | 回传 | 用户级别 | ✅ | ✅ |
在开始接入热力引擎数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
热力引擎提供了实时 API 导出功能，支持实时回传激活等事件数据，详情可以参考热力引擎官网文档 (opens new window)
# 集成流程
- 接入热力引擎 SDK 与 TE SDK，在调用热云 SDK 注册方法时传入 TE SDK 的访客 ID
- 登录 TE 后台，进入三方集成模块，新增热云 TrackingIO 集成，完成相关配置，并复制回调地址
- 将应用的 APP_ID 与 Secret、回调地址以及回调数据类型提供给热云技术人员，热云技术人员将协助您配置数据回传
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
# 1.1 引入热力引擎 SDK 与 TE SDK
首先，您需要在应用中引入热力引擎 SDK 以及 TE SDK，并完成初始化配置。热力引擎 SDK 与 TE SDK 的接入文档如下：
# 1.2 进行 SDK 配置
在引入 SDK 后，接下来需要做的就是将 TE SDK 的访客 ID 与账号 ID 设置到热力引擎 SDK 中，我们推荐的做法是使用热力引擎的公共事件属性的设置接口
请注意顺序：
- 完成 TE SDK 的初始化
- 获取 TE SDK 的访客 ID
- 调用热力引擎的设置公共属性接口，将 TE SDK 的访客 ID 设置为热力引擎 SDK 的公共属性
- 热力引擎 SDK 初始化
- 当可以获取 TE SDK 的账号 ID 时（即登录账号或角色上线时），调用 TE SDK 的 login 接口，并再次调用热力引擎的设置公共属性接口，将账号 ID 设置为热力引擎 SDK 的公共属性
以下是安卓的代码样例：
// 完成 TE SDK 的初始化
TDAnalytics.init(context, APPID, SERVER_URL);
// 获取 TE SDK 的访客 ID
String te_distinct_id = TDAnalytics.getDistinctId();
// 使用公共事件属性设置接口，将 TE 的访客 ID 设置为热力引擎 SDK 的公共属性
SolarEngineManager.getInstance().setSuperProperties(context, "te_distinct_id", te_distinct_id);
// 热力引擎 SDK 初始化
SolarEngineConfig config = new SolarEngineConfig.Builder().build();
SolarEngineManager.getInstance().initialize(context, "开发者申请的appkey","开发者申请的userId",config);
// .....
// 用户登录后
// 获取账号 ID
String te_account_id = "login_id";
// TE SDK 调用 login
TDAnalytics.login(te_account_id);
// 使用公共事件属性设置接口，将 TE 的账号 ID 设置为热力引擎 SDK 的公共属性
SolarEngineManager.getInstance().setSuperProperties(context,"te_account_id", te_account_id);
# 二、方案配置
在完成了 SDK 的配置之后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成热力引擎的配置。下图是热力引擎的配置界面：
# 2.1 用户识别字段
由于热力引擎回传的是用户级别数据，因此需要为其设置用户识别规则。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：event_custom_params.te_account_id
- 访客 ID 关联字段：event_custom_params.te_distinct_id
# 2.2 事件表入库设置
打开「事件表入库设置」开关后，回传的数据（包括激活事件和应用内事件）都将写入到事件表中
我们建议您开启事件数据入库。但需要注意，默认情况下，我们会接收所有热力引擎回传的数据。如果回传的事件类型过多，会导致 TE 项目的事件量过度膨胀。因此建议在热力引擎平台设置回传时，只选择必要事件进行回传。
# 2.3 用户属性入库规则
在默认情况下，TE 系统会自动将热力引擎回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| 热力引擎字段 | 标准化字段 | 说明 |
|---|---|---|
| channel_name | te_ads_object.media_source | 媒体渠道 |
| adplan_name | te_ads_object.campaign_name | 广告计划名 |
| adgroup_name | te_ads_object.ad_group_name | 广告组名 |
| adcreative_name | te_ads_object.ad_name | 广告名 |
如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示
在此，您可以修改用户属性从哪些事件来。如果您不希望用户属性被频繁写入，可以关闭「包含所有事件」，并将来源事件名修改为 install。这样配置，则 TE 系统只会从热力引擎回传的 install 事件中提取需要写入用户属性的字段并进行写入。入库方式默认是 user_setOnce，也就是只会保留首次上报的信息。
如果您希望关闭用户属性入库，可以停止所有规则：
# 2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制，比如入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义。Key 为热力引擎的事件名，Value 为入库后的事件名；默认的是激活事件：install |
# 2.5 终端地址
终端地址中展示了 TE 系统接收热力引擎回传数据的地址。请您直接复制该地址，在接下来进行回传配置时，请将该地址填入：
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到热力引擎配置页的「数据源」复制终端地址。
# 三、在热力引擎完成回调配置
# 3.1 在热力引擎后台的实时api数据导出页面配置回调链接
在完成 TE 后台的方案创建后，请您登录热力引擎后台，选择您需要回传数据的项目，并从「归因」模块中选择「应用设置」-「数据导出」-「实时api导出」，即可进行热力引擎的实时回传配置
您可以按照以下规则来进行填写：
- 回调类型选择「激活」
- 回调地址填写您在 TE 后台获取到的回传地址
- 回调地址解析，建议您按照 3.2 章节的内容进行填写
- 回调方式，请选择 POST
- 超时时长、重试次数可以按需修改，无特殊需求可以使用默认值
当您完成配置后，点击提交即可
# 3.2 热力引擎的回调参数
以下展示的是热力引擎回调支持设置的参数，我们建议您在配置时，填入的参数名称与所选值保持一致，您可以从下表中获取所有我们推荐回传的字段，请注意一定要回传 event_name、event_time 与 event_custom_params 字段，否则数据可能转换失败
参数名 | 默认使用 | 值（举例） | 说明 |
|---|---|---|---|
| event_type | 是 | 枚举值： preset，custom | 是否预制事件 |
| event_name | 是 | 事件名称：install，startup，etc... | 事件名称 |
| attribution_time | 是 | 2023/7/1 22:47 | 归因时间 |
| attribution_touch_type | 是 | click | 归因触点类型 |
| attribution_method | 是 | 枚举值： deviceid fingerprint | 归因方法 |
| attribution_lbw | 86400 | 归因时间窗 | |
| attribution_ttit | 68 | 归因时间差 | |
| channel_name | 是 | Mintegral | 归因的渠道名称 |
| app_name | 是 | Cat EscapeInfinity | APP名称 |
| appkey | 是 | appkey | |
| app_platform | 是 | ios | app的平台 |
| landing_page_url | [https://apps.apple.com/us/app/cat-escape-infinity/id6445884698](https://apps.apple.com/us/app/cat-escape-infinity/id6445884698) | app落地页地址 | |
| turl_id | Ev2Evya | 监测链接短链ID | |
| turl_string | 监测链接短链 | ||
| turl_campaign_id | 是 | 7b35b6bd982780f729fcf4ff925b9c4e | 监测链接唯一ID |
| turl_campaign_name | 是 | 躲猫猫无尽版-IOS | 监测链接名称 |
| channel_id | 是 | 8221 | 监测链接对应的渠道ID |
| ry_touchpoint_ts | 是 | 1688222783854 | 展点时间 |
| attribution_type | 是 | ua | 归因类型（写死UA拉新） |
| account_id | 是 | 投放账号ID | |
| adgroup_id | 是 | 投放平台广告组ID | |
| adgroup_name | 是 | CatEscapeInfinity_CN_FO_0404_WX_iOS_MTG_1 | 投放平台广告组名称 |
| adplan_id | 是 | ss_Duomm_CN_FO_0404_WX_iOS_MTG_1 | 投放平台广告计划ID |
| adplan_name | 是 | 投放平台广告计划名称 | |
| adcreative_id | 是 | 1804913040 | 投放平台广告素材ID |
| adcreative_name | 是 | wadmm_21186_0_V_1203_mtg_nndb_cn_1024x768_cy.mp4 | 投放平台广告素材名称 |
| adcreative_type | 是 | 投放平台广告素材类型 | |
| site_id | 是 | mtg1183741824 | 投放平台子渠道ID |
| site_name | 是 | 投放平台子渠道名称 | |
| ad_type | 是 | 投放平台广告类型 | |
| placement_id | 是 | 投放平台广告位id | |
| conversion_id | 投放平台接收转化的唯一ID | ||
| click_id | mtg64a03bfe52979a0001a8cb4y | 投放平台点击唯一ID | |
| impression_id | 投放平台展示唯一ID | ||
| request_id | 7434D04B787321D534C7268DD8D4D52E | 投放平台请求唯一ID | |
| callback_id | 投放平台回调唯一ID | ||
| callback_url | 投放平台回调地址 | ||
| custom_params_1 | 投放平台自定义参数数据1-10 | ||
| custom_params_2 | 投放平台自定义参数数据1-10 | ||
| custom_params_3 | 投放平台自定义参数数据1-10 | ||
| custom_params_4 | 投放平台自定义参数数据1-10 | ||
| custom_params_5 | 投放平台自定义参数数据1-10 | ||
| custom_params_6 | 投放平台自定义参数数据1-10 | ||
| custom_params_7 | 投放平台自定义参数数据1-10 | ||
| custom_params_8 | 投放平台自定义参数数据1-10 | ||
| custom_params_9 | 投放平台自定义参数数据1-10 | ||
| custom_params_10 | 投放平台自定义参数数据1-10 | ||
| device_id | 是 | B9BBB98D-FFEE-448D-A9BE-52883FF230FD | 归因设备唯一ID |
| device_id_type | 是 | distinct_id | distinct_id |
| device_id_md5_type | distinct_id_md5 | distinct_id_md5 | |
| device_id_md5 | 55a6187afabbe2ed4c6e9bc0fdca423d | 归因设备唯一ID的md5 | |
| gaid | gaid | ||
| gaid_md5 | gaid_md5 | ||
| imei1 | imei1 | ||
| imei1_md5 | imei1_md5 | ||
| imei2 | imei2 | ||
| imei2_md5 | imei2_md5 | ||
| oaid | oaid | ||
| oaid_md5 | oaid_md5 | ||
| mac | mac | ||
| mac_md5 | mac_md5 | ||
| android_id | android_id | ||
| android_id_md5 | android_id_md5 | ||
| idfa | 49BB9C2F-E0DB-46B8-9C68-21C4C7FB30CC | idfa | |
| idfa_md5 | 1225a829ea48f2fc62a2d3faee263829 | idfa_md5 | |
| idfv | B9BBB98D-FFEE-448D-A9BE-52883FF230FD | idfv | |
| idfv_md5 | 55a6187afabbe2ed4c6e9bc0fdca423d | idfv_md5 | |
| ipv4 | 110.154.208.22 | ipv4 | |
| ipv6 | ipv6 | ||
| ua | 是 | Mozilla/5.0 (iPad; CPU OS 14_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 | ua |
| manufacturer | 是 | apple | 品牌 |
| model | 是 | iPad11,6 | 机型 |
| os | 是 | 枚举值 1：安卓 2：ios | 系统 |
| os_version | 是 | 14.2 | 版本 |
| ua_device_type | iPad | ua解析的设备类型 | |
| ua_os | IOS | ua解析的系统 | |
| ua_osv | 14.2 | ua解析的os version | |
| language | 是 | zh-Hans-CN | 语言 |
| country | 是 | CN | 国家 |
| city | 是 | 城市 | |
| att_status | 枚举值： denied、restricted、authorized、unknown、空 | ||
| lat_status | 枚举值： enable、disable、unknown、空 | ||
| network_type | 是 | 枚举值： 0：无网络 1：unknown 2：2G 3：3G 4：4G 5：5G 6：6G或下一代网络 9：WIFI | 上传数据时的网络状态 |
| carrier | 是 | 运营商 | |
| install_time | 1688222848242 | 激活时间 | |
| event_time | 是 | 1689781058000 | 服务端收到事件时间 |
| channel_package_name | default | 渠道包名称 | |
| app_version | 是 | 1.0.2 | app版本 |
| bundleid | 是 | jp.os.catescape | app bundle id |
| event_data | 是 | ||
| collector_version | 1.1.8.0 | sdk版本 | |
| integration_type | 枚举值： sdk api s2s | 对接方式 | |
| event_custom_params | 是 | 客户的自定义事件属性内容 | |
| caid | 事件的caid值 | ||
| caid_md5 | 事件caid的md5值 | ||
| event_account_id | 事件的account_id |
# 四、数据入库
# 4.1 数据入库规则
默认情况下，我们会按照以下规则将拉取的数据以事件形式写入 TE 项目中：
- 使用数据中的 event_time 字段，作为事件的数据时间 #event_time
- 使用数据中的 event_name 作为数据的事件名
- 其他字段将全数入库
# 4.2 标准化字段
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| account_id | te_ads_object.ad_account_id | 广告账号 ID |
| adplan_name | te_ads_object.campaign_name | 广告计划名 |
| adplan_id | te_ads_object.campaign_id | 广告计划 ID |
| adgroup_name | te_ads_object.ad_group_name | 广告组名，变现广告的 Unit 名 |
| adgroup_id | te_ads_object.ad_group_id | 广告组 ID，变现广告的 Unit ID |
| adcreative_name | te_ads_object.ad_name | 广告名 |
| adcreative_id | te_ads_object.ad_id | 广告 ID |
| placement_id | te_ads_object.placement | 广告位置 |
| channel_name | te_ads_object.media_source | 媒体渠道或变现渠道 |
| bundleid | te_ads_object.app_id | 应用 ID |
| app_name | te_ads_object.app_name | 应用名 |
| app_platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| country | te_ads_object.country | 国家地区编码 |