# TopOn 集成方案
本文将介绍如何在 TE 后台接入 TopOn 数据，目前 TE 后台支持接入的是 TopOn 的设备层级数据报告 API (opens new window) ，如需了解如何接入 TopOn 的其他接口数据，请参考 TopOn 数据集成解决方案 (opens new window)
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 集成类型 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|
| 设备层级数据报告 API | API | 用户级别 | ✅ | ✅ | ✅ |
设备层级数据报告 API (opens new window)可以获取以用户为维度的聚合指标，包括了用户在一段时间内的总展示、点击以及收益数据。因此 TE 系统会单独拉取每个用户每天的数据，也就是一个用户在每天的广告展示数、点击数以及收益情况。
在开始接入 TopOn 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 接入 TopOn 客户端 SDK (opens new window) 与 TE SDK，在 TopOn SDK 设置 TE 的用户识别 ID
- 登录 TopOn 后台，获取 Publisher Key 和 APP Key
- 登录 TE 后台，进入三方集成模块，新增 TopOn 集成，创建集成方案，并执行单次拉取同步数据
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
集成 TopOn 数据的第一步，是在客户端完成 TE SDK 与 TopOn SDK 的打通，在 TopOn SDK 中设置 TE 系统的用户识别 ID
# 1.1 方案一（自动集成）
- 如果您接入的 TE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
- 如果您接入的 TE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
本方案是自动集成方案，请在初始化 TE 客户端 SDK 后调用以下代码开启：
// 初始化 TE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// 开启 TopOn ID 关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
// 初始化 TopOn SDK
// ...
// 修改访客ID之后，需要再次同步数据(可选)。
instance.identify("distinct_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
该方案的原理就是内部自动调用 ATSDK 的 initCustomMap 方法，传入 ATCustomRuleKeys.USER_ID，传入值为 TA 项目的访客 ID。
# 1.2 方案二（手动集成）
通过 TopOn 的 App 全局自定义规则设置，将 TA 的 distinct_id 传进 TopOn SDK 的 custom_rule 里面的 user_id ，调用方法和代码实例可以参考该文档 (opens new window)。
iOS 客户端代码配置样例：
[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:self.TA_DISTINCT_ID}];
安卓客户端代码配置样例：
Map<String, String> customMap = new HashMap<>();
customMap.put(ATCustomRuleKeys.USER_ID,"ta_distinct_id");
ATSDK.initCustomMap(customMap);
注意（非常重要）
通过 setCustomData (iOS) 方法或 initCustomMap (Android) 的上报需要在 TopOn SDK 初始化之前完成；否则，部分 user_id 可能会无法获取。
# 二、TopOn 后台信息获取
完成 SDK 的配置后，您需要登录 TopOn 后台获取拉取数据所需的授权信息。
为了获取授权信息，您需要先向 TopOn 对接人申请开通设备层级数据报告 API 权限。开通成功后，可在开发者后台的账号管理页面查看 Publisher Key 与 App Key。请复制这两个信息，在接下来的 TE 系统配置时会用到。
# 三、TE 三方集成页面配置
在完成 SDK 配置并获取 TopOn 的后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 TopOn 的配置。下图是 TopOn 的配置界面，请打开「集成开关」开始 TopOn 的配置：
# 3.1 用户识别与关联
由于 TopOn 仅可以返回一个自定义用户 ID 字段，因此并没有放开识别字段的修改。您需要根据本文档完成客户端 SDK 的配置。那么在 TopOn 的数据中，user_id 即为 TE 系统的访客 ID.
# 3.2 集成参数
接下来，您需要设置拉取数据的配置。主要有两个配置：
- 拉取时区：可以选择 UTC-8、+8、±0 三个时区
- 定时拉取：设置 TE 系统定时拉取的策略，可以选择在每天或者每小时拉取一段时间的数据。请注意，TopOn 设备层级数据报告 API 仅支持拉取过去 29 天的数据。
# 3.3 创建集成方案
为了拉取数据，您还需要创建一个集成方案，将您在 TopOn 后台获取的授权信息填入到集成方案中。如下图所示，为其设置一个方案名，并填入 Publisher Key 与 App Key。
# 3.4 保存配置与单次拉取
最后，请您检查以上配置均填写正确，点击页面右下角的保存配置。至此，您已经完成了所有 TopOn 集成的配置工作。
保存完配置后，我们建议您点击页面右下角的单次拉取按钮，手动触发一次数据拉取。在拉取数据弹窗中，请您设置需要拉取的数据范围，以及哪些方案需要拉取。
# 四、数据入库规则
# 4.1 用户识别规则
由于 TopOn API 数据的字段限制，因此 TopOn API 数据的用户识别规则是固定的，即：
- 账号 ID：不检查，直接留空
- 访客 ID：检查 user_id 是否存在，如果有，将其设置为 #distinct_id。如果没有，则该条数据将被视作无效数据，直接丢弃
# 4.2 事件入库规则
- TE 系统将每天的 0 点，作为事件的 #event_time
- 数据事件名为 -- ta_ad_revenue_topon
- 其他字段将全数入库
# 4.3 包含字段
TopOn 数据中包含以下事件属性，其中部分字段 TE 系统会进行标准化处理：
| 字段 | 备注 | 标准化字段 |
|---|---|---|
| placement_id | 广告位ID | |
| placement_name | 广告位名称 | te_ads_object.placement |
| placement_format | 广告类型： 0：native；1：rewarded_video；2：banner；3：interstitial； 4：splash | |
| android_id | 设备ID，androidid | |
| gaid | Google 的广告设备 ID | |
| idfa | iOS 的设备 ID | |
| area | 国家 | |
| impression | 展示数 | |
| click | 点击数 | |
| revenue | 收益，根据三方广告平台的收益对设备层级进行拆分，货币单位同开发者后台配置一致 | te_ads_object.revenue |
| ecpm | TopOn 基于收益 API 按设备展示拆分后的收益和 TopOn 统计的设备展示计算出 eCPM，计算公式：（设备收益/TopOn统计的设备展示）* 1000。注：eCPM 延迟 2 天提供 | |
| is_abtest | 对照组或测试组： 0：表示对照组或未开通A/B测试；1：表示测试组 | |
| traffic_group_id | 对照组或测试组id | |
| segment_id | 流量分组ID | |
| segment_name | 流量分组名称 | |
| idfv | iOS的设备ID | |
| oaid | 安卓的设备ID | |
| user_id | 开发者的自定义用户ID | |
| network_firm_id | 广告平台ID | |
| network_firm | 广告平台名称 | te_ads_object.media_source |
| currency | 开发者账号币种，USD表示美元，CNY表示人民币 | te_ads_object.currency |
| os_version | iOS设备的操作系统版本 | |
| att_status | iOS设备的ATT授权状态： 0：Not determined(未决定是否授权) ；1：Restricted (受限制)；2：Denied(已拒绝)；3：Authorize(已授权) | |
| imei | 安卓的设备识别码 | |
| device_type | IOS设备类型，枚举值说明： 0：非IOS设备；1：iphone；2：ipad | |
| brand | 设备品牌名 | |
| model | 设备型号 | |
| app_vn | 应用版本名 | |
| app_vc | 应用版本号 | |
| new_user_type | 新用户类型，枚举值说明： 1: 是新用户；2: 不是新用户 | |
| channel | 渠道，由开发者通过TopOn SDK传入的渠道 | |
| estimate_revenue | 预购收益，竞价广告源以实时的广告展示价格汇总得出预估收益，非竞价广告源以人工填写的eCPM价格 * TopOn统计的展示汇总得出预估收益 |
# 4.4 用户属性入库规则
目前 TopOn 没有放开用户属性入库规则。
# 五、后续使用
# 5.1 数据入库检查
最后，请您检查 TE 系统是否接收到了 TopOn 的数据，您可以按照以下方法进行检查：
- 在「数据管理」-「元事件」页面查看 ta_ad_revenue_topon 事件是否被创建。
- 您也可以在事件分析模型中查询 ta_ad_revenue_topon 是否有数据
# 5.2 报表建议
以下提供几个构建报表的建议：
- 在事件分析模型中，使用 TopOn 的数据搭建广告变现核心指标，创建广告分析报表
- 在留存分析模型中，结合 TopOn 数据的广告变现信息与游戏内付费事件，计算包含广告变现的 LTV
# 六、常用 FAQ
请参考 TopOn FAQ (opens new window)
← Adjust 集成方案 巨量引擎集成方案 →