# TopOn 综合报表查询 API
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 综合报表查询 API | API | 聚合指标 | ✅ | ✅ | ✅ |
综合报表 (opens new window)指的是 TopOn 数据报表查询 API 中的综合报表数据，提供了聚合的广告变现数据，包含展示、点击以及收益指标。
# 集成流程
- 登录 TopOn 后台，获取 Publisher Key 和 APP ID
- 登录 TE 后台，进入三方集成模块，新增 TopOn 集成，创建集成方案，并执行单次拉取同步数据
- 查看 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
- 如果您使用的是 Taku，官网地址为 takuad.com，则填入
# 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 | 变现收益 |