TopOn 设备层级数据报告

TIP

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

概要

接口简介

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

设备层级数据报告 (opens new window)可以获取以用户维度的数据，包括了用户在一段时间内的总展示、点击以及收益数据。因此 TE 系统会单独拉取每个用户每天的数据，也就是一个用户在每天的广告展示数、点击数以及收益情况。

在开始接入 TopOn 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户

集成流程

1. 接入 TopOn 客户端 SDK (opens new window) 与 TE SDK，在 TopOn SDK 设置 TE 的用户识别 ID
2. 登录 TopOn 后台，获取 Publisher Key 和 APP ID
3. 登录 TE 后台，进入三方集成模块，新增 TopOn 集成，创建集成方案
4. 查看 TE 系统否成功接收数据，并完成报表搭建

一、客户端 SDK 配置

集成 TopOn 数据的第一步，是在客户端完成 TE SDK 与 TopOn SDK 的打通，在 TopOn 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 初始化和开启自动集成代码必须在 TopOn 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化TE SDK。

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

3. 初始化 TopOn SDK。

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

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

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

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

TIP

修改访客ID之后，需要再次调用 enableThirdPartySharing() 同步数据。

该方案的原理就是内部自动调用 ATSDK 的 initCustomMap 方法，传入 ATCustomRuleKeys.USER_ID，传入值为 TA 项目的访客 ID。

1.2 方案二（手动集成）

通过 TopOn 的 App 全局自定义规则设置，将 TA 的 distinct_id 传进 TopOn SDK 的 custom_rule 里面的 user_id ，调用方法和代码实例可以参考该文档 (opens new window)。

WARNING

请注意 TE 的 SDK 初始化和调用 initCustomMap 接口必须在 TopOn 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化 TE SDK。

2. 调用initCustomMap 设置访客 ID。

3. 初始化 TopOn 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设置到 TopOn 采集事件中
Map<String, String> customMap = new HashMap<>(); 
customMap.put(ATCustomRuleKeys.USER_ID,distinctId); 
ATSDK.initCustomMap(customMap);
// 4、初始化 TopOn 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设置到 TopOn 采集事件中
[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:distinctId}];
// 4、初始化 TopOn 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设置到 TopOn 采集事件中
ATSDKAPI.initCustomMap(new Dictionary<string, string> { { "user_id", distinctId } }); 
// 4、初始化 TopOn SDK
//  。。。

二、TopOn 后台信息获取

完成 SDK 的配置后，您需要登录 TopOn 后台获取拉取数据所需的授权信息。

为了获取授权信息，您需要先向 TopOn 对接人申请开通设备层级数据报告 API 权限。开通成功后，可在开发者后台的账号管理页面获取 Publisher Key。

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

三、方案配置

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

3.1 授权信息配置

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

其中：

• APP ID：刚刚获得的应用 ID
• Publisher Key：即刚刚获得的 Publisher Key

3.2 定时拉取

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

3.3 拉取时区

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

3.4 用户识别字段

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

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

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

3.5 事件表入库设置

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

3.6 用户属性入库规则

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

3.7 集成配置

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

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

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

3.8 事件入库规则

• TE 系统将每天的 0 点，作为事件的 #event_time
• 默认使用的事件名为 -- ta_ad_revenue_topon
• 其他字段将全数入库，以下是所有会入库的事件属性

字段	备注
placement_id	广告位ID
placement_name	广告位名称
placement_format	广告类型： 0：native；1：rewarded_video；2：banner；3：interstitial； 4：splash
android_id	设备ID，androidid
gaid	Google 的广告设备 ID
idfa	iOS 的设备 ID
area	国家
impression	展示数
click	点击数
revenue	收益，根据三方广告平台的收益对设备层级进行拆分，货币单位同开发者后台配置一致
ecpm	TopOn 基于收益 API 按设备展示拆分后的收益和 TopOn 统计的设备展示计算出 eCPM，计算公式：（设备收益/TopOn统计的设备展示）* 1000。注：eCPM 延迟 2 天提供
is_abtest	对照组或测试组： 0：表示对照组或未开通A/B测试；1：表示测试组
traffic_group_id	对照组或测试组id
segment_id	流量分组ID
segment_name	流量分组名称
idfv	iOS的设备ID
oaid	安卓的设备ID
user_id	开发者的自定义用户ID
network_firm_id	广告平台ID
network_firm	广告平台名称
currency	开发者账号币种，USD表示美元，CNY表示人民币
os_version	iOS设备的操作系统版本
att_status	iOS设备的ATT授权状态： 0：Not determined(未决定是否授权) ；1：Restricted (受限制)；2：Denied(已拒绝)；3：Authorize(已授权)
imei	安卓的设备识别码
device_type	IOS设备类型，枚举值说明： 0：非IOS设备；1：iphone；2：ipad
brand	设备品牌名
model	设备型号
app_vn	应用版本名
app_vc	应用版本号
new_user_type	新用户类型，枚举值说明： 1: 是新用户；2: 不是新用户
channel	渠道，由开发者通过TopOn SDK传入的渠道
estimate_revenue	预购收益，竞价广告源以实时的广告展示价格汇总得出预估收益，非竞价广告源以人工填写的eCPM价格 * TopOn统计的展示汇总得出预估收益

3.9 标准化字段

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

原字段	标准化字段	含义
network_firm	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	变现收益