# TopOn 设备层级数据报告
TIP
请注意,第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
---|---|---|---|---|---|---|---|---|
设备层级数据报告 | API | 用户级别 | ✅ | ✅ | ✅ |
设备层级数据报告 (opens new window)可以获取以用户维度的数据,包括了用户在一段时间内的总展示、点击以及收益数据。因此 TE 系统会单独拉取每个用户每天的数据,也就是一个用户在每天的广告展示数、点击数以及收益情况。
在开始接入 TopOn 数据前,请确保您已经阅读 TE 系统用户识别规则,理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 接入 TopOn 客户端 SDK (opens new window) 与 TE SDK,在 TopOn SDK 设置 TE 的用户识别 ID
- 登录 TopOn 后台,获取 Publisher Key 和 APP ID
- 登录 TE 后台,进入三方集成模块,新增 TopOn 集成,创建集成方案
- 查看 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 初始化之前完成,请按照以下步骤操作:
初始化TE SDK。
调用
enableThirdPartySharing
自动设置访客 ID。初始化 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 初始化之前完成,请按照以下步骤操作:
初始化 TE SDK。
调用
initCustomMap
设置访客 ID。初始化 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 | 变现收益 |