# TradPlus 综合报表查询 API
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 综合报表查询 API | API | 聚合指标 | ✅ | ✅ | ✅ |
综合报表查询 API (opens new window) 提供了广告变现的聚合指标数据，包括广告展示次数、点击次数以及收益等指标。
# 集成流程
- 登录 TradPlus 后台，获取 Access Token和应用ID
- 登录 TE 后台，进入三方集成模块，新增 TradPlus 综合报表查询 API 集成方案
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、TradPlus 后台信息获取
完成 SDK 的配置后，您需要登录 TradPlus 后台，获取 Access Token和应用ID
- Access token 可以通过 TradPlus 后台「我的账号」-「报表API key」-点击「生成 key」获取
- 应用 ID 可在「应用管理」-「应用 & 广告位」中查看
# 二、方案配置
当您完成了 SDK 配置并获得 Access Token和应用ID 后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 TradPlus 综合报表查询 API 的配置界面，请您按照本章节内容完成方案的创建：
# 2.1 授权信息配置
点击「授权信息」按钮，在弹出框内填写您在授权工作中获取到的信息
# 2.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 TradPlus 综合报表查询 API 的策略，可以选择在每天的某时或者每小时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 2.3 拉取时区
您还可以设置拉取的数据的时区，默认为 UTC+8
# 2.4 事件表入库设置
打开「事件表入库设置」开关后，回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.5 集成配置
您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义 |
| source | metrics | 数据中的指标，列表类型，不同层级支持不同的 metrics，填写时需要注意 |
| group_by | 数据中的分组维度，列表类型，不同层级支持不同的 group_by，填写时需要注意 |
下列表格中展示的是综合报表查询 API 所有支持的分组维度。请注意，部分维度添加后，可能您将无法查询到一些指标字段。如需调整，请将分组项加入到 source.group_by 中：
| 分组项 | 字段 | 默认 | 备注 |
|---|---|---|---|
| date | date | 是 | 日期，格式：YYYY-mm-dd |
| appId | app_id | 是 | 应用ID （TradPlus） |
| platform | 是 | 应用的系统平台 (1 Android, 2 iOS) | |
| package_name | 是 | 包名 | |
| placementId | placement_id | 是 | 广告位ID （TradPlus） |
| placement_name | 是 | 广告位名字 （TradPlus） | |
| adFormat | ad_format | 是 | 广告位类型 |
| ad_format_name | 是 | 广告位类型名字 | |
| area | area | 是 | 国家地区编码(ISO 3166-1二位国家地区代码) |
| network | network | 是 | 广告网络ID |
| network_name | 是 | 广告网络名字 | |
| networkPlacementId | network_placement_id | 是 | 广告网络的广告位ID信息 |
| network_placement_name | 是 | 广告网络的广告源名称 （TradPlus） | |
| network_placement_info | 是 | 广告网络的广告位详细信息 | |
| adSceneId | ad_scene_id | 广告场景ID | |
| ad_scene_name | 广告场景名称 | ||
| sdk | sdk | SDK 版本 | |
| channel | channel | 渠道 | |
| appVersion | app_version | 应用版本 | |
| idfa | idfa | IDFA 授权 | |
| bucketId | bucket_id | A/B 测试分组 |
默认情况下，我们会选取部分字段入库，如果需要进行调整，可以将指标字段名填入 source.metrics：
| 指标字段 | 入库名 | 默认 | 备注 |
|---|---|---|---|
| dau | dau | 是 | TradPlus 统计的日活跃用户数量(app级别) |
| deu | deu | 是 | TradPlus 统计的每日观看广告用户数 |
| arpu | arpu | 是 | TradPlus 统计的用户平均收入 |
| newUsers | new_users | 是 | TradPlus 统计的新增用户(app级别) |
| newUserRate | new_user_rate | 是 | TradPlus 统计的新增用户占比(app级别) |
| bidRequestApi | bid_request_api | 三方广告网络的竞价请求数 | |
| bidResponseApi | bid_response_api | 三方广告网络的竞价响应数 | |
| bidResponseRateApi | bid_response_rate_api | 三方广告网络的竞价响应率 | |
| bidWinRateApi | bid_win_rate_api | 三方广告网络的竞价胜出率 | |
| requestApi | request_api | 是 | 三方广告网络的请求数 |
| fillApi | fill_api | 是 | 三方广告网络的填充数 |
| fillrateApi | fillrate_api | 是 | 三方广告网络的填充率 |
| impressionApi | impression_api | 是 | 三方广告网络的展示数 |
| clickApi | click_api | 是 | 三方广告网络的点击数 |
| ctrApi | ctr_api | 是 | 三方广告网络的点击率 |
| ecpmApi | ecpm_api | 是 | 三方广告网络的ECPM |
| revenue | revenue | 是 | 三方广告网络的收益 |
| appRequest | app_request | TradPlus 统计的应用请求数 | |
| enterAdScene | enter_ad_scene | TradPlus 统计的进入广告场景次数 | |
| enterAdSceneUsers | enter_ad_scene_users | TradPlus 统计的进入广告场景用户数 | |
| bidRequest | bid_request | TradPlus 统计的竞价请求数 | |
| bidResponse | bid_response | TradPlus 统计的竞价响应数 | |
| bidResponseRate | bid_response_rate | TradPlus 统计的竞价响应率 | |
| bidWinRate | bid_win_rate | TradPlus 统计的竞价胜出率 | |
| request | request | 是 | TradPlus 统计的请求数 |
| fill | fill | 是 | TradPlus 统计的填充数 |
| fillrate | fillrate | 是 | TradPlus 统计的填充率 |
| impression | impression | 是 | TradPlus 统计的展示次数 |
| impressionRatio | impression_ratio | 是 | TradPlus 统计的展示占比 |
| click | click | 是 | TradPlus 统计的点击次数 |
| clickUsers | click_users | 是 | TradPlus 统计的点击用户数 |
| ctr | ctr | 是 | TradPlus 统计的点击率 |
| estimateRevenue | estimate_revenue | 是 | TradPlus 统计的预估收益 |
| eventRevenue | event_revenue | 是 | TradPlus 统计的埋点收入 |
# 2.6 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 TE 项目中：
- 使用数据中的 date 字段，即数据的日期，作为事件的 #event_time
- 数据事件名为 -- tradplus_allreport
- 其他字段将全数入库
# 2.7 标准化字段
TradPlus 设备层级数据报告中的部分字段，TE 系统会进行标准化处理
| 原字段 | 标准化字段 | 含义 |
|---|---|---|
| network_name | te_ads_object.media_source | 变现渠道 |
| package_name | te_ads_object.app_id | 应用 ID |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| package_name | te_ads_object.placement | 广告位置 |
| area | te_ads_object.country | 国家地区编码 |
| impression | te_ads_object.impressions | 曝光量 |
| click | te_ads_object.clicks | 点击量 |
| revenue | te_ads_object.revenue | 变现收益 |