接口文档SDK业务专题开发者工具

点击监测链接使用指南

一. 点击监测链接的作用是什么?

广告主在创建转化归因规则的时候,会在转化id上填写“点击监测链接”,用来接收AMS发出的点击信息。通过约定指定格式的字符串,用以代表将来将要替换的字段位置,这个格式我们统称为“宏”。

二. 点击监测的格式要求

监测链接主要由https://XXXX.XXX.com?+参数。具体格式如下:
(1) 监测链接的前缀格式为:

https://XXX.XXX.com?

(2) 宏“参数”的格式为“__参数__”,其中:

  • 参数必须全部大写,广告主可以根据自己的需要选择具体填写哪些参数,AMS支持宏参数请见下方;
  • “__参数__”格式中参数两边为双下划线,即参数左右两边均为两个连续的英文字符’_’
  • 若为点击监测的回传方式,必选字段

    为“__CALLBACK__”;其他场景“__CALLBACK__”不可选;

(3) 链接可以用http、https开头,不能直接用ip、必须是正式的域名;使用https的话机器不能有多个域名,不支持sni;

三. 点击监测链接示例

  1. 广告主填写在转化id创建时的监测链接如下:
https://www.example.com/click/?adgroup_id=__ADGROUP_ID__&ad_id=__AD_ID__&muid=__MUID__&callback=__CALLBACK__

这里的 “__ADGROUP_ID__ ”,就是一个宏,代表将来真实的ADGROUP_ID 字段会在这里填写。
用户在腾讯的媒体上浏览广告并真实产生了广告点击的时候,我们会把相应的字段换成真实的广告信息,发送给广告主。

  1. 广告主收到的真实请求:
https://www.example.com/click/?adgroup_id=228691429&ad_id=251986746&muid=8d3ebd3654fb46a2832296669cf1b536&callback=http%3A%2F%2Ftracking.e.qq.com%2Fconv%3Fcb%3DMTIzYWJjNDU2ZGVm%26conv_id%3D12345678

其中下划线的部分,就是我们替换后的真实广告信息(非 ASC 字符,进行了 url encode)

四. 点击监测字段列表

所有字段 宏定义 支持版本 字段说明 枚举值及样例说明
click_id __CLICK_ID__ 兼容新旧版本广告 点击id 24oi6xq2aaakvagnqu7a
click_time __CLICK_TIME__ 兼容新旧版本广告 点击时间 1586437362
impression_time __IMPRESSION_TIME__ 兼容新旧版本广告 曝光时间 1586437361
campaign_id __CAMPAIGN_ID__ 仅旧版本广告 计划id 102043154
adgroup_id __ADGROUP_ID__ 兼容新旧版本广告 广告组id(实际为广告id) 228691429
ad_id __AD_ID__ 仅旧版本广告 广告id(实际为创意id) 251986746
dynamic_creative_id __DYNAMIC_CREATIVE_ID__ 仅新版本广告 创意 ID 654321
dynamic_creative_name __DYNAMIC_CREATIVE_NAME\ 仅新版本广告 创意名称
creative_components_info __CREATIVE_COMPONENTS_INFO__ 仅新版本广告 创意组件信息 [{"id":101234567},{"id":102345678},{"id":103456789},{"id":104567890}]
element_info __ELEMENT_INFO__ 兼容新旧版本广告 素材信息 [{"id":"123"},{"id":"456"},{"id":"789"}]
marketing_goal __MARKETING_GOAL__ 仅新版本广告 一级营销目的 MARKETING_GOAL_UNKNOWN:未知
MARKETING_GOAL_USER_GROWTH:用户增长
MARKETING_GOAL_PRODUCT_SALES:商品销售
MARKETING_GOAL_LEAD_RETENTION:线索留资
MARKETING_GOAL_BRAND_PROMOTION:品牌宣传
MARKETING_GOAL_INCREASE_FANS_INTERACTION:加粉互动
marketing_sub_goal __MARKETING_SUB_GOAL__ 仅新版本广告 二级营销目的 MARKETING_SUB_GOAL_UNKNOWN:未知
MARKETING_SUB_GOAL_NEW_GAME_RESERVE:新游预约
MARKETING_SUB_GOAL_NEW_GAME_TEST:新游测试
MARKETING_SUB_GOAL_NEW_GAME_LAUNCH:新游首发
MARKETING_SUB_GOAL_PLATEAU_PHASE_LAUNCH:平推期投放
MARKETING_SUB_GOAL_MINI_GAME_NEW_CUSTOMER_GROWTH:新客增长
MARKETING_SUB_GOAL_MINI_GAME_RETURN_CUSTOMER_ENGAGEMENT:回流触达
MARKETING_SUB_GOAL_APP_ACQUISITION:应用拉新
MARKETING_SUB_GOAL_APP_ACTIVATION:应用拉活
marketing_target_id __MARKETING_TARGET_ID__ 仅新版本广告 营销对象 12345
marketing_carrier_id __MARKETING_CARRIER_ID__ 仅新版本广告 一级营销载体 20001111111
marketing_sub_carrier_id __MARKETING_SUB_CARRIER_ID__ 仅新版本广告 二级营销载体 0;00012301234567890123456789
marketing_asset_id __MARKETING_ASSET_ID__ 仅新版本广告 营销资产ID 12345
material_package_id __MATERIAL_PACKAGE_ID__ 仅新版本广告 素材标签ID 6123456123456123456
ad_platform_type __AD_PLATFORM_TYPE__ 兼容新旧版本广告 广告投放平台 1: GDT entrance
3: 京东直投
5: 经wechat mp投放的广告
6: 京东运营
8: QQ公众账号平台
9: 移动联盟SSP
10: 58运营
11: 58商户
12: 易车运营
13: 易车商户
14: 融360运营
15: 融360商户
16: 点评运营
17:点评商户
18: 来自OMG的广告主
19: 京东外单
ad_type __AD_TYPE__ 兼容新旧版本广告 广告类型 1: 普通广告 DYNAMIC_AD_TYPE_COMMON
2: 动态创意广告 DYNAMIC_TYPE_DYNAMIC_CREATIVE
3: 聚合页一跳广告
4: 合约CPM广告
5: 动态标题广告
6: 内容化广告
7: 动态元素广告 DYNAMIC_AD_TYPE_DYNAMIC_ELEMENT
8: 动态图片广告
9: 动态商品图片广告(枫叶相关)
10: 动态商品文字广告(枫叶相关)
11: 动态商品单商品广告
account_id __ACCOUNT_ID__ 兼容新旧版本广告 广告主id 9471147
agency_id __AGENCY_ID__ 兼容新旧版本广告 代理商id 1050262
click_sku_id __CLICK_SKU_ID__ 兼容新旧版本广告 点击sku 478c4a93a054f7c9087b4ecb1f03f8a1
billing_event __BILLING_EVENT__ 兼容新旧版本广告 计费类型 1: CPC BILLINGEVENT_CLICK
2: CPA
3: CPS
4: CPM BILLINGEVENT_IMPRESSION
5: CPD BILLINGEVENT_APP_DOWNLOAD
deeplink_url __DEEPLINK_URL__ 兼容新旧版本广告 应用直达链接(Android) tbopen%3A%2F%2Fm.taobao.com%2Ftbopen%2Findex.html%3F%26action%3Dali.open.nav%26module%3Dh5%26bootImage%3D0%26source%3Dtaobaolive%26h5Url%3Dhttp%3A%2F%2Fhuodong.m.taobao.com%2Fact%2Ftalent%2Flive.html%3Fid%3D258690996826
universal_link __UNIVERSAL_LINK__ 兼容新旧版本广告 应用直达链接(iOS) %25%25universal_link%25%25%3Fallianceid%3D1094307%26sid%3D2603989%26ouid%3Dzaoding2tu2_haogao_ios%26openapp%3D3
page_url __PAGE_URL__ 兼容新旧版本广告 落地页地址 https%3A%2F%2Fh5.gdt.qq.com%2Fxjviewer%2Fnemo%2F1644609
device_os_type __DEVICE_OS_TYPE__ 兼容新旧版本广告 设备类型 ios, android
process_time __PROCESS_TIME__ 兼容新旧版本广告 请求时间 1586437335
promoted_object_id __PROMOTED_OBJECT_ID__ 兼容新旧版本广告 应用id 1101072624, wx69618ae091cf2c76
promoted_object_type __PROMOTED_OBJECT_TYPE__ 兼容新旧版本广告 推广类型 12: Android应用推广 PROMOTED_OBJECT_TYPE_APP_ANDROID
19: iOS应用推广 PROMOTED_OBJECT_TYPE_APP_IOS
20: 应用宝换量应用推广 PROMOTED_OBJECT_TYPE_EXCHANGE_APP_ANDROID_MYAPP
23: 微信公众号推广
25: 京东商品推广
29: 微信品牌活动推广
30: 商品推广 PROMOTED_OBJECT_TYPE_ECOMMERCE
31: 品牌活动推广
35: Android应用推广(应用宝)PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP
36: 优惠券推广
37: QQ消息推广 PROMOTED_OBJECT_TYPE_QQ_MESSAGE
39: 微信门店推广 PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT
41: QQ门店推广 PROMOTED_OBJECT_TYPE_LOCAL_ADS
43: 销售线索收集 PROMOTED_OBJECT_TYPE_LEAD_AD
45: QQ浏览器小程序 PROMOTED_OBJECT_TYPE_QQ_BROWSER_MINI_PROGRAM
46: 微信小游戏推广 PROMOTED_OBJECT_TYPE_MINI_GAME_WECHAT
47: 微信支付代金券推广 PRODUCT_TYPE_WECHAT_PAY_COUPON
49: QQ小游戏推广 PRODUCT_TYPE_WECHAT_PAY_COUPON
1000: 网页推广 PROMOTED_OBJECT_TYPE_LINK
request_id __REQUEST_ID__ 兼容新旧版本广告 请求id vqp7xdombqonw
impression_id __IMPRESSION_ID__ 兼容新旧版本广告 曝光id xkrx5et47h7g401
site_set __SITE_SET__ 兼容新旧版本广告 站点集(待废弃,建议使用site_set_name) 15. 优量汇 SITE_SET_MOBILE_UNION
21. 微信 SITE_SET_WECHAT
22. 应用宝 SITE_SET_MOBILE_YYB
25. QQ、腾讯看点、腾讯音乐 SITE_SET_QQ_MUSIC_GAME
27. 腾讯新闻 SITE_SET_TENCENT_NEWS
28. 腾讯视频 SITE_SET_TENCENT_VIDEO
muid __MUID__ 兼容新旧版本广告 设备id(imei或idfa的加密值) 对IMEI设备号转成小写,再进行md5编码,再小写,32位
对IDFA 设备号保持大写,进行 md5 编码,再小写,32位
d4b8f3898515056278ccf78a7a2cca2d
hash_android_id __HASH_ANDROID_ID__ 兼容新旧版本广告 安卓id做md5加密后小写 797745b011e3286de9e1a1c59ba72c97
ip __IP__ 兼容新旧版本广告 媒体投放系统获取的用户终端的公共IPV4地址 183.226.102.120
user_agent __USER_AGENT__ 兼容新旧版本广告 用户代理(user_agent) Dalvik%2F2.1.0+%28Linux%3B+U%3B+Android+8.0.0%3B+PIC-AL00+Build%2FHUAWEIPIC-AL00%29
callback(自归因api场景必填,其他场景不需要填写) __CALLBACK__ 兼容新旧版本广告 直接提供上报信息回传接口的 url,示例为url encode编码原值,广告主需要decode作为post请求url回传至AMS http%3A%2F%2Ftracking.e.qq.com%2Fconv%3Fcb%3DxXx%252BxXx%253D%26conv_id%3D123
encrypted_position_id(依据联盟白名单判断) __ENCRYPTED_POSITION_ID__ 兼容新旧版本广告 联盟广告位id 8144201
ipv6 __IPV6__ 兼容新旧版本广告 媒体投放系统获取的用户终端的公共IPV6地址 2409%3A8a55%3A4cc0%3A4050%3A2507%3A4922%3Abbe0%3A524b
hash_oaid __HASH_OAID__ 兼容新旧版本广告 Android Q 及更高版本的设备号,64位及以下,取原值后做md5加密 9d271e4d04de7e4b0b4f1df20e79ce64
caid __QAID_CAA__ 兼容新旧版本广告 URL Encode后的JSON数组;其中qaid为中广协ID(即CAID),hash_qaid为CAID原值MD5加密后的结果, version为腾讯版本号,支持两个版本同时下发(即最新版和上一版),腾讯版本号与中广协版本对应关系为:腾讯 1001 = 中广协 20200901;腾讯 1003 = 中广协 20201230; 腾讯1004 = 中广协 20211207;腾讯1005=中广协 20220111;腾讯1006=中广协 20230330 [{"qaid":"12345","hash_qaid":"123456789012345","version":"1003"},{"qaid":"67890","hash_qaid":"6789523654780214556","version":"1006"}] 进行URL Encode后的结果
adgroup_name __ADGROUP_NAME__ 兼容新旧版本广告 广告组名称 三国志·战略版IOS
site_set_name __SITE_SET_NAME__ 兼容新旧版本广告 广告版位 SITE_SET_MOMENTS:微信朋友圈
SITE_SET_WECHAT:微信公众号与小程序
SITE_SET_KANDIAN:腾讯看点
SITE_SET_QQ_MUSIC_GAME:QQ、腾讯音乐及游戏
SITE_SET_MOBILE_INNER:QQ、腾讯看点、腾讯音乐(待废弃)
SITE_SET_TENCENT_NEWS:腾讯新闻
SITE_SET_TENCENT_VIDEO:腾讯视频
SITE_SET_MOBILE_UNION:优量汇
SITE_SET_MOBILE_YYB:应用宝
SITE_SET_PCQQ:PC QQ、QQ 空间、腾讯音乐
SITE_SET_MINI_GAME_WECHAT:微信小游戏
SITE_SET_MINI_GAME_QQ:QQ 小游戏
SITE_SET_MOBILE_GAME:App 游戏
SITE_SET_QBSEARCH:QQ浏览器、应用宝版位
SITE_SET_CHANNELS:微信视频号
SITE_SET_WECHAT_SEARCH:微信搜一搜
campaign_name __CAMPAIGN_NAME__ 仅旧版本广告 计划名称 推广品牌活动-公众号互选广告
ad_name __AD_NAME__ 仅旧版本广告 广告名称 推广品牌活动-20201011-图文-中国教育报
model __MODEL__ 兼容新旧版本广告 机型 PCKM00
M2007J17C
V1813A
RMX2176
M2002J9E
OPPO R11 Pluskt
Redmi 7
iPhone 7
……
boost_exp_info __BOOST_EXP_INFO__ 兼容新旧版本广告 专用于ROI策略(原联合专区RuleLab)的UV分组实验信息,用于区分实验组和对照组 0: 未知
1: base
2: 实验组
boost_model_id __BOOST_MODEL_ID__ 兼容新旧版本广告 专用于ROI策略(原联合专区RuleLab),对应ROI策略的策略ID(原Rule ID),用于定位对应的ROI策略 格式为LongInt
wechat_openid __WECHAT_OPEN_ID__ 兼容新旧版本广告 专用于网页类小程序转化规则的点击监测下发,其它类型不支持该字段下发。每个用户针对小程序应用会产生一个安全的OpenID,只针对当前的小程序有效 ozWH25VK0aodxYMZrX0Lqj9HHhrg
keyword_id __KEYWORD_ID__ 兼容新旧版本广告 专用于搜索广告的关键词ID下发
keyword_text __KEYWORD_TEXT__ 兼容新旧版本广告 专用于搜索广告的关键词下发
ip_md5 __IP_MD5__ 兼容新旧版本广告 媒体投放系统获取的用户终端的公共IPV4地址MD5加密后转小写,仅在新版转化里支持配置
ipv6_md5 __IPV6_MD5__ 兼容新旧版本广告 媒体投放系统获取的用户终端的公共IPV6地址MD5加密后转小写,仅在新版转化里支持配置
caid(原值) __CAID__ 兼容新旧版本广告 URL Encode后的JSON数组:其中caid为中广协ID(即CAID),hash_caid为CAID原值MD5加密后的结果, version为中广协caid版本号,支持两个版本同时下发(即最新版和上一版),仅在新版转化归因支持 对[ { "caid": "bed47550547dc8d51c98b668eb690140","caid_md5": "27dc3f5a7c02e8cba6e699c3ee07b295","version": "20220501"}, {"caid": "cb187c190ba19b7863c803cb27ab2523", "caid_md5":"34ae823c759e5c0480867247c77462bb", "version": "20210501"} ] 进行URL Encode后的结果

注意:callback服务器下发的是 url encode编码原值,直接摘取该字段内容。自归因数据上报时,将callback进行一次 url decode操作后作为post请求url回传至AMS。
存在有些http库会自动进行一次url decode,故在回传数据的时候无需再操作一次decode编译,否则将报错。

五. 字段必填/选填说明

安卓不可选字段:

universal_link / qaid_caa

安卓必填字段:

account_id / click_id / click_time / device_os_type / hash_android_id / hash_oaid / muid / promoted_object_id

安卓A级竞品客户可使用字段:

account_id / agency_id / callback / click_id / click_time / device_os_type / encrypted_position_id / hash_android_id / hash_oaid / impression_id / ip / ipv6 / muid / promoted_object_id / promoted_object_type / user_agent

ios不可选字段:

deeplink_url / hash_android_id / hash_oaid

ios必填字段:

account_id / click_id / click_time / device_os_type / muid / promoted_object_id

iosA级竞品客户可使用字段:

account_id / agency_id / callback / click_id / click_time / device_os_type / encrypted_position_id / impression_id / ip / ipv6 / muid / promoted_object_id / promoted_object_type / qaid_caa / user_agent

网页不可使用字段:

ad_name / campaign_name / deeplink_url / model / promoted_object_id / universal_link

网页必填字段:

account_id / callback / click_id / click_time

网页A级竞品客户可选:

account_id / adgroup_name / agency_id / callback / click_id / click_time / device_os_type / encrypted_position_id / impression_id / ip / ipv6 / qaid_caa / user_agent

网页A级竞品客户可选:

account_id / adgroup_name / agency_id / callback / click_id / click_time / device_os_type / encrypted_position_id / impression_id / ip / ipv6 / qaid_caa / user_agent

小程序必填字段:

account_id / callback / click_id / click_time

小程序不可使用字段:

hash_android_id / hash_oaid / muid / ip / ipv6 / qaid_caa / user_agent / boost_exp_info / boost_model_id

公众号必填字段:

account_id / callback / click_id / click_time

公众号不可使用字段:

hash_android_id / hash_oaid / muid / qaid_caa / wechat_open_id

企业微信必填字段:

account_id / callback / click_id / click_time

企业微信不可使用字段:

hash_android_id / hash_oaid / muid / qaid_caa / wechat_open_id

六、点击监测链接推荐示例

应用类—Android:

https://www.example.com/click/?account_id=__ACCOUNT_ID__&click_id=__CLICK_ID__&click_time=__CLICK_TIME__&device_os_type=__DEVICE_OS_TYPE__&hash_android_id=__HASH_ANDROID_ID__&muid=__MUID__&hash_oaid=__HASH_OAID__&promoted_object_id=__PROMOTED_OBJECT_ID__&campaign_id=__CAMPAIGN_ID__&adgroup_id=__ADGROUP_ID__&ad_id=__AD_ID__&ip=__IP__&user_agent=__USER_AGENT__&promoted_object_type=__PROMOTED_OBJECT_TYPE__&callback=__CALLBACK__

应用类—iOS:

https://www.example.com/click/?account_id=__ACCOUNT_ID__&click_id=__CLICK_ID__&click_time=__CLICK_TIME__&device_os_type=__DEVICE_OS_TYPE__&muid=__MUID__&promoted_object_id=__PROMOTED_OBJECT_ID__&campaign_id=__CAMPAIGN_ID__&adgroup_id=__ADGROUP_ID__&ad_id=__AD_ID__&ip=__IP__&user_agent=__USER_AGENT__&promoted_object_type=__PROMOTED_OBJECT_TYPE__&callback=__CALLBACK__

a级竞品应用类—Android:

https://www.example.com/click/?click_id=__CLICK_ID__&click_time=__CLICK_TIME__&muid=__MUID__&hash_android_id=__HASH_ANDROID_ID__&hash_oaid=__HASH_OAID__&ip=__IP__&user_agent=__USER_AGENT__&account_id=__ACCOUNT_ID__&promoted_object_type=__PROMOTED_OBJECT_TYPE__&device_os_type=__DEVICE_OS_TYPE__&callback=__CALLBACK__

a级竞品应用类—iOS:

https://www.example.com/click/?account_id=__ACCOUNT_ID__&agency_id=__AGENCY_ID__&callback=__CALLBACK__&click_id=__CLICK_ID__&click_time=__CLICK_TIME__&device_os_type=__DEVICE_OS_TYPE__&hash_android_id=__HASH_ANDROID_ID__&hash_oaid=__HASH_OAID__&ip=__IP__&muid=__MUID__&user_agent=__USER_AGENT__&promoted_object_type=__PROMOTED_OBJECT_TYPE__&promoted_object_id=__PROMOTED_OBJECT_ID__

七、点击转发的其它功能介绍

  1. 修改:目前仅支持修改转化名称和点击监测链接的宏。
    若您要修改转化名称,点击转化名称右边的按钮即可进行修改。
    若您要修改点击检测链接,则点击 详情按钮,点击 点击监测链接 旁边的按钮即可修改。目前仅支持修改宏,不允许修改点击链接域名
    一旦配置信息修改提交成功,联调状态默认为未联调;转化状态为未开启。您需要重新进行联调和开启转化状态。
    如果您的转化生效时未配置点击监测链接,目前暂不支持在修改时在该转化下新增。
  2. 删除:您可以通过删除按钮对已有配置进行删除,一旦配置信息删除,系统将停止向您发送对应的点击行为数据。
  3. 详情:您可以通过详情按钮查看配置信息,并修改点击检测链接、进行转化联调联调。

八、FAQ

1.获取点击数据后,广告主如何设置归因逻辑:

应用类:

建议广告主按照如下优先级设置自己的归因逻辑:

对于Android系统:

(1)优先使用muid归因

(2)若muid归因失败,使用AndroidID归因

(3)若AndroidID归因失败,使用oaid归因

(4)若oaid归因失败,使用IP+UA归因

对于iOS系统:

(1)优先使用muid归因

(2)若muid归因失败,使用qaid_ caa归因

(3)若qaid_ caa归因失败,使用IP+UA归因

在新版转化归因链路中,API上报必须将click_id放在callback中回传,具体上报方式可在APP转化数据API自归因文档查看。

微信小程序类:

  • 对于通过点击下发进行归因的方式:建议通过wechat_open_id进行归因,回传自归因成功的click_id与wechat_openid
  • 对于通过落地页参数进行归因的方式:建议通过对应行为发生的小程序参数gdt_vid进行归因,回传全量的gdt_vid中的traceid作为clickid;落地页参数下发可参考:https://ad.weixin.qq.com/guide/679

备注:对于微信小程序,如果通过点击下发和落地页参数同时获取点击信息,不建议通过将点击下发的id信息与gdt_vid信息进行匹配归因(因部分版位拼接的参数id取值逻稍有差异)

2. 对于非OCPX的竞价广告,是否支持用新版转化归因进行点击下发:

新版转化归因的点击下发,需要选择优化目标后,在广告创建流程时绑定转化。目前仅支持应用推广和商品推广场景,对其它场景,不支持用新版转化归因配置点击下发。

应用推广:

⑴ 在转化归因,APP场景下创建转化

⑵在对应转化下填写对应应用ID

⑶选择点击为优化目标,转化联调生效后即可下发

商品推广:

⑴ 在转化归因,WEB场景下创建转化

⑵在对应转化下填写对应落地页域名(如投放原生推广页,域名为https://mp.weixin.qq.com)

⑶选择点击为优化目标,转化联调生效后即可下发

特别说明:仅支持该账户自建的转化,对于从其它广告主账户授权的转化不支持在该种操作下对非ocpx的竞价广告点击下发