快手曝光/点击链接使用文档

本文档用于说明快手媒体接入时，安卓和 iOS 的曝光、点击监测链接如何拼接、各参数含义、哪些参数必填，以及服务端收到请求后的处理逻辑。

适用范围：

快手曝光链接：/kuaishou/impression
快手点击链接：/kuaishou/click

代码入口：

src/main/java/com/adx/tencent/kuaishou/controller/KuaishouTrackingController.java

1. 链接地址

请将 {your-domain} 替换为项目实际对外域名。

1.1 iOS 曝光链接

https://{your-domain}/kuaishou/impression?callback=__CALLBACK__&platform=ios&tagId={baiduTagId}&accountId={accountId}&idfa=__IDFA2__&kenyid_caa=__KENYID_CAA__&ip=__IP__&ua=__UA__&deduction_rate={0-100}&ts=__TS__

1.2 iOS 点击链接

https://{your-domain}/kuaishou/click?callback=__CALLBACK__&platform=ios&tagId={baiduTagId}&accountId={accountId}&idfa=__IDFA2__&kenyid_caa=__KENYID_CAA__&ip=__IP__&ua=__UA__&deduction_rate={0-100}&ts=__TS__

1.3 Android 曝光链接

https://{your-domain}/kuaishou/impression?callback=__CALLBACK__&platform=android&tagId={baiduTagId}&accountId={accountId}&oaid=__OAID2__&imei=__IMEI2__&androidid=__ANDROIDID2__&ip=__IP__&ua=__UA__&deduction_rate={0-100}&ts=__TS__

1.4 Android 点击链接

https://{your-domain}/kuaishou/click?callback=__CALLBACK__&platform=android&tagId={baiduTagId}&accountId={accountId}&oaid=__OAID2__&imei=__IMEI2__&androidid=__ANDROIDID2__&ip=__IP__&ua=__UA__&deduction_rate={0-100}&ts=__TS__

2. 参数说明

2.1 通用参数

参数名	是否必填	说明
`callback`	必填	快手下发的回传标识。后续回传快手时会从这里取值。
`tagId`	建议必填	百度广告位 ID。若配置了多广告位，必须传。
`platform`	建议必填	平台类型，取值：`ios` / `android`。
`accountId`	必填	快手投放账户 ID。快手扣量按账户维度参与计算。
`ip`	建议必填	用户 IP。若未传，服务端会尝试从请求中获取。
`ua`	建议必填	用户 UA。若未传，服务端会根据平台补默认值。
`deduction_rate`	选填	扣量比例，范围 `0-100`。不传时按 `0` 处理，即不扣量。
`ts`	选填	媒体事件时间戳。用于回传时生成 `event_time`，建议传毫秒时间戳。

说明：

callback 从业务上应视为必填。没有 callback 会导致后续无法正常回传快手。
tagId 与 platform 至少要能让服务端定位到正确的百度 appId/tagId 配置。若同一平台只配置了一个 tagId，理论上可仅传 platform；为减少歧义，建议始终传 tagId。

2.2 iOS 设备参数

参数名	是否必填	说明
`idfa`	至少一种	对应快手宏 `__IDFA2__`，iOS 下的 IDFA MD5。
`kenyid_caa`	至少一种	对应快手宏 `__KENYID_CAA__`，URL Encode 后的 CAID JSON 数组。

说明：

idfa、kenyid_caa 至少传一种。
若两者都传，服务端会一起带给百度。

2.3 Android 设备参数

参数名	是否必填	说明
`oaid`	至少一种	对应快手宏 `__OAID2__`，Android 下的 OAID MD5。
`imei`	至少一种	对应快手宏 `__IMEI2__` 或 `__IMEI4__`，Android 下的 IMEI MD5。
`androidid`	至少一种	对应快手宏 `__ANDROIDID2__`，Android 下的 AndroidID MD5。

说明：

oaid、imei、androidid 至少传一种。
推荐优先传 oaid。

3. 当前不需要传的参数

以下参数在当前快手链路中不再参与主流程，也不再进入 Redis 瘦身白名单：

campaignid
aid
cid
deduction_key

说明：

快手扣量已按腾讯口径收敛，不再使用 deduction_key。
如无特殊排障需求，不需要继续向媒体暴露这些参数。

4. 服务端处理逻辑

4.1 曝光链接

服务端收到 /kuaishou/impression 请求后：

规范化请求参数。
根据 tagId/platform 解析百度广告位配置。
拼装百度竞价请求并调用百度 ADX。
落 kuaishou_ad_bid_events 竞价事件数据。
将百度返回的曝光监测地址上报，并记录到 kuaishou_tracking_reports。
返回 JSON：

{
  "qk": "xxx",
  "traceId": "xxx",
  "tagId": "xxx"
}

4.2 点击链接

服务端收到 /kuaishou/click 请求后：

优先按 traceId 从 Redis 查快手 bid 缓存。
若未命中，则补发一次百度竞价请求并落缓存。
调用百度点击监测地址。
点击完成后对 Redis 中的 bid 数据做瘦身。
若百度返回了落地页或商店链接，则 302 跳转到目标地址。
若没有可跳转地址，则返回 JSON：

{
  "qk": "xxx",
  "traceId": "xxx",
  "tagId": "xxx"
}

5. 回传与扣量逻辑

5.1 快手回传

在百度转化拉取后：

先根据 qk 匹配快手 bid。
再根据 tagId + baidu_act 解析 kuaishou_tag_event.event_type。
回传前先查 kuaishou_media_callbacks，只发送未处理过的回传任务。

5.2 扣量逻辑

快手扣量已按腾讯口径处理：

对外链接只需要传 deduction_rate
扣量在百度转化回流时计算
扣量维度：accountId + act + date

扣量命中时：

不回传快手
仅落 kuaishou_media_callbacks
dispatch_status = DEDUCTED

5.3 回传去重

相同回传任务不会重复发送。去重依据为回传任务的 dedupe_key。

已视为“处理过”的情况：

ok = 1
或 dispatch_status = DEDUCTED

6. `kuaishou_tag_event` 配置要求

当前 kuaishou_tag_event 只保留以下字段：

tag_id
baidu_act
event_type

说明：

event_type 为快手回传事件类型。
不再通过表字段配置 event_props_json。
若某些特殊 event_type 需要额外业务字段，应由代码按 event_type 分支处理。

7. 联调建议

建议媒体侧按以下最小参数集进行联调：

iOS 最小参数集

callback + platform + tagId + accountId + idfa/kenyid_caa + ip + ua

Android 最小参数集

callback + platform + tagId + accountId + oaid/imei/androidid + ip + ua

如需扣量

再补：

deduction_rate

8. 注意事项

callback 必须可用，否则后续无法正常回传快手。
accountId 建议始终传，避免扣量维度退化到 unknown。
tagId 建议始终传，避免多广告位场景下路由错误。
deduction_rate 仅影响转化回流后的扣量，不影响曝光/点击请求本身是否成功。
若快手侧后续需要使用特殊 event_type，需提前确认是否存在额外必填业务字段。

9. 快手宏对应关系

链接参数	快手宏
`idfa`	`__IDFA2__`
`kenyid_caa`	`__KENYID_CAA__`
`oaid`	`__OAID2__`
`imei`	`__IMEI2__` 或 `__IMEI4__`
`androidid`	`__ANDROIDID2__`

KUAISHOU_TRACKING_LINK_USAGE.md 6.9 KB Histórico Raw