数据对接指引
更新日志
| 日期 | 更新内容 |
|---|---|
| 2024.03 | |
| 2023.11 | |
| 2023.09 |
一、目录
本文主要介绍 TapAD 的广告场景的转化事件回传，分为广告浅层监测事件下发和广告深度事件回传两部分
二、广告监测事件下发
1、监测范围
- 本标准只适用于通过 TapTap 推广平台投放的游戏产品的广告相关监测
- 监测下发功能处于内部测试阶段，广告主生成监测链接后，需联系 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, 使用原始的数据值，不存在时传递空字符串 |
| {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} | 深度回传链接(激活、注册、付费、次留等)，按照要求拼接上相关参数回传深度事件 |
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}&tap_project_id=13&tap_track_id=xxxevent_type=xxx&event_timestamp={timestamp}&???=xxx)，并发起 GET 请求，上报给 TapAD。
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客户端微信小游戏打开行为 |
五、模拟联调
注意：
- 广告主接受TapAd下发数据的服务，返回值 code 为 200
六、其他
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：会去重的，但建议一次转化事件只回传一次（比如同一次付费、一次激活只回传一次）