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