# Tenjin 实时回调接口
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 实时回调接口 | 回传 | 用户级别 | ✅ | ✅ |
Tenjin 提供了配置实施回调链接 (opens new window)的方法，您可以通过回传激活事件获取用户粒度的归因数据。
在开始接入 Tenjin 实时回调数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 登录 TE 后台，进入三方集成模块，新增 Tenjin 实时回调接口方案，并完成相关配置
- 在 Tenjin 后台配置 Webhooks，传入 TE 的回调链接
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、方案配置
接入 Tenjin 回调数据的第一步，需要您登录 TE 系统后台，在「三方集成」模块中完成 Tenjin 实时回调接口方案的配置。下图是 Tenjin 实时回调接口方案的配置界面：
# 1.1 事件表入库设置
打开「事件表入库设置」开关后，Tenjin 回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 1.2 用户属性入库规则
在默认情况下，TE 系统不会将 Tenjin 回传数据中写入到用户属性中。由于 Tenjin 中不存在 TE 系统的用户识别字段，回传数据无法和 TE 用户进行绑定，因此不建议您开启用户属性入库
# 1.3 集成配置
您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义。 |
# 1.4 终端地址
# 1.4.1 默认配置
若您配置了系统和项目级别数据上报地址，则显示如下链接，您可以直接复制该地址：
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到 Tenjin 实时回调接口配置页的「终端地址」复制终端地址。
# 1.4.2 自定义宏
Tenjin 实时回调接口的回调地址中包含一种称为宏的结构，表示方法为。宏可以被认为是一种占位符，当 Tenjin 需要回传的数据中包含与宏对应的字段。以 $为例， Tenjin 会在回传数据时，将 Campaign 的值填入回调地址中宏所在位置。
请将您刚刚获取的终端地址，替换以下地址中的开头部分，请将替换后的回调地址复制下来，之后在 Tenjin 后台中需要填入该地址：
https://{终端地址}?bundle_id={{bundle_id}}&platform={{platform}}&store_id={{store_id}}&time_in_ms={{time_in_ms}}&engaged_at_s={{engaged_at_s}}&acquired_at_ms={{acquired_at_ms}}&advertising_id={{advertising_id}}&developer_device_id={{developer_device_id}}&allow_ad_tracking={{allow_ad_tracking}}&ip_address={{ip_address}}&country={{country}}&campaign_name={{campaign_name}}&tenjin_campaign_id={{tenjin_campaign_id}}&click_id={{click_id}}&referrer={{referrer}}&site_id={{site_id}}&ad_network={{ad_network}}&device={{device}}&os_version={{os_version}}&app_version={{app_version}}&sdk_version={{sdk_version}}&language={{language}}&user_agent={{user_agent}}&creative_name={{creative_name}}&device_brand={{device_brand}}&device_model={{device_model}}&carrier={{carrier}}&locale={{locale}}&timezone={{timezone}}&tracking_status={{tracking_status}}
# 二、Tenjin 后台配置
# 2.1 设置方法
首先，登录 Tenjin 后台，在「CONFIGURE」-「Apps」中选择您需要配置的应用，点击「+ New Callback」新增回调
点击右上角的「Create Custom Callback」
- 触发事件选择「App Open」事件
- 触发条件可以选择「Ping on Every Install」
- 回调地址处，您可以填写 1.4.2 章节我们推荐的宏
完成配置后，您可以看到如下图所示的配置信息，Active 处显示为 true，代表回调配置完毕
# 2.2 推荐设置的宏
回调链接宏是配置在回调链接中的占位字段，当数据回传时，Tenjin 会将字段值替换这些宏。因此，宏决定了回传的字段有哪些。
下表所示的是我们推荐设置的宏，这些宏也是我们在 1.4.2 中提供的带宏回调地址中所使用的。您可以访问 Tenjin 官网获取更为详细的宏列表，如果您希望调整设置的宏，请自行修改 Tenjin 回调中的 Callback URL。
| 宏 | 描述 |
|---|---|
| Bundle ID (如 com.tenjin.wordfinder) | |
| 平台 | |
| App Store ID (数字部分) | |
| 请求时间（毫秒级） | |
| 点击或曝光的时间戳（秒级） | |
| 安装的时间戳（毫秒级） | |
| 设备的广告标识 ID | |
| IDFV 或开发者的 Device ID | |
| 是否允许广告追踪? (true, false 分别代表允许和不允许) | |
| IP 地址 | |
| 用户设备的 Country code | |
| 归因 Campaign 名 | |
| 归因 Campaign ID | |
| Channel 的 click ID | |
| Android 端的 referrer | |
| Channel 的 site ID | |
| 来源渠道名 | |
| 设备型号 | |
| 设备系统版本 | |
| App 版本 | |
| Tenjin SDK 的版本 | |
| 设备的语言 | |
| 设备的 User Agent | |
| 创意名 | |
| 设备品牌 | |
| 设备机型 | |
| 设备运营商 | |
| 本地化信息 | |
| 设备时区 | |
iOS 设备的 ATT 授权状态.
0 => 待定, 1 => 受限制, 2 => 已拒绝, 3 => 授权 |
# 三、数据入库
# 3.1 入库规则
- 由于 Tenjin 中不存在 TE 系统的用户识别字段，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 time_in_ms 字段，作为事件的 #event_time
- 默认的事件名为 -- tenjin_callback
- 回调链接中配置的其他字段将全数入库
TIP
如果您需要将用户粒度回调数据关联到 TE 用户上，那么您需要在用户属性中记录 GAID 与 IDFA（推荐记录在一个用户属性上），在通过数据回溯的方式，将 Tenjin 回调数据关联到 TE 用户上
# 3.2 标准化字段
Tenjin 实时回调数据中的部分字段，TE 系统会进行标准化处理
| 原字段 | 标准化字段 | 含义 |
|---|---|---|
| campaign_name | te_ads_object.campaign_name | 广告计划名 |
| tenjin_campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| creative_name | te_ads_object.ad_name | 广告名 |
| ad_network | te_ads_object.media_source | 媒体渠道 |
| bundle_id | te_ads_object.app_id | 应用 ID |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| country | te_ads_object.country | 国家地区编码 |