menu
Is this helpful?

# 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
  • 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案

WARNING

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

  1. 初始化TE SDK。

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

  3. 初始化 TopOn SDK。

TIP

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

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

# 1.2 方案二（手动集成）

通过 TopOn 的 App 全局自定义规则设置，将 TE 的 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 手动集成代码样例：

# 二、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 变现收益

← TopOn 综合报表查询 API →