目录
此内容是否有帮助?

# TopOn 集成方案（WIP）

本文将介绍如何在 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 识别一个用户

# 集成流程

  1. 接入 TopOn 客户端 SDK (opens new window) 与 TE SDK，在 TopOn SDK 设置 TE 的用户识别 ID
  2. 登录 TopOn 后台，获取 Publisher Key 和 APP Key
  3. 登录 TE 后台，进入三方集成模块，新增 TopOn 集成，创建集成方案，并执行单次拉取同步数据
  4. 查看 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 报表建议

以下提供几个构建报表的建议：

  1. 在事件分析模型中，使用 TopOn 的数据搭建广告变现核心指标，创建广告分析报表
  2. 在留存分析模型中，结合 TopOn 数据的广告变现信息与游戏内付费事件，计算包含广告变现的 LTV

# 六、常用 FAQ

请参考‌⁣⁢‌‬‍⁢⁣‌⁡⁢‬‬⁢⁡⁤⁢⁡⁡‬‌⁡⁡‬⁡⁣⁣‬‬⁣‬ TopOn FAQ (opens new window)

← 巨量引擎集成方案（WIP） →