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

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

适用范围：

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

代码入口：

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

## 1. 链接地址

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

### 1.1 iOS 曝光链接

```text
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 点击链接

```text
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 曝光链接

```text
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 点击链接

```text
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` 请求后：

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

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

### 4.2 点击链接

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

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

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

## 5. 回传与扣量逻辑

### 5.1 快手回传

在百度转化拉取后：

1. 先根据 `qk` 匹配快手 bid。
2. 再根据 `tagId + baidu_act` 解析 `kuaishou_tag_event.event_type`。
3. 回传前先查 `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 最小参数集

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

### Android 最小参数集

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

### 如需扣量

再补：

```text
deduction_rate
```

## 8. 注意事项

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

## 9. 快手宏对应关系

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