跳到主要内容

TradPlus 数据集成解决方案

最近更新 2026/10/05

最近更新日期：2022-08-22

一、概述​

提示

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

概要​

本文介绍将 TradPlus 的广告变现数据回传到 Agentic Engine（后文简称 AE 系统） ，本方案支持：

在开始接入 TradPlus 之前，请确保您已经阅读 AE 系统数据规则，理解 AE 的数据结构。另外，建议您将拉取数据所需的信息交给我们的客户成功经理，格式可参考数据集成配置信息模板。

流程​

TradPlus 数据的接入流程如下：

  • 接入设备层级数据报告 API
  1. 从 TradPlus 后台获取 Token 和应用 ID，并发送给 AE 工作人员
  2. 在客户端 SDK 中将 AE 项目的访客 ID 设置为 TradPlus 的自定义 ID
  3. 确定数据拉取的数据维度、指标类型、拉取频率以及拉取时间范围
  4. 由 AE 工作人员完成数据拉取开发工作
  5. 在 AE 后台搭建看板、报表，并完成数据验收
  • 综合报表查询 API
  1. 从 TradPlus 后台获取 Token 和应用 ID，并发送给 AE 工作人员
  2. 确定数据拉取的数据维度、指标类型、拉取频率以及拉取时间范围
  3. 由 AE 工作人员完成数据拉取开发工作
  4. 在 AE 后台搭建看板、报表，并完成数据验收

二、授权​

无论您接入哪种数据，您都需要先登录 TradPlus 后台，获取 Access Token 和应用 ID，并将其发送给 AE 工作人员。

  • Access token 可以通过 TradPlus 后台「我的账号」-「报表API key」-点击「生成 key」获取
  • 应用 ID 可在「应用管理」-「应用 & 广告位」中查看

三、设备层级数据报告 API​

接口基本信息

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

设备层级数据报告 API 提供了用户级别的广告变现数据，包括用户在某一天的广告展示次数、点击次数以及收益等指标。

3.1 客户端 SDK 配置​

为了将 TradPlus 广告数据与 AE 项目的用户数据进行关联，需要在客户端 SDK 进行配置，将 AE 项目的访客 ID 传到 TradPlus 后台。

方案一（自动集成）：

提示

如果您接入的 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);
// 开启TradPlus id关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TRAD_PLUS);

// 初始化 TradPlus SDK
// ...

本方案的原理就是内部自动调用 SegmentUtils 的 initCustomMap 方法，将 AE SDK 的访客 ID 传入AppKeyManager.CUSTOM_USERID

方案二（手动集成）：

手动集成方案就是可以通过 TradPlus 的 AppKeyManager.CUSTOM_USERID (Android) 或 dicCustomValue (iOS) 方法，将 AE 访客 ID 传进 TradPlus SDK 的 userId (设备层级数据报告 API 返回参数之一)里。

iOS 代码示例：

//应用维度的自定义信息
NSString *ta_distinct_id = [instance getDistinctId];
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": ta_distinct_id};

Android 原生代码示例：

String ta_distinct_id = instance.getDistinctId();
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, ta_distinct_id);
//设置APP维度的规则，对全部placement有效
SegmentUtils.initCustomMap(customMap);

Unity SDK 代码示例：

string ta_distinct_id = ThinkingAnalyticsAPI.GetDistinctId();
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", ta_distinct_id);
//设置APP维度的规则，对全部placement有效
TradPlus.initCustomMap(map);
警告

注意（非常重要）：

通过 AppKeyManager.CUSTOM_USERID (Android/Unity) 或 dicCustomValue (iOS) 的上报需要在 TradPlus SDK 初始化之前完成；否则，部分 userId 可能会无法回传。

3.2 数据拉取​

3.2.1 涵盖字段​

  • 维度字段
字段类型备注
dateTimeStampint时间戳（日期）
#zone_offsetint时区，即请求时使用的时区
appIdString应用ID （TradPlus）
placementIdString广告位ID （TradPlus）
placementNameString广告位名字（TradPlus）
adFormatInt广告位类型
adFormatNameString广告位类型名字
areaString国家地区编码(ISO 3166-1二位国家地区代码)
networkInt广告网络ID
networkNameString广告网络名字
networkPlacementIdString广告网络的广告位ID信息
networkPlacementNameString广告网络的广告源名称 （TradPlus）
networkPlacementInfoString广告网络的广告位详细信息
androidIdString设备ID，androidid
gaidStringGoogle的广告设备ID
idfaStringiOS的设备ID
userIdString用户自定义上传的 Custom User ID，此处应为 AE 项目的访客 ID
channelString渠道
sub_channelString子渠道
oaidStringAndroid设备标识符
idfvString应用开发商标识符
os_versionString终端os版本
att_statusInt苹果ATT状态 (0:用户未决定; 1:受限制的; 2:拒绝的; 3:授权的)
  • 指标字段
字段类型备注
impressionInt展示数（TradPlus）
clickInt点击数（TradPlus）
revenueFloat收益
ecpmFloat千次展示收益

3.2.2 接口参数​

  • 时间：
    • 拉取以日为时间单位的数据
      • 时区可选择 "UTC+8"、"UTC+0"、"UTC-8"
  • 币种：
    • 可选择 USD、CNY，默认为 USD
  • 拉取项目：
    • 需要指定需要拉取数据的平台项目，并提供该项目的 App ID

3.2.3 数据入库规则​

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

  • 使用数据中的 userId 作为数据中的访客 ID，该字段应可对应 AE 项目中的访客ID
  • 使用数据中的 dateTimeStamp 字段，即数据时间戳，作为事件的 #event_time
  • 数据事件名为 -- tradplus_device_report
  • 其余字段都将会入库

四、综合报表查询 API​

接口基本信息

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

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

4.1 分析维度​

以下列出的是综合报表查询 API 的所有分析维度，默认情况下，我们会使用所有分组维度，如果需要进行调整，请将需要拉取的分组项填写在数据集成配置信息模板中。

分组项字段备注
datedate日期，格式：YYYY-mm-dd
appIdappId应用ID （TradPlus）
packageName包名
placementIdplacementId广告位ID （TradPlus）
placementName广告位名字 （TradPlus）
adFormatadFormat广告位类型
adFormatName广告位类型名字
areaarea国家地区编码(ISO 3166-1二位国家地区代码)
networknetwork广告网络ID
networkName广告网络名字
networkPlacementIdnetworkPlacementId广告网络的广告位ID信息
networkPlacementName广告网络的广告源名称 （TradPlus）
networkPlacementInfo广告网络的广告位详细信息

4.2 涵盖指标​

以下是综合报表查询 API 的涵盖的指标字段，默认情况下，所有字段均会获取，如果需要进行调整，请将需要拉取的指标字段填写在数据集成配置信息模板中。

字段类型备注
dauInt日活跃用户数量(app级别)
deuInt每日观看广告的用户数
arpuFloat每用户平均收入
newUsersInt新增用户(app级别)
newUserRateFloat新增用户占比(app级别)
requestApiInt三方广告平台的请求数
fillrateApiFloat三方广告平台的填充率
impressionApiInt三方广告平台的展示数
clickApiInt三方广告平台的点击数
ctrApiFloat三方广告平台的点击率
ecpmApiFloat三方广告平台的eCPM
revenueFloat收益

4.3 接口参数​

  • 时间：
    • 拉取以日为时间单位的数据
      • 时区可选择 "UTC+8"、"UTC+0"、"UTC-8"
  • 币种：
    • 可选择 USD、CNY，默认为 USD
  • 拉取项目：
    • 可以指定需要拉取数据的平台项目，并提供该项目的 App ID

4.4 数据入库规则​

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

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

五、数据集成配置信息模板​

在阅读完以上文档之后，请将您要拉取的API、字段、拉取方式等信息填写在以下信息框里并发送给您在 ThinkingAI 的客户成功经理。

接口：TradPlus 设备层级数据报告 API / 综合报表查询 API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
TradPlus Access Token: XXX
---------
数据拉取类型：设备层级数据报告 API / 综合报表查询 API （如果两个都用，请分开编写）

<-----以下是 设备层级数据报告 API----->
TradPlus 后台的应用 ID: XXX, XXX
拉取数据时区：XXX (时区，枚举值：UTC-8、UTC+8、UTC+0，不传则默认 "UTC+0")
<--------------------------------->

<-----以下是 综合报表查询 API 的信息----->
TradPlus 后台的应用 ID: XXX, XXX
拉取数据时区：XXX (时区，枚举值：UTC-8、UTC+8、UTC+0，不传则默认 "UTC+0")
分析维度：XXX, XXX（默认为全字段）
拉取指标：XXX, XXX（默认为 all，即全字段）
<------------------------------------>

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前一天的数据

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

6.1 数据校验​

可以在 AE 系统后台的「数据管理」—「事件管理」页面 或「SQL IDE」页面搜索以下事件是否入库：

  • 设备层级数据报告 API：tradplus_device_report
  • 综合报表查询 API：tradplus_allreport
这篇文档对你有帮助吗？
本页内容