跳到主要内容

数据对接指引

更新日志

日期更新内容
2024.03
  • 增加微信小游戏上架TapTap iOS客户端进行投放(部分内测)对接流程
  • 2023.11
  • 增加深度事件回传 event_type 的枚举值
  • 2023.09
  • 增加{IPV6}宏

  • 增加模拟联调流程图
  • 一、目录

    本文主要介绍 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, 使用原始的数据值,不存在时传递空字符串
    {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}深度回传链接(激活、注册、付费、次留等),按照要求拼接上相关参数回传深度事件

    2.3 注意事项

    • 深度数据回传:当广告主通过链接成功匹配到安装激活及后续深度事件时,应该将深度数据回传给 TapTap 广告系统。 在监测链接中,可以设置 {DEEP_CALLBACK_URL}宏,它们会被替换为深度回传地址,默认 HTTPS 协议,按照要求拼上对应的参数回传深度事件
    • 宏参数必须全大写,否则无法回传对应参数值
    • 监测链接不能是下载链接
    • 展示、点击监测链接不支持串接代码
    • 监测链接必须支持连通
    • 监测链接不能包含非法字符
      • 非法字符包括但不限于如下列表:
    序号非法字符字符解释
    1%url path 中出现的单个的 %,后面不跟 2 位 16 进制数;转义字符中的 % 没有问题
    2空格url 中出现的空格
    3//url path 中出现的连续 //

    2.4 链接示例

    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=xxx&event_type=xxx&event_timestamp={timestamp}&???=xxx),并发起 GET 请求,上报给 TapAD。

    3.2 字段说明

    字段是否必传类型描述
    tap_track_id必填stringxx广告 ID,前序事件中会下发 {DEEP_CALLBACK_URL}中也会拼上该字段
    tap_project_id必填int10231游戏 ID,前序事件中会下发
    event_type必填int枚举值{1,2,3,4,5,6}:1:激活 首次打开 APP 2:注册 在 APP 内注册账户/创角 3:付费(多次)4:次留 5:全渠道首次吊起(当日 app 首次被促活广告拉起) 6:关键事件 (用户在 app 进行了一些黑盒关键行为, 如加购等)转化事件类型为了有效优化广告深度转化效果,回传事件定义务必与文档一致
    event_timestamp必填int1321423400时间戳(单位:秒)事件发生时间 若为回传时间会导致归因失败
    amountevent_type = 3 付费事件时必填,其他不填int10000付费金额(单位:分)
    md5_android_id选填stringce5b074b70316009fd1c33c4a3eb3ea4ANDROID md5 后的 android_id 值(32 位小写)
    md5_oaid选填stringcw5b074b70316009fd1c33c4a3eb3ea4ANDROID md5 后的 oaid 值(32 位小写)
    ipv4选填string10.25.49.101ipv4 值
    ipv6选填string2345:0425:2CA1:0000:0000:0567:5673:23b5ipv6 值
    ua选填stringMozilla/5.0 (Linux; U; Android 2.3.7; en-us; Nexus One Build/FRF91)ua 标准值
    device_model选填stringvivo X7设备型号 Android:Build.MODEL
    device_brand选填stringvivo设备名称 Android:Build.MANUFACTURER
    os_version选填string5.1.1系统版本 Android:Build.VERSION.RELEASE
    replenish选填 数据修复 必填int0仅用于数据修复,补数据时使用 0:非补数据(默认 0)1:补历史数据

    4、数据修复

    4.1 场景

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

    4.2 修复方式

    4.2.1 离线回传

    通过线下方式,提供数据文档给到 TapAD,完成数据修复。Tap 会清除已回传的历史数据,一切以新传数据为准。 需满足以下数据要求:

    1. 数据规模:全量回传,以修复时间为节点,回传修复前的所有数据。
    2. 回传字段:深度事件所有字段,无数据字段可回传空值。
    3. 文件格式:不限
    4.2.2 API 回传

    通过深度接口{DEEP_CALLBACK_URL}宏中的 host 加上对应的参数回传数据,完成数据修复。 API 方式修复数据,需要回传必传字段 replenish,用于区分是否为后补数据。

    字段是否必传类型描述
    replenish必填int0仅用于数据修复,补数据时使用 0:非补数据(默认 0) 1:补历史数据

    四、小游戏数据接入流程

    1、整体流程

    小游戏接入条件

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

    Tap支持通过API上报数据的方式进行转化数据对接。

    主要流程如下:

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

    2、获取广告参数

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

    参数描述类型示例
    source渠道名称stringtaptap
    tap_track_id用于追踪广告效果的参数stringQhjqIfB1tKO7acjcdJBuGA3LYkj
    tap_project_id在 tap 的游戏 idint10001
    tap_adset_id广告组 idint1000394
    tap_creative_id创意 idint234232323

    启动路径示例: pages/index/index?source=taptap&tap_track_id=QhjqIfB1tKO7acjcdJBuGA3LYkj&tap_project_id=10001&tap_creative_id=234232323&tap_adset_id=1000394

    通过启动链接唤起小游戏后,客户在小游戏内部通过wx.getLaunchOptionsSyncwx.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时间戳(单位:秒),事件发生时间
    amountevent_type = 3 付费事件时必填,其他不填int例:10000付费金额(单位:分)
    project_type必传int3表示投放的资产为小游戏/小程序

    转化事件类型参数(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:会去重的,但建议一次转化事件只回传一次(比如同一次付费、一次激活只回传一次)