跳到主要内容

TopOn 数据集成解决方案

最近更新 2026/10/05

最后更新时间：2022-08-17

一、集成前准备​

提示

请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量

1. 概览​

本文将介绍如何将 TopOn 数据回传到 Agentic Engine（后文简称 AE 系统） ，本方案支持以下三种方式，可点击接口名称跳转到对应的方案部分：

接口描述API 类型产品化数据更新频率
设备层级数据报告 API聚合数据拉式是仅支持拉取两天前数据T2
综合报表聚合数据拉式否可拉取当天数据T0
客户端 SDK 上报用户明细客户端SDK-实时

在开始接入 TopOn 数据前，请确保您已经阅读 AE 系统数据规则，理解 AE 的数据结构。另外，建议您将拉取数据所需的信息交给我们的客户成功经理，格式可参考数据集成配置信息模板（设备层级数据报告 API、综合报表）。

二、设备层级数据报告 API（已产品化）​

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
设备层级数据报告 API拉式是用户级别是是是

设备层级数据报告 API 可以获取以用户为维度的聚合指标，包括了用户在一段时间内的总展示、点击以及收益数据。

2.1 API 权限​

在拉取数据前，您需要先向 TopOn 对接人申请开通设备层级数据报告 API 权限，开通成功后，可在开发者后台的账户信息页面查看 Publisher Key。请将 Publisher Key 与 TopOn 后台项目的应用 ID 发送给 AE 工作人员，或填写在数据集成配置信息模板中。

在账户信息页面可获取 Publisher Key

在应用页面可查看 TopOn 项目的应用 ID

2.2 客户端 SDK 配置​

警告

报表数据的 user_id 属性 Android 应用基于成本考虑默认不返回，如果需要请优先升级 SDK 版本到 5.9.70 以上，并联系 TopOn 运营人员沟通权限

方案一（自动集成）：

提示

如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，推荐使用自动关联方案

如果您接入的 AE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件

本方案是自动集成方案，请在初始化 AE 客户端 SDK 后调用以下代码开启，详情请参考安卓 SDK 三方数据 与 iOS SDK 三方数据

// 初始化 AE 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，传入值为 AE 项目的访客 ID。

方案二（手动集成）：

手动集成方案需要您通过 TopOn 的 App 全局自定义规则设置，将 AE 的 #distinct_id 传进 TopOn SDK 的 custom_rule 里面的 user_id ，调用方法和代码实例可以参考该文档。

iOS 客户端代码配置样例：

[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:self.TA_DISTINCT_ID}];

安卓客户端代码配置样例：

// 获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String te_distinct_id = instance.getDistinctId();

Map<String, String> customMap = new HashMap<>(); 
customMap.put(ATCustomRuleKeys.USER_ID, te_distinct_id); 
ATSDK.initCustomMap(customMap);
警告

注意（非常重要）：

通过 setCustomData (iOS) 方法或 initCustomMap (Android) 的上报需要在 TopOn SDK 初始化之前完成；否则，部分 user_id 可能会无法回传。

2.3 数据拉取​

2.3.1 涵盖字段​

设备层级数据报告 API 涵盖了以下字段

字段类型备注
placement_id字符串广告位ID
placement_name字符串广告位名称
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数值收益，根据三方广告平台的收益对设备层级进行拆分，货币单位同开发者后台配置一致

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字符串广告平台名称
currency字符串开发者账号币种，USD表示美元，CNY表示人民币
os_version字符串iOS设备的操作系统版本
att_status字符串

iOS设备的ATT授权状态：

0：Not determined(未决定是否授权) ；1：Restricted (受限制)；2：Denied(已拒绝)；3：Authorized(已授权)

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_revenuedecimal(18,6)预估收益，竞价广告源以实时的广告展示价格汇总得出预估收益，非竞价广告源以人工填写的eCPM价格 * TopOn统计的展示汇总得出预估收益

2.3.2 接口参数​

  • 时间：

    • 拉取以某一日为开始时间的数据，仅支持从 2 天前开始
    • 时区可以选择 UTC 0，-8，+8，不传则默认使用开发者账号时区

  • App：

    • 需要指定拉取数据的 App，需要提供 TopOn 后台的应用 ID

2.3.3 数据入库规则​

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

  • 使用数据中的 user_id 作为数据中的访客 ID，该字段应可对应 AE 项目中的访客ID
  • 使用拉取数据的开始时间字段，作为事件的 #event_time
  • 数据事件名为 -- ta_ad_revenue_topon
  • 其他字段将全数入库

2.4 数据集成配置信息模板​

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

数据接口：TopOn 设备层级数据报告 API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
TopOn App ID：XXX
TopOn Publisher Key：XXX
---------
拉取时区：UTC+8 (枚举值：UTC-8、UTC+8、UTC+0，不传则默认使用开发者账号时区)
历史数据拉取时间范围：从 yyyy/mm/dd 开始（至少 2 天前）
定时拉取：每天 X 点拉取过去 X 天的数据

三、综合报表​

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
综合报表拉式否聚合数据是是是

综合报表 是 TopOn 数据报表查询 API 中的综合报表数据，提供了聚合的广告变现数据，包含展示、点击以及收益指标。

3.1 API 权限​

在拉取数据前，您需要先向 TopOn 对接人申请开通数据报表查询 API 权限，开通成功后，可在开发者后台的账户信息页面查看 Publisher Key。请将 Publisher Key 与 TopOn 后台项目的应用 ID 发送给 AE 工作人员，或填写在数据集成配置信息模板中。

在账户信息页面可获取 Publisher Key

在应用页面可查看 TopOn 项目的应用 ID

3.2 数据拉取​

3.2.1 分组维度​

下列表格中展示的是综合报表查询 API 所有支持的分组维度，请注意：查询 10 天以内的数据最多可选择 6 个分组维度，查询 10 天前的数据最多选 3 个分组维度：

分组维度字段类型是否默认备注
datedate字符串是日期，格式：YYYYmmdd

app

app_id字符串是开发者后台的应用ID
app_name字符串是应用名称
app_platform字符串是应用的系统平台
app_pkg_name字符串是应用的包名
placementplacement_id字符串是开发者后台的广告位 ID
placement_name字符串是广告位名称

adformat

adformat字符串广告样式，枚举值：Rewarded Video、Interstitial、Banner、Native、Splash
areaarea字符串国家（地区）码

network

network字符串广告平台账号 ID
network_name字符串广告平台账号名称

adsource

adsource_network字符串是广告源所属的广告平台名称
adsource_token_position_id字符串是广告源的位置 ID
adsource_token_orientation字符串是广告源的方向
adsource_token_video_muted字符串是广告是否静音
adsource_token_app_id字符串是广告源的 App ID
adsource_token_app_name字符串是广告源的 App 名称
adsource_id字符串是广告源id
adsource_name字符串是广告源名称
network_firm_idnetwork_firm_id字符串是广告平台 ID
network_firm字符串是广告平台名称
scenarioscenario_id字符串广告场景 ID
scenario_name字符串广告场景名称

traffic_group

traffic_group_id字符串流量分组id
traffic_group_name字符串流量分组名称
traffic_group_segment_id字符串流量分组数字 ID，注意：默认流量分组时 segment_id = 0,不会返回
channelchannel字符串渠道名称
sdk_versionsdk_version字符串SDK版本
app_versionapp_version字符串应用版本

3.2.2 指标字段​

默认情况下，我们会选取以下所有字段入库，如果需要进行调整，可以记录在数据集成配置信息模板：

字段类型备注
time_zone字符串时区，枚举值：UTC+8、UTC+0、UTC-8
currency字符串开发者账号币种，该字段与revenue字段组成的收益需与开发者后台报表的收益一致
new_users数值新增用户
new_user_rate数值新增用户占比
day2_retention数值次日留存
deu数值DEU
engaged_rate数值渗透率
imp_dau数值展示 / DAU
imp_deu数值展示 / DEU
impression_rate数值展示率
dau数值根据group_by条件才有返回
arpu数值有dau才有该项返回
request数值请求数
fillrate数值填充率
impression数值展示数
click数值点击数
ctr数值点击率
ecpm数值TopOn通过报表API向广告平台拉取到的实际收益和TopOn统计的展示计算出eCPM，计算公式：（收益/TopOn统计的展示）*1000。注：eCPM延迟1天提供
revenue数值三方广告平台的收益，币种为开发者账号币种
request_api数值三方广告平台的请求数
fillrate_api数值三方广告平台的填充率
impression_api数值三方广告平台的展示数
click_api数值三方广告平台的点击数
ctr_api数值三方广告平台的点击率
ecpm_api数值TopOn通过报表API向广告平台拉取到的实际收益和展示API计算出eCPM API，计算公式：（收益/展示API）*1000。注：eCPM API延迟1天提供
estimate_revenue数值预估收益，币种：美元

estimate_revenue_ecpm

数值根据预估收益和TopOn统计的展示计算出预估eCPM，计算公式：（预估收益/TopOn统计的展示）*1000。注：1、预估 eCPM当天提供；2、常规广告源基于手动填写的eCPM价格计算，竞价广告源基于实时竞价价格计算
ready_request数值isReady调用次数
ready_rate数值isReady成功率
cy_estimate_revenue数值按开发者账号币种返回的预估收益
cy_estimate_revenue_ecpm数值按开发者账号币种返回的预估eCPM，计算方式和estimate_revenue_ecpm一样
load数值流量请求，注意：当选了某些group_by维度(例如：network_firm_id)，响应为“0”
load_fillrate数值流量填充率，注意：当选了某些group_by维度(例如：network_firm_id)，响应不返回该指标

3.2.3 接口参数​

  • 时间：

    • 拉取以日为时间单位的数据
    • 时区可以选择 UTC 0，-8，+8，不传则默认使用开发者账号时区

3.2.4 数据入库规则​

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

  • 由于 综合报表查询 API 返回的是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
  • 使用数据中的 date 字段，即数据的日期，设置为聚合数据的 #event_time
  • 数据事件名为 -- topon_fullreport
  • 其余字段都将会入库

3.3 数据集成配置信息模板​

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

数据接口：TopOn 综合报表查询 API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
TopOn App ID：XXX
TopOn Publisher Key：XXX
---------
拉取时区：UTC+8 (枚举值：UTC-8、UTC+8、UTC+0)
分析维度：xxx，xxx
拉取指标：xxx，xxx
历史数据拉取时间范围：从 yyyy/mm/dd 开始（至少 2 天前）
定时拉取：每天 X 点拉取最近 X 天的数据

四、客户端 SDK 上报​

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
ATAdInfo 回调接口客户端 SDK否用户明细是是

TopOn 客户端 SDK 有 ATAdInfo 回调接口，可以通过 getEcpm() 等方法获取预估 eCPM 值和其他相关维度和指标，然后再通过 AE SDK 上报到 AE 系统。

以 Android SDK 为例，接收收入数据并传入 AE 的代码示例：

ATBannerView mBannerView = new ATBannerView(this);
mBannerView.setBannerAdListener(new ATBannerExListener() {
    @Override
    public void onBannerShow(ATAdInfo entity) {
        JSONObject properties = new JSONObject();
        try{
            properties.put("id", entity.getShowId());
            properties.put("publisher_revenue", entity.getPublisherRevenue());
            properties.put("currency", entity.getCurrency());
            properties.put("country", entity.getCountry());
            properties.put("adunit_id", entity.getTopOnPlacementId());
            properties.put("adunit_format", entity.getTopOnAdFormat());
            properties.put("precision", entity.getEcpmPrecision());
            properties.put("network_type", entity.getAdNetworkType());
            properties.put("network_placement_id", entity.getNetworkPlacementId());
            properties.put("ecpm_level", entity.getEcpmLevel());
            properties.put("segment_id", entity.getSegmentId());
            properties.put("scenario_id", entity.getScenarioId());
            properties.put("scenario_reward_name", entity.getScenarioRewardName());
            properties.put("scenario_reward_number", entity.getScenarioRewardNumber());
            properties.put("channel", entity.getChannel());
            properties.put("sub_channel", entity.getSubChannel());
            properties.put("custom_rule", entity.getCustomRule());
            properties.put("network_firm_id", entity.getNetworkFirmId());
            properties.put("adsource_id", entity.getAdsourceId());
            properties.put("adsource_index", entity.getAdsourceIndex());
            properties.put("adsource_price", entity.getEcpm());
            properties.put("adsource_isheaderbidding", entity.isHeaderBiddingAdsource());
            properties.put("ext_info", entity.getExtInfoMap());
        }catch(JSONException e){
        }
        // 将收入数据上报到 AE，事件名称为 topon_sdk_ad_info
        instance.track("topon_sdk_ad_info", properties);
    }
});

数据上报后，可以基于事件名为 topon_sdk_ad_info 的事件在 AE 系统进行相关维度和指标的分析。

五、联调测试和数据使用​

5.1 联调测试​

可以在实时入库、事件分析或 SQL IDE 里查找以下事件：

  • 设备层级报告 API 数据： ta_ad_revenue_topon
  • 综合报表查询 API 数据： topon_fullreport
  • 客户端 SDK 实时回调接口：topon_sdk_ad_info

5.2 数据使用​

  • 把 AE SDK 上报的内购和通过 TopOn 获取的广告变现收入加和做比较完整 ROI 的分析

通过广告获取的非自然用户产生的收益 (包括订阅付费、应用下载付费、应用内事件付费、广告变现) 除以买量成本，因为在计算过程中需要用户级别数据，所以使用设备层级数据报告API。

  • 「渠道来源」虚拟事件属性创建

事件属性和用户属性的归因数据通过虚拟属性合成一个虚拟事件属性再作为分组项

channel_final = coalesce(channel(cost), network_name)
  • 通过预估 eCPM 实时计算用户级别广告收益

TopOn 的预估 eCPM 准确性可以满足分析需求，并且其实时性也具有价值，可以考虑使用 TopOn 客户端 SDK 实时回调接口返回的预估 eCPM， 在 AE 系统内计算用户级别广告收益。

adsource_priceString根据预估收益和TopOn统计的展示计算出预估eCPM，计算公式：（预估收益/TopOn统计的展示）*1000。注：1、通过客户端 SDK 实时回调接口预估 eCPM当天提供；2、常规广告源基于手动填写的eCPM价格计算，竞价广告源基于实时竞价价格计算
  • 使用广告源ID（adsource_id），计算每次曝光收益
  • 事件属性集成后数据类型

为了提高数据使用的灵活性，事件属性默认「按字符串类型接入」，您可以通过 AE 系统的虚拟属性功能将字符串类型的字段转换为其他类型，例如：

  • 将 revenue 属性转换为数值类型："revenue" （数据类型选择数值）
  • topon_fullreport 全局筛选 app_pkg_name 有值

可以在使用 topon_fullreport 数据时，全局筛选 app_pkg_name 有值，这样可以排除干扰数据

  • 获取 iOS 设备的 ATT 授权状态

通过 iOS 的设备层级 API 可以得到设备的 ATT 授权状态：

0：Not determined(未决定是否授权)；1：Restricted (受限制)；2：Denied(已拒绝)；3：Authorized(已授权)

六、FAQ​

如何区分 TopOn 设备层级 API 和综合报表 API 传来的数据？​

可以根据事件名区分，ta_ad_revenue_topon 是设备层级的，topon_fullreport 是综合报表的

这篇文档对你有帮助吗？
本页内容