TapTap 广告归因接入指引

本文面向通过 TapTap 广告平台（TapAD）投放的游戏产品开发者，介绍广告转化归因的两种接入方式：SDK 自归因（推荐） 与 数据回传归因（传统方式）。

一、归因方式总览

TapAD 为投放 TapTap 广告的游戏产品提供转化归因能力，当前支持两种方式：

方式	说明	适用场景
SDK 自归因（推荐）	集成 TapSDK，客户端上报事件数据，平台侧自动完成广告转化识别与归因	新接入优先推荐；Android 设备 OAID 获取受限时保证归因完整性
数据回传归因（传统）	配置监测链接接收点击/展示回调，自建服务完成归因匹配后，调用深度回传接口上报事件	已自建归因服务的客户；或无法集成 SDK 的场景

两种方式可并行接入，互不影响。

二、SDK 自归因（推荐）

2.1 背景与原理

部分 Android 手机受系统策略限制，可能无法稳定获取 OAID，导致广告带来的激活、登录和付费转化无法被完整归因。为减少对单一 OAID 的依赖，TapAD 采用 SDK 自归因方案：通过 TapSDK 上报事件数据，由平台识别广告转化并完成归因。

2.2 接入目标

开发者需要完成以下三类核心数据接入：

事件	业务时机	需要完成的接入动作
初始化 SDK	应用启动，用户同意隐私协议后	初始化 TapSDK 及数据分析模块
用户注册登录	用户登录账号成功后	设置游戏自定义用户 ID（setUser），方便后续查询数据
用户付费	用户支付成功	通过客户端 SDK 上报付费事件

2.3 接入前准备

2.3.1 开发者中心配置

通过 TapTap 开发者中心创建游戏应用；
进入「游戏服务」→「应用配置」，点击「立即开启」：

进入游戏服务并开启应用配置

开启后，在「基本信息」中获取 Client ID 和 Client Token，并在「签名证书配置」中核对 Android 包名与签名：

核对 Client ID、Client Token、Android 包名和签名

完整操作说明：开发者中心配置

2.3.2 开发环境要求

请确认游戏工程满足以下最低环境要求：

依赖	最低版本
Android	5.0（API level 21）及以上
Kotlin	1.7.21 及以上
Gradle	6.1.1 及以上
Android Gradle Plugin	4.0.1 及以上

如工程版本低于上述要求，请先完成升级。其他兼容性说明请查看 Android 原生集成。

2.3.3 隐私与合规

接入 TapSDK 时，请重点确认：

在用户同意游戏《隐私政策》后，再初始化 TapSDK 并开始数据收集；
在游戏《隐私政策》中披露接入 TapSDK 的情况，包括 SDK 名称、提供方、收集的信息类型、使用目的及隐私政策链接；
在申请具体系统权限前，向用户说明权限用途，并同时提供同意和拒绝选项；仅在用户同意后申请对应权限。

完整要求及披露示例请查看 TapSDK 合规使用说明。

2.4 SDK 接入步骤

接入环节	接入文档	业务注意事项
添加依赖与权限	Android SDK 获取、数据分析权限说明	事件上报最小化 SDK 依赖 `com.taptap.sdk:tap-core:4.10.7`（版本号取最新版），其他依赖按需获取；数据分析模块需要网络相关权限；可选权限由开发者根据实际需要决定是否申请，SDK 不会主动申请
初始化 TapSDK	Android 基础初始化、数据分析初始化额外配置	用户同意隐私协议后完成初始化
设置账号 ID	设置账号 ID	账号登录时调用；不同账号的 userId 必须唯一，字符串长度不超过 160
上报付费	客户端上报充值记录	用户支付成功后通过客户端接口上报；已接入 TapPayments 时无需手动上报，避免重复统计

2.5 联调与上线验收

打开 TapDB 后台，在顶部导航打开「接入指引」；
选择对应项目及 Android 平台；
按照页面提示查看「初始化 SDK」、调用「设置账号」接口、上报「付费」事件的接入状态：

TapDB 后台接入指引（Android 平台）

状态均为「已完成」即代表联调成功。

若上报后状态仍为「未完成」，可通过 TapDB 后台「运营 → 配置 → 埋点概览」查看错误详情进行排查：

TapDB 后台埋点概览

三、数据回传归因（传统方式）

3.1 方案概述

广告主在广告平台配置监测链接（含宏字段）。当 TapTap 用户发生广告交互行为（如点击下载按钮）时，平台会通知填写到后台的监测地址，广告主可以获取回调请求中的设备信息进行归因匹配。匹配到安装激活及后续深度事件后，通过深度回传接口将事件回传给 TapAD，平台在报表上进行数据展示。

适用范围：通过 TapTap 推广平台投放的游戏产品广告监测；
适用平台：Android / iOS（小游戏请参考 3.5 小游戏数据接入）。

3.2 广告监测事件下发

3.2.1 监测链接与宏字段

监测链接主要由 https://xxx.xxx.com?参数 + 其他部分组成，监测配置在游戏维度上，只需配置一条监测链接即可监测到所有计划/创意数据。

基本要求：

监测地址需要是合法的 http 或 https 链接，长度不能超过 1000 个字符；
回调地址应当返回 2xx 或 3xx 的 http code；回调地址调用失败时，Tap 下发服务会进行 3 次尝试，3 次尝试失败会丢弃该回调；
宏参数必须全大写，否则无法回传对应参数值；
监测链接不能是下载链接；展示、点击监测链接不支持串接代码；监测链接必须支持连通；
监测链接不能包含非法字符，包括但不限于：url path 中出现的单个 %（后面不跟 2 位 16 进制数）、空格、连续 //。

支持的宏字段：

宏	说明
`{IDFA}`	iOS 设备的 IDFA，使用原始的大写值，不存在时传递空字符
`{IDFA_MD5}`	IDFA md5 值
`{CAID}`	iOS 设备中国广告协会互联网广告标识，包含最新两个版本的 CAID 和版本号（URL Encode 后的 JSON 数组）
`{PAID}`	拼多多广告 ID（Pinduoduo Advertisement IDentifier）
`{ANID}`	Android 设备的 Android ID，使用原始的数据值，Android 8 以后基本不可用
`{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"
`{CREATIVE_NAME}`	创意名称
`{CONVERSION_TYPE}`	下载类型：广告下载 "TapTapAd" 和间接下载 "TapTapNature"（目前仅下发广告下载）
`{DEVICE}`	设备类型：iOS 下发 "1"，android 下发 "0"
`{DEVICE_BRAND}`	设备品牌
`{DEVICE_MODEL}`	设备型号
`{OS_VERSION}`	系统版本号
`{WEB_UA}`	浏览器 UA
`{TAP_TRACK_ID}`	广告归因 ID，用于深度回传服务，默认下发（`tap_track_id={TAP_TRACK_ID}`），无需额外配置
`{TAP_PROJECT_ID}`	游戏 ID，默认下发（`tap_project_id={TAP_PROJECT_ID}`），无需额外配置
`{DEEP_CALLBACK_URL}`	深度回传链接（激活、注册、付费、次留等），默认 HTTPS 协议，按照要求拼接上相关参数回传深度事件。`{CALLBACK_HTTPS}` / `{CALLBACK_HTTP}` 不推荐使用，新建监测链接已废弃，存量不受影响

3.2.2 链接示例

配置链接：

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}

平台回传给广告主归因服务对应的示例（宏替换后）：

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=1111

tap_track_id、tap_project_id 两个字段在下载回传服务中默认下发，在深度事件回传中需回传该字段，也可以通过 {TAP_TRACK_ID} 和 {TAP_PROJECT_ID} 宏进行获取。

3.2.3 使用流程

广告主在广告平台针对游戏/计划/创意维度填写相应的监测链接；
平台在广告产生相应的监测事件后，将对应的事件通过广告主填写的链接进行相应的宏替换，将事件实时传给广告主，并且附带上对应的深度回传链接；
广告主获取到对应的事件后存储下来；
广告主的 App 在安装完成后，产生对应的激活等深度事件，通过设备 ID 精准匹配或者 IPUA 模糊归因的手段，将产生的激活事件归因到广告平台下发的前置事件上，并且调用前置事件中的深度事件回传链接将事件回传给平台；
平台在报表上进行相应的数据展示。

注意：Appsflyer、热云等第三方需要先单独进行对接。

3.3 广告深度转化事件回传

3.3.1 请求方式

转化事件发生后，广告主/第三方在请求接口后附上回传字段，并发起 GET 请求上报给 TapAD：

{DEEP_CALLBACK_URL}&event_type=xxx&event_timestamp=xxx&???=xxx

注意事项：

tap_project_id、tap_track_id 默认填充在 {DEEP_CALLBACK_URL} 中，不需要再次拼接这两个参数；
由于历史问题，使用旧回传宏 {CALLBACK_HTTPS} / {CALLBACK_HTTP} 的客户建议尽快更换为新宏 {DEEP_CALLBACK_URL}；
旧宏在下发时默认会添加 event_timestamp 和 event_type，请不要在后面再次拼接，造成重复参数；务必用真实事件时间和类型替换掉下发时这两个参数值，否则会导致事件缺失或时间错误造成报表数据看不到，尤其是回传付费事件时。

3.3.2 字段说明

字段	是否必传	类型	说明
`tap_track_id`	必填	string	广告 ID，前序事件中会下发，`{DEEP_CALLBACK_URL}` 中也会拼上该字段
`tap_project_id`	必填	int	游戏 ID，前序事件中会下发
`event_type`	必填	int	转化事件类型，枚举值见下表
`event_timestamp`	必填	int	事件发生时间戳（单位：秒）。若为回传时间会导致归因失败
`amount`	event_type = 3 付费事件时必填，其他不填	int	付费金额（整数，单位：分）
`md5_android_id`	选填	string	ANDROID md5 后的 android_id 值（32 位小写）
`md5_oaid`	选填	string	ANDROID md5 后的 oaid 值（32 位小写）
`ipv4`	选填	string	ipv4 值
`ipv6`	选填	string	ipv6 值
`ua`	选填	string	ua 标准值
`device_model`	选填	string	设备型号（Android: Build.MODEL）
`device_brand`	选填	string	设备名称（Android: Build.MANUFACTURER）
`os_version`	选填	string	系统版本（Android: Build.VERSION.RELEASE）
`replenish`	选填，数据修复时必填	int	0：非补数据（默认 0）；1：补历史数据

event_type 枚举值：

值	事件	描述
1	激活	首次打开 APP
2	注册	在 APP 内注册账户/创角
3	付费（多次）	付费金额通过 `amount` 字段回传
4	次留	次日留存
5	全渠道首次吊起	当日 App 首次被促活广告拉起
6	关键事件	用户在 App 进行了一些黑盒关键行为，如加购等
7	用户标签	您可自定义的用户标签（未与平台沟通则不会实际生效）

为了有效优化广告深度转化效果，回传事件定义务必与文档一致。

3.3.3 数据修复

当已回传数据出现缺失、遗漏、错误等问题时，可修复过去已经传回的错误数据。

离线回传：通过线下方式提供数据文档给到 TapAD，完成数据修复。Tap 会清除已回传的历史数据，一切以新传数据为准。需满足以下数据要求：
- 数据规模：全量回传，以修复时间为节点，回传修复前的所有数据；
- 回传字段：深度事件所有字段，无数据字段可回传空值；
- 文件格式：不限。
API 回传：通过深度接口 {DEEP_CALLBACK_URL} 宏中的 host 加上对应的参数回传数据，完成数据修复。API 方式修复数据需要回传必传字段 replenish（1 = 补历史数据），用于区分是否为后补数据。

3.4 模拟联调（新版）

新版模拟联调全链路对齐线上环境，真实广告展示（不计费），支持激活/付费回传，完善的前置校验流程。

使用前提：

安装 TapTap 客户端，并登录；
TapAd 有可投放的广告计划和创意，用于客户端广告展示；
准备好可访问的监测链接（包含宏参数 {DEEP_CALLBACK_URL}）。

具体流程：

获取 TapTap 用户 ID：只有对应用户的设备才能出联调广告；
新建模拟联调配置：正确选择要联调的游戏、设备、转化目标（目前支持激活/付费），填写要用于展示广告的设备登录的 TapTap 用户 ID，点击「提交并开始联调」；
开始联调：点击联调页面「开始联调」，联调生效，有效期 30 分钟，有效期内尽快完成下发和回传；联调期间不允许修改 TapTap 用户 ID，联调成功配置自动失效；
等待下发：打开 TapTap 客户端，刷新首页，在第一屏找到联调的测试广告（可能有 1~2 分钟延迟），点击或下载游戏，此时会触发平台侧下发点击事件（可能有 1~2 分钟延迟）；若长时间未找到测试广告，可联系平台运营同学反馈；
等待回传：成功下发后，广告主侧完成或模拟转化目标，归因匹配后将对应事件回传给平台。回传方式为获取对应点击事件填充后的 {DEEP_CALLBACK_URL}，URL 解码后拼接对应转化事件的类型和时间戳，发起 GET 请求回传给平台；
获取联调结果：有效期内成功匹配下发和回传即联调成功；有效期内未成功匹配则过期失败，需要重新联调。

常见情况排查：

长时间处于等待下发状态：未出广告，检查是否有开启的投放中的计划和开启的审核通过的创意；如有仍未出广告，联系平台运营反馈；出广告但下发记录一直失败，检查监测链接是否可正常访问；
已下发但长时间处于等待回传状态：检查回传参数是否正确、回传是否成功（返回的响应值 Code：成功为 0，失败为 -1）；确保是通过 {DEEP_CALLBACK_URL} 拼接的方式完成的回传。

3.5 小游戏数据接入（可选）

接入条件：

只支持微信小游戏上架 TapTap iOS 客户端进行广告投放；
暂时只邀请部分优质微信小游戏进行内测。

Tap 支持通过 API 上报数据的方式进行转化数据对接，主要流程如下：

Tap 在投放的小游戏启动链接上拼接广告参数；
客户从小游戏的唤起路径中获取广告参数（主要是 source、tap_track_id、tap_project_id）；
发生转化事件时，客户通过回传接口进行上报。

获取广告参数： Tap 广告会在跳转小游戏时携带如下参数：

参数	描述	示例
`source`	渠道名称	`taptap`
`tap_track_id`	用于追踪广告效果的参数	`QhjqIfB1tKO7acjcdJBuGA3LYkj`
`tap_project_id`	在 tap 的游戏 id	`10001`
`tap_adset_id`	广告组 id	`1000394`
`tap_creative_id`	创意 id	`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 获取参数。

转化事件回传： 客户获取到回传参数并发生相应转化事件时，拼接事件参数并通过固定接口进行回传，http code = 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	用于追踪广告效果的参数，启动链接上会携带
`tap_project_id`	必传	int	用于追踪广告效果的参数，启动链接上会携带
`event_type`	必传	int	转化事件类型，见枚举值
`event_timestamp`	必传	int	事件发生时间戳（单位：秒）
`amount`	event_type = 3 付费事件时必填，其他不填	int	付费金额（整数，单位：分）
`project_type`	必传	int	3 表示投放的资产为小游戏/小程序

小游戏转化事件类型（event_type）枚举值：

事件类型	枚举值	描述
激活	1	首次打开应用
注册	2	在应用内注册账户/创角
付费	3	可多次回传
次留	4	—
小游戏打开	10	上架 TapTap iOS 客户端微信小游戏打开行为

四、数据展示与问题反馈

广告激活数据会直接展示在广告投放后台；
问题反馈请按以下模板提供（相关问题也可以对接 TapAd 的运营同学），提高排查效率：
- 登录 TapTap 用户 ID；
- 广告主（账号）ID；
- 游戏 ID；
- 计划 ID；
- 创意 ID；
- 问题描述；
- 截图（辛苦全屏，包含 URL）。

五、常见问题（FAQ）

Q：TapAD 激活、深度转化事件的归因窗口期是多久？

A：广告激活归因窗口期为 7 天；深度事件回传的数据不限制窗口期。

Q：广告激活回传/深度转化回传配置成功后，可以收到历史转化数据回传吗？

A：不可以。激活/深度转化事件的数据，仅可接收到配置成功后的数据。

Q：深度事件回传的链接怎么拼接？

A：通过浅层监测事件中配置的 {DEEP_CALLBACK_URL} 宏拼接上相关的回传参数，发起 GET 请求上报给 TapAD。

Q：用户的一次转化事件多次回传给 TapTap，TapTap 会去重吗？

A：会去重的，但建议一次转化事件只回传一次（比如同一次付费、一次激活只回传一次）。

Q：如何获得 IDFA？

A：下载软件 DeviceId 查询，必须先允许跟踪：设置 → 隐私与安全性 → 跟踪 → 允许 App 请求跟踪。

Q：如何获得 CAID？

A：CAID 由中国广告协会提出，旨在提供统一的设备标识符，特别是在苹果和 Google 限制传统广告标识符获取后，保护用户隐私。CAID 在同一设备上的不同应用中是相同的；用户升级系统后 CAID 也随之变化。收费，可通过 API 或 SDK 接入，见互联网广告技术实验室开发者平台。

Q：如何获得 OAID？

A：OAID 由中国信息通信研究院发起，旨在提供匿名的设备标识符，用于广告和用户行为分析，不包含任何个人信息。用户可以在设备设置中重置 OAID（类似于苹果的 IDFA）；在同一设备上，所有应用获取的 OAID 是相同的。免费，获取方式见移动安全工作委员会。

Q：Android 设备拿不到 OAID，导致归因不全怎么办？

A：建议优先接入 SDK 自归因方案。通过 TapSDK 上报事件数据识别广告转化，减少对单一 OAID 的依赖，保证激活、登录、付费转化的完整归因。

Q：SDK 自归因和数据回传归因可以同时接入吗？

A：可以。两种方式互不影响，可并行接入；新接入场景建议优先采用 SDK 自归因。

一、归因方式总览​

二、SDK 自归因（推荐）​

2.1 背景与原理​

2.2 接入目标​

2.3 接入前准备​

2.3.1 开发者中心配置​

2.3.2 开发环境要求​

2.3.3 隐私与合规​

2.4 SDK 接入步骤​

2.5 联调与上线验收​

三、数据回传归因（传统方式）​

3.1 方案概述​

3.2 广告监测事件下发​

3.2.1 监测链接与宏字段​

3.2.2 链接示例​

3.2.3 使用流程​

3.3 广告深度转化事件回传​

3.3.1 请求方式​

3.3.2 字段说明​

3.3.3 数据修复​

3.4 模拟联调（新版）​

3.5 小游戏数据接入（可选）​

四、数据展示与问题反馈​

五、常见问题（FAQ）​