TradPlus 设备层级数据报告 API

TIP

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

概要

接口简介

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

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

集成流程

1. 接入 TradPlus 客户端 SDK 与 TE SDK，在 TradPlus SDK 设置 TE 的用户识别 ID
2. 登录 TradPlus 后台，获取 Access Token和应用ID
3. 登录 TE 后台，进入三方集成模块，新增 TradPlus 设备层级数据报告 API 集成方案
4. 查看 TE 系统否成功接收数据，并完成报表搭建

一、客户端 SDK 配置

集成 TradPlus 数据的第一步，是在客户端完成 TE SDK 与 TradPlus SDK 的打通，在 TradPlus SDK 中设置 TE 系统的用户识别 ID

1.1 方案一（自动集成）

• 如果您接入的 Android、iOS SDK
  • SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
  • SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考安卓 SDK 对接文档 与 iOS SDK 对接文档
• 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案

WARNING

请注意 TE 的 SDK 初始化和开启自动集成代码必须在 TradPlus 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化TE SDK。

2. 调用enableThirdPartySharing 自动设置访客 ID。

3. 初始化 TradPlus SDK。

以下各端 SDK 的代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、调用 enableThirdPartySharing 接口设置 ta_distinct_id 到 TradPlus 事件中
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.TRAD_PLUS);
// 3、初始化 TradPlus SDK
//  。。。

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、调用 enableThirdPartySharing 接口 设置 ta_distinct_id 到 TradPlus 事件中
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeTradPlus];
// 3、初始化 TradPlus SDK
//  。。。

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、调用 enableThirdPartySharing 设置 ta_distinct_id 到 TradPlus 事件中
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.TRADPLUS);
// 3、初始化 TradPlus SDK
//  。。。

// 1、初始化 Unreal SDK
UTDAnalytics::Initialize();
// 2、调用 enableThirdPartySharing 设置 ta_distinct_id 到 TradPlus 事件中
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeTRADPLUS"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
// 3、初始化 TradPlus SDK
//  。。。

本方案的原理就是内部自动调用TradPlus内部方法，将 TE SDK 的访客 ID 传进 TradPlus SDK 的 userId (设备层级数据报告 API 返回参数之一)里 。

1.2 方案二（手动集成）

手动集成方案就是可以通过 TradPlus 的 AppKeyManager.CUSTOM_USERID (Android) 或 dicCustomValue (iOS) 方法，将 TE 访客 iD 传进 TradPlus SDK 的 userId (设备层级数据报告 API 返回参数之一)里 ，调用方法和代码实例可以参考该文档。

WARNING

请注意（非常重要） TE 的 SDK 初始化和调用 dicCustomValue /initCustomMap 接口必须在 TradPlus 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化 TE SDK。

2. 调用dicCustomValue / initCustomMap 接口设置访客 ID。

3. 初始化 TradPlus SDK。

以下各端 SDK 手动集成代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String distinctId = TDAnalytics.getDistinctId();
// 3、将访客ID设置到 TradPlus 采集事件中
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, ta_distinct_id);
//设置APP维度的规则，对全部placement有效
SegmentUtils.initCustomMap(customMap);
// 4、初始化 TradPlus SDK
//  。。。

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
NSString *distinctId = [TDAnalytics getDistinctId];
// 3、将访客ID设置到 TradPlus 采集事件中
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": distinctId};
// 4、初始化 TradPlus SDK
//  。。。

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
var distinctId = TDAnalytics.GetDistinctId();

// 3、将访客ID设置到 TradPlus 采集事件中
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", distinctId);
//设置APP维度的规则，对全部placement有效
TradPlus.initCustomMap(map);
// 4、初始化 TradPlus SDK
//  。。。

二、TradPlus 后台信息获取

完成 SDK 的配置后，您需要登录 TradPlus 后台，获取 Access Token和应用ID

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

三、方案配置

当您完成了 SDK 配置并获得 Access Token和应用ID 后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 TradPlus 设备层级数据报告 API 的配置界面，请您按照本章节内容完成方案的创建：

3.1 授权信息配置

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

3.2 定时拉取

您可以在「定时拉取」模块设置 TE 系统定时拉取 TradPlus 设备层级数据报告 API 的策略，可以选择在每天的某时或者每小时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据

3.3 拉取时区

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

3.4 用户识别字段

由于 TradPlus 设备层级数据报告 API 是用户级别数据，因此需要为其设置用户识别规则，即 TradPlus SDK 中设置的 TE 系统的用户识别 ID。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。

如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：

• 账号 ID 关联字段：无
• 访客 ID 关联字段：user_id
  

3.5 事件表入库设置

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

3.6 用户属性入库规则

在默认情况下，TE 系统不会将 TradPlus 设备层级数据报告 API 的数据写入到用户属性中。如果您希望将一些字段写入用户表，请首先打开规则，使其运行，再通过属性映射功能添加需要写入用户表的字段，来源属性名需填写字段的入库名：

3.7 集成配置

您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等

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

模块	名称	含义
sink_event	event_name	入库后的事件名，可以自定义
transfer	double_columns	指标字段，请不要修改

3.8 事件入库规则

• 使用数据中的 dateTimeStamp 字段，即数据时间戳，作为事件的 #event_time
• 数据事件名为 -- tradplus_device_report
• 其他字段将全数入库，以下是所有会入库的事件属性

字段	类型	备注
#zone_offset	int	时区，即请求时使用的时区
currency	String	币种
appid	String	应用ID （TradPlus）
placement_id	String	广告位ID （TradPlus）
placement_name	String	广告位名字（TradPlus）
ad_format	Int	广告位类型
ad_format_name	String	广告位类型名字
area	String	国家地区编码(ISO 3166-1二位国家地区代码)
network	Int	广告网络ID
network_name	String	广告网络名字
network_placement_id	String	广告网络的广告位ID信息
network_placement_name	String	广告网络的广告源名称 （TradPlus）
network_placement_info	String	广告网络的广告位详细信息
android_id	String	设备ID，androidid
gaid	String	Google的广告设备ID
idfa	String	iOS的设备ID
user_id	String	用户自定义上传的 Custom User ID，此处应为 TE 项目的访客 ID
channel	String	渠道
sub_channel	String	子渠道
oaid	String	Android设备标识符
idfv	String	应用开发商标识符
os_version	String	终端os版本
att_status	Int	苹果ATT状态 (0:用户未决定; 1:受限制的; 2:拒绝的; 3:授权的)
impression	Int	展示数（TradPlus）
click	Int	点击数（TradPlus）
revenue	Float	收益
ecpm	Float	千次展示收益

3.9 标准化字段

TradPlus 设备层级数据报告中的部分字段，TE 系统会进行标准化处理

原字段	标准化字段	含义
network_name	te_ads_object.media_source	变现渠道
placement_name	te_ads_object.placement	广告位置
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	变现收益