menu
Is this helpful?

# TopOn 综合报表查询 API

TIP

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

# 概要

# 接口简介

接口名 类型 粒度 归因 成本 收益 展示 点击 转化
综合报表查询 API API 聚合指标

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

# 集成流程

  1. 登录 TopOn 后台,获取 Publisher Key 和 APP ID
  2. 登录 TE 后台,进入三方集成模块,新增 TopOn 集成,创建集成方案,并执行单次拉取同步数据
  3. 查看 TE 系统否成功接收数据,并完成报表搭建

# 一、TopOn 后台信息获取

在拉取数据前,您需要先向 TopOn 对接人申请开通数据报表查询 API 权限,开通成功后,可在开发者后台的账号管理页面查看 Publisher Key。

接下来,请前往 TopOn 后台的应用页,获取您需要接入数据的应用的应用 ID

# 二、方案配置

当您完成了 SDK 配置并获得 Publisher Key 与 App ID 后,您可以登录 TE 系统,在「三方集成」模块中完成新方案的配置。下图是 TopOn 综合报表查询 API 的配置界面,请您按照本章节内容完成方案的创建:

# 2.1 授权信息配置

点击「授权信息」按钮,在弹出框内填写您在授权工作中获取到的信息

其中:

  • APP ID:刚刚获得的应用 ID
  • Publisher Key:即刚刚获得的 Publisher Key
  • Brand:原 TopOn 将旗下业务进行了划分(详见本文 (opens new window)),您需要填写您所使用的具体业务品牌
    • 如果您使用的是 Taku,官网地址为 takuad.com,则填入taku(若不填写,则也视为 taku)
    • 如果您使用的是 TopOn,官网地址为 www.toponad.com,则填入topon

# 2.2 定时拉取

您可以在「定时拉取」模块设置 TE 系统定时拉取 TopOn 综合报表查询 API 的策略,可以选择在每天的某时或者每小时拉取一段时间的数据。由于拉取的数据也会计算再数据量中,建议您在不要定时拉取太长时间的数据

# 2.3 拉取时区

您还可以设置拉取的数据的时区,默认为 UTC+8

# 2.4 事件表入库设置

打开「事件表入库设置」开关后,回传的数据都将写入到事件表中,我们建议您开启事件数据入库。

# 2.5 集成配置

您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据拉取的指标字段与维度,以及入库后的事件名等。

集成配置中的内容是一个 JSON,您可以按照以下内容进行自定义配置:

模块 名称 含义
sink_event event_name 入库后的事件名,可以自定义
source metrics 数据中的指标,列表类型,不同层级支持不同的 metrics,填写时需要注意
group_by 数据中的分组维度,列表类型,不同层级支持不同的 group_by,填写时需要注意
- 分组维度

下列表格中展示的是综合报表查询 API 所有支持的分组维度,请注意:查询 10 天以内的数据最多可选择 6 个分组维度,查询 10 天前的数据最多选 3 个分组维度,time_zone 和 currency 不占用分组维度数量。如需调整,请将分组维度加入到 source.group_by 中:

分组维度 入库字段名 类型 是否默认 备注

date

date 字符串 日期,格式:YYYYmmdd

app

app_id 字符串 开发者后台的应用ID
app_name 字符串 应用名称
app_platform 字符串 应用的系统平台
app_pkg_name 字符串 应用的包名

placement

placement_id 字符串 开发者后台的广告位 ID
placement_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_id

network_firm_id 字符串 广告平台 ID
network_firm 字符串 广告平台名称

必有

time_zone 字符串 时区,枚举值:UTC+8、UTC+0、UTC-8
currency 字符串 开发者账号币种,该字段与revenue字段组成的收益需与开发者后台报表的收益一致

adformat

adformat 字符串 广告样式,枚举值:Rewarded Video、Interstitial、Banner、Native、Splash

area

area 字符串 国家(地区)码

network

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

scenario

scenario_id 字符串 广告场景 ID
scenario_name 字符串 广告场景名称

traffic_group

traffic_group_id 字符串 流量分组id
traffic_group_name 字符串 流量分组名称
traffic_group_segment_id 字符串 流量分组数字 ID,注意:默认流量分组时 segment_id = 0,不会返回

channel

channel 字符串 渠道名称

sdk_version

sdk_version 字符串 SDK版本

app_version

app_version 字符串 应用版本
- 指标字段

默认情况下,我们会选取以下所有字段入库,如果需要进行调整,可以修改 source.metrics:

字段 备注
new_user_rate 新增用户占比
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一样

# 2.6 事件入库规则

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

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

# 2.7 标准化字段

TopOn 综合报表查询 API 中的部分字段,TE 系统会进行标准化处理

字段 标准化字段 含义
adsource_name te_ads_object.ad_name 广告名
adsource_id te_ads_object.ad_id 广告 ID
placement_name te_ads_object.placement 广告位置
network_firm te_ads_object.media_source 变现渠道
app_pkg_name te_ads_object.app_id 应用 ID
app_name te_ads_object.app_name 应用名
app_platform te_ads_object.platform 平台,即 Android、iOS 等
area te_ads_object.country 国家地区编码
currency te_ads_object.currency 成本或收益的币种
impression te_ads_object.impressions 曝光量
click te_ads_object.clicks 点击量
revenue te_ads_object.revenue 变现收益