数据对接指引
更新日志
| 日期 | 更新内容 |
|---|---|
| 2024.10 | |
| 2024.03 | |
| 2023.11 | |
| 2023.09 |
一、目录
本文主要介绍 TapAD 的广告场景的转化事件回传，分为广告浅层监测事件下发和广告深度事件回传两部分
二、广告监测事件下发
1、监测范围
- 本标准只适用于通过 TapTap 推广平台投放的游戏产品的广告相关监测
- 适用于安卓、iOS
- 小游戏参考
2、接口简介
2.1 作用
TapTap 客户或代理对其在 TapTap 推广游戏进行监测时，可以通过提供监测链接的形式，来对广告进行点击、转化等事件监测。通过约定指定格式的字符串，用以代表将要替换的字段位置，这个格式我们统称为“宏”。
当 TapTap ⽤户发⽣广告交互行为（如“点击下载按钮”）时，系统会通知填写到后台的监测地址，⼴告主可以获取回调请求中的设备信息进⾏归因匹配。
2.2 宏字段介绍
监测链接主要由"https://XXX.XXX.com?"+"参数"+其他部分组成，监测配置在游戏维度上，只需要配置一条监测链接即可监测到所有计划/创意数据，具体格式如下：
- 监测地址需要是合法的 http 或 https 链接，⻓度不能超过 1000 个字符。
- 回调地址应当返回 2xx 或 3xx 的 http code。当回调地址调⽤失败时，Tap 下发服务会进行 3 次尝试，3 次尝试失败会丢弃该回调。
- 回调地址⽀持下列宏替换：
| 宏 | 说明 |
|---|---|
| {IDFA} | iOS 设备的 IDFA，使⽤原始的⼤写的值，不存在时传递空字符 |
| {IDFA_MD5} | IDFA md5 值 |
| {CAID} | iOS 设备中国广告协会互联网广告标识，包含最新两个版本的 CAID 和版本号。 URL Encode 后的 JSON 数组UrlEncode("[{\"caid\":\"81bcddc91ea559bb711cfaf0b55cae52\",\"version\":\"20211207\"},{\"caid\":\"0f1e07a50956d6af4a63c79106fa3e68\",\"version\":\"20220111\"}]") |
| {ANID} | Android 设备的 Android ID, 使用原始的数据值，不存在时传递空字符串，Android8 以后基本不可用 |
| {IMEI} | Android 设备的 IMEI, 使用原始的数据值，不存在时传递空字符串 |
| {OAID} | Android 设备的 OAID, 使用原始的数据值，不存在时传递空字符串 |
| {OAID_MD5} | OAID md5 值 |
| {TIME} | 时间戳，1970 年到当前时间的秒数 |
| {IP} | 用户的 IP 地址 |
| {IPV6} | 用户的 IPV6 地址 |
| {ORG_ID} | 账户 ID |
| {ORG_NAME} | 账户名称 |
| {GAME_NAME} | 游戏名称 |
| {ADSET_ID} | 广告计划 ID，补量默认为“999999” |
| {ADSET_NAME} | 广告计划名称，补量默认为“SupplementCampaign” |
| {CREATIVE_ID} | 创意 ID，补量默认值为“9999” |
| {CONVERSION_TYPE} | 下载类型，分广告下载“TapTapAd”和间接下载“TapTapNature”（目前仅下发广告下载） |
| {DEVICE} | 设备类型，iOS 下发“1”，android 下发“0” |
| {DEVICE_BRAND} | 设备品牌 |
| {DEVICE_MODEL} | 设备型号 |
| {OS_VERSION} | 系统版本号 |
| {WEB_UA} | 浏览器 UA |
| {TAP_TRACK_ID} | 广告归因 ID:用于深度回传服务 |
| {DEEP_CALLBACK_URL} | 深度回传链接(激活、注册、付费、次留等)，按照要求拼接上相关参数回传深度事件，{CALLBACK_HTTPS} / {CALLBACK_HTTP} 不推荐使用，新建监测链接已废弃，存量不受影响 |
2.3 注意事项
- 深度数据回传：当广告主通过链接成功匹配到安装激活及后续深度事件时，应该将深度数据回传给 TapTap 广告系统。 在监测链接中，可以设置 {DEEP_CALLBACK_URL}宏，它们会被替换为深度回传地址，默认 HTTPS 协议，按照要求拼上对应的参数回传深度事件
- 宏参数必须全大写，否则无法回传对应参数值
- 监测链接不能是下载链接
- 展示、点击监测链接不支持串接代码
- 监测链接必须支持连通
- 监测链接不能包含非法字符
- 非法字符包括但不限于如下列表：
| 序号 | 非法字符 | 字符解释 |
|---|---|---|
| 1 | % | url path 中出现的单个的 %，后面不跟 2 位 16 进制数；转义字符中的 % 没有问题 |
| 2 | 空格 | url 中出现的空格 |
| 3 | // | url path 中出现的连续 // |
2.4 链接示例
- 配置链接：
https://xx.xxx.com/track?idfa={IDFA}&time={TIME}&ip={IP}&org_id={ORG_ID}&org_name={ORG_NAME}&game_id={TAP_PROJECT_ID}&game_name={GAME_NAME}&adset_id={ADSET_ID}&adset_net={ADSET_NAME}&device_brand={DEVICE_BRAND}&device_model={DEVICE_MODEL}&creative_id={CREATIVE_ID}&conversion_type={CONVERSION_TYPE}&device={DEVICE}&OAID={OAID}&callback={DEEP_CALLBACK_URL}&tap_track_id={TAP_TRACK_ID}&tap_project_id={TAP_PROJECT_ID} - 平台回传给广告主归因服务对应的示例：
https://xx.xxx.com/track?idfa=asedfstUfe&time=1605432321&ip=10.33.25.54&org_id=20&org_name=广告主名称&game_id=13&game_name=游戏名称&adset_id=132214&adset_net=计划名称&device_brand=苹果&device_model=iPhone3,2&creative_id=131232&conversion_type=TapTapAd&device=1&OAID=&callback=https%3A%2F%2Fdcc.iem.taptap.cn%2Fv1%2Fdeep%2Fcallback%3Ftap_track_id%3DxYTKx4rSFFWx%26tap_project_id%3D1111&tap_track_id=xYTKx4rSFFWx&tap_project_id=13- tap_track_id、tap_project_id 两个字段在下载回传服务中默认下发，在深度事件回传中回传该字段，也可以通过{TAP_TRACK_ID}和{TAP_PROJECT_ID}宏进行获取
3、使用指南
- 广告主在广告平台针对游戏/计划/创意维度进行相应的监控链接填写
- 平台在广告产生相应的监控事件后，将对应的事件通过广告主填写的链接进行相应的宏替换，将事件实时传给广告主并且附带上对应的深度回传链接
- 广告主获取到对应的事件后存储下来
- 广告主的 app 在安装完成后，产生对应的激活等深度事件，通过设备 id 精准匹配或者 ipua 模糊归因的手段，将产生的激活事件归因到广告平台下发的前置事件上，并且调用前置事件中的深度事件回传链接将事件回传给平台
- 平台在报表上进行相应的数据展示
注意：appsflyer、热云等第三方需要先单独进行对接
三、广告深度转化事件回传
1、数据回传范围
- 本标准只适用于通过 TapTap 推广平台投放的游戏产品的广告深度事件回传
- 适用于安卓、iOS
- 小游戏参考
2、申请条件
优质客户白名单测试
- 测试条件：广告主具备配置服务端上传字段技术支持
3、请求参数及示例
| 数据收集 | 说明 | 支持事件 | 备注 |
|---|---|---|---|
| 广告量 | 广告事件必传 tap_project_id 和 tap_track_id， 其中 tap_track_id 用于串联对应的广告主&游戏&计划&创意 | 1.激活 2.注册 3.付费 4.次留 | tap_project_id、tap_track_id 以上两个字段在下载回传服务中默认下发，也可通过宏字段获取 |
3.1 请求方式
转化事件发生后，广告主/第三方在请求接口后附上回传字段({DEEP_CALLBACK_URL}&event_type=xxx&event_timestamp={timestamp}&???=xxx)，并发起 GET 请求，上报给 TapAD。
注意：tap_project_id、tap_track_id 默认填充在{DEEP_CALLBACK_URL}中，不需要再次拼接这两个参数， 由于历史问题，使用旧回传宏 {CALLBACK_HTTPS} / {CALLBACK_HTTP} 的客户建议尽快更换为新宏{DEEP_CALLBACK_URL}， 旧宏在下发时默认会添加event_timestamp和event_type， 请不要在后面再次拼接event_timestamp和event_type，造成重复参数，务必用真实事件时间和类型替换掉下发时这两个参数值， 否则会导致事件缺失或时间错误造成报表数据看不到，尤其是回传付费事件时。
3.2 字段说明
| 字段 | 是否必传 | 类型 | 值 | 描述 |
|---|---|---|---|---|
| tap_track_id | 必填 | string | xx | 广告 ID，前序事件中会下发 {DEEP_CALLBACK_URL}中也会拼上该字段 |
| tap_project_id | 必填 | int | 10231 | 游戏 ID，前序事件中会下发 |
| event_type | 必填 | int | 枚举值{1,2,3,4,5,6}：1：激活 首次打开 APP 2：注册 在 APP 内注册账户/创角 3：付费(多次)4：次留 5：全渠道首次吊起（当日 app 首次被促活广告拉起） 6：关键事件 （用户在 app 进行了一些黑盒关键行为， 如加购等） | 转化事件类型为了有效优化广告深度转化效果，回传事件定义务必与文档一致 |
| event_timestamp | 必填 | int | 1321423400 | 时间戳(单位:秒)事件发生时间 若为回传时间会导致归因失败 |
| amount | event_type = 3 付费事件时必填，其他不填 | int | 10000 | 付费金额(单位:分) |
| md5_android_id | 选填 | string | ce5b074b70316009fd1c33c4a3eb3ea4 | ANDROID md5 后的 android_id 值(32 位小写) |
| md5_oaid | 选填 | string | cw5b074b70316009fd1c33c4a3eb3ea4 | ANDROID md5 后的 oaid 值(32 位小写) |
| ipv4 | 选填 | string | 10.25.49.101 | ipv4 值 |
| ipv6 | 选填 | string | 2345:0425:2CA1:0000:0000:0567:5673:23b5 | ipv6 值 |
| ua | 选填 | string | Mozilla/5.0 (Linux; U; Android 2.3.7; en-us; Nexus One Build/FRF91) | ua 标准值 |
| device_model | 选填 | string | vivo X7 | 设备型号 Android:Build.MODEL |
| device_brand | 选填 | string | vivo | 设备名称 Android:Build.MANUFACTURER |
| os_version | 选填 | string | 5.1.1 | 系统版本 Android:Build.VERSION.RELEASE |
| replenish | 选填 数据修复 必填 | int | 0 | 仅用于数据修复，补数据时使用 0：非补数据（默认 0）1：补历史数据 |
4、数据修复
4.1 场景
当已回传数据出现缺失，遗漏，错误等问题时，修复过去已经传回的错误数据。
4.2 修复方式
4.2.1 离线回传
通过线下方式，提供数据文档给到 TapAD，完成数据修复。Tap 会清除已回传的历史数据，一切以新传数据为准。 需满足以下数据要求：
- 数据规模：全量回传，以修复时间为节点，回传修复前的所有数据。
- 回传字段：深度事件所有字段，无数据字段可回传空值。
- 文件格式：不限
4.2.2 API 回传
通过深度接口{DEEP_CALLBACK_URL}宏中的 host 加上对应的参数回传数据，完成数据修复。 API 方式修复数据，需要回传必传字段 replenish，用于区分是否为后补数据。
| 字段 | 是否必传 | 类型 | 值 | 描述 |
|---|---|---|---|---|
| replenish | 必填 | int | 0 | 仅用于数据修复，补数据时使用 0：非补数据（默认 0） 1：补历史数据 |
四、小游戏数据接入流程
1、整体流程
小游戏接入条件：
- 只支持微信小游戏上架TapTap iOS客户端进行广告投放
- 暂时只邀请部分优质微信小游戏进行内测
Tap支持通过API上报数据的方式进行转化数据对接。
主要流程如下：
- Tap在投放的小游戏启动链接上拼接广告参数
- 客户从小游戏的唤起路径中获取广告参数（主要是source、tap_track_id、tap_project_id）
- 发生转化事件时，客户通过回传接口进行上报
2、获取广告参数
Tap广告会在跳转小游戏时携带如下参数:
| 参数 | 描述 | 类型 | 示例 |
|---|---|---|---|
| source | 渠道名称 | string | taptap |
| tap_track_id | 用于追踪广告效果的参数 | string | QhjqIfB1tKO7acjcdJBuGA3LYkj |
| tap_project_id | 在 tap 的游戏 id | int | 10001 |
| tap_adset_id | 广告组 id | int | 1000394 |
| tap_creative_id | 创意 id | int | 234232323 |
启动路径示例: pages/index/index?source=taptap&tap_track_id=QhjqIfB1tKO7acjcdJBuGA3LYkj&tap_project_id=10001&tap_creative_id=234232323&tap_adset_id=1000394
通过启动链接唤起小游戏后，客户在小游戏内部通过wx.getLaunchOptionsSync或wx.getEnterOptionsSync获取参数。
3、转化事件回传
客户获取到回传参数并发生响应转化事件时，客户拼接事件参数并通过固定接口进行回传，httpcode=200 表示回传成功。
请求协议：HTTPS
请求方式：GET
请求接口：https://dcc.iem.taptap.cn/v1/deep/callback
回传请求示例：
https://dcc.iem.taptap.cn/v1/deep/callback?tap_track_id=QhjqIfB1tKO7acjcdJBuGA3LYkj&tap_project_id=10001&event_type=1&event_timestamp=1694510529&project_type=3
请求参数说明
| 字段 | 是否必传 | 类型 | 值 | 描述 |
|---|---|---|---|---|
| tap_track_id | 必传 | string | 例:QhjqIfB1tKO7acjcdJBuGA3LYkj | 用于追踪广告效果的参数，启动链接上会携带该参数 |
| tap_project_id | 必传 | int | 例:10001 | 用于追踪广告效果的参数，启动链接上会携带该参数 |
| event_type | 必传 | int | 见转化事件类型参数（event_type）枚举值 | 转化事件类型为了有效优化效果，回传事件定义务必与文档一致 |
| event_timestamp | 必传 | int | 例:1321423400 | 时间戳(单位:秒),事件发生时间 |
| amount | event_type = 3 付费事件时必填,其他不填 | int | 例:10000 | 付费金额(单位:分) |
| project_type | 必传 | int | 3 | 表示投放的资产为小游戏/小程序 |
转化事件类型参数（event_type）枚举值
| 事件类型 | 枚举值 | 描述 |
|---|---|---|
| 激活 | 1 | 首次打开应用 |
| 注册 | 2 | 在应用内注册账户/创角 |
| 付费 | 3 | 可多次回传 |
| 次留 | 4 | |
| 小游戏打开 | 10 | 上架TapTap iOS客户端微信小游戏打开行为 |
五、模拟联调
1. 作用
监测链接设置好后，可通过模拟联调，来测试广告数据下发、激活数据回传是否顺利无误。以避免由于数据回传失败，导致真实投放广告时，回收不到广告激活的困扰。
2. 具体流程
开始以下操作之前，请先正确填写监测链接。
注意：
- 广告主接受TapAd下发数据的服务，返回值 code 为 200
2.1 新建模拟联调
联调之前，需要先填写联调游戏信息，设备信息。
注意，目前转化目标仅支持激活，可选设备分 iOS / Android，其中
- iOS
- IDFA / CAID 至少填写一个，IPv4 必填，IPv6 / UA 选填
- Android
- OAID 必填
2.2 开始联调
点击开始联调
跳出开始联调弹窗，点击开始联调按钮，下发模拟下载事件
使用刚填写信息的设备，前往 TapTap 下载联调的游戏，完成激活转化目标，然后在界面点击【已完成】
完成激活后，使用设备号匹配之前的下发记录，若匹配的上，取出下发记录中的模拟回传链接callback（url解码后直接请求，无需拼接任何参数）， 完成归因后的激活回传，等待联调结果。注意，这里是模拟回传链接，和线上回传链接有区分，线上需要拼接参数，详见广告深度转化事件回传。
等待联调结果，直到联调成功
六、其他
1、数据展示
- 广告激活数据会直接展示在广告投放后台
2、数据反馈提报流程
问题反馈请按如下模板发一下（相关问题也可以对接 TapAd 的运营同学），提高排查效率：
| 内容 |
|---|
| 登录 TapTap 用户 ID: |
| 广告主(账号)ID: |
| 游戏 ID: |
| 计划 ID |
| 创意 ID |
| 问题描述： |
| 截图（截图辛苦全屏，包含 URL） |
七、Q&A
Q：TapAD 激活、深度转化事件的归因窗口期是多久？
A：广告激活归因窗口期为 7 天。 深度事件回传的数据不限制窗口期。
Q：广告激活回传/深度转化回传 配置成功后，可以收到历史转化数据回传吗？
A：不可以，激活/深度转化事件的数据，仅可接收到配置成功后的数据。
Q: 深度事件回传的链接怎么拼接？
A：通过浅层监测事件中配置{DEEP_CALLBACK_URL}宏拼接上相关的回传参数，发起 GET 请求上报给 TapAD
Q: 用户的一次转化事件多次回传给 Taptap，Taptap 会去重吗？
A：会去重的，但建议一次转化事件只回传一次（比如同一次付费、一次激活只回传一次）
Q: 如何获得IPv4？
A: 通过设置-无限局域网查看
Q: 如何获得IDFA?
A: 下载软件DeviceId查询，必须先允许跟踪，设置 -> 隐私与安全性 -> 跟踪 -> 允许App请求跟踪
Q: 如何获得CAID？
A: CAID 由中国广告协会提出，旨在提供统一的设备标识符，特别是在苹果和 Google 限制传统广告标识符获取后，保护用户隐私。
CAID 在同一设备上的不同应用中是相同的。用户升级系统，CAID 也随之变化。
收费，可通过api或sdk接入，互联网广告技术实验室开发者平台
Q: 如果获得OAID?
A: OAID 由中国信息通信研究院发起，旨在提供匿名的设备标识符，用于广告和用户行为分析。OAID 不包含任何个人信息。
用户可以在设备设置中重置 OAID，类似于苹果的 IDFA。在同一设备上，所有应用获取的 OAID 是相同的。 免费，
获取方式：移动安全工作委员会