Untitled_doxcnsCq
原始路径：新建广告/Untitled_doxcnsCq
本页含 0 张本地化原始图片 · 0 个本站关联导航
三方（微信）小游戏转化回传技术对接指南
产品投放文档：
**更新日志**
2023.02.07 新增投放2.0参数下发（promotion_id等）
2022.06.22 支持**url&token在线获取**
2022.04.28 path下发参数已增加req_id和advertiser_id，详情见「clue_token下发」。
转化回传全景图
转化回传全流程
clue_token下发
clue_token是用户每次通过广告调起微信小游戏的唯一编码，用于广告主进行自匹配归因，而不再需要点击监测链接。（注意：每次广告调起下发的clue_token均不相同）
广告主**可通过微信小游戏 生命周期getLaunchOptions提取参数值**，文档参考：
[Object wx.getLaunchOptionsSync()](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.getLaunchOptionsSync.html)
**用户跳转至微信小游戏时，字节会将clue_token、项目id、广告id、素材ID、请求ID、账户ID信息以参数形式拼接在小游戏path上**。示例：`path：/pages/index.html?clue_token=___&``project_id=___&promotion_id=___&mid1=___&mid2=___&mid3=___&mid4=___&mid5=___``&req_id=___&advertiser_id=___`
**project_id**：项目id
**promotion_id**：广告id
**mid1-5**：素材id（1图片，2标题，3视频，4试玩，5落地页）
**advertiser_id**：广告账户id
**req_id**：请求下发的id。如果广告主在计划创编时填写第三方监控链接，可请求获取request_id和其他需要的参数（如IMEI、IDFA、OS等，具体参考文档[监测链接发送服务](https://open.oceanengine.com/labels/7/docs/1696710655781900)），然后与path下发的req_id进行映射。
广告主自归因后回传
1. 广告主可以通过字节下发的clue_token来匹配转化数据。
2. 广告主需要获取接口进行转化回传。
3. **Method**
• POST
4. **Content-Type**
• application/json
5. 获取接口信息流程如下：
• ~~广告主提交微信小游戏加白申请后，联系字节对应的运营同学提供url（含path）、密钥token任一账户创建小游戏资产后可在线获取url&token，如有多个账户在投，使用任一账户下获取的url&token进行上报即可~~在巨量纵横工作台可在线获取url&token，具体操作见下图
• url示例：https://xxx.com/xxx?timestamp=\_\_\_\_&nonce=\_\_\_\_\_\_&signature=\_\_\_\_\_\_\_
• \_\_\_\_\_\_下划线里面需要客户填上值，**query参数解释如下Timestamp**转化事件发生时间unix时间戳，秒级别，10位。如1642419633（[转换工具](https://tool.lu/timestamp/)）**Nonce**随机整数（随机即可，防止请求被中间劫持篡改）**Signature**签名反作弊使用**计算签名方式**：
1. 对密钥token，timestamp和nonce三个string进行**升序**排序
2. 将三个string转成bytes放入一个buffer
3. 对byte buffer进行sha1 哈希加密
4. 哈希加密后转成string即为signature
5. 然后将string拼在url上
> 🌰假如token="D528C6F23C7D7", nonce="234", timestamp="1646989046"，
>
> 1. 升序排序后字符串"1646989046234D528C6F23C7D7"
> 2. 对排序后字符串进行sha1转换，结果为"a3c1ad351db9b88c1c5cb7a4cab977f8cd146524"
• golang代码示例：
```Go
strList := []string{token, timestamp, nonce}
sort.Strings(strList)
var buffer bytes.Buffer
for i , str := range strList {
buffer.WriteString(str)
}
h := sha1.New()
h.Write(buffer.Bytes())
r := fmt.Sprintf("%x", h.Sum(nil))
```
• Java 代码示例
```Java
String[] arr={token,nonce,String.valueOf(dto.getTime())}; //进行排序
Arrays.sort(arr);
StringBuffer buffer = new StringBuffer();
for (int i = 0; i < arr.length; i++) {
buffer.append(arr[i]);
}
//进行sha1加密生成签名
String signature=DigestUtils.sha1Hex(buffer.toString());
```
• nodejs代码示例
```JavaScript
const sha1 = require('./sha1.min.js')
let sign = (token, timestamp, nonce) => {
let strList = [token, timestamp, nonce];
strList.sort();
let buffer = "";
strList.forEach(str => {
buffer += str;
})
return sha1(buffer);
}
```
• php代码示例
```PHP
$collect = Array((string)$token,(string)$nonce,(string)$timestamp);
usort($collect,'strcmp');
$signature = sha1(implode('',$collect));
echo $signature;
```
**Body参数**
```Go
{
"clue_token": "xxx", // 用户跳转小程序时携带的clue_token参数
"union_id": "xxx", // 微信union_id
"open_id": "xxx", // 微信open_id，必须回传
"event_type": "0", // 事件类型，string格式
"props": {
"pay_amount": 123 // 当event_type为2，使用付费类出价产品时需上报，单位为分，格式int
}
}
```
• **参数枚举说明：**回传事件定义及标准：不同出价产品需要回传的事件类型：
| event_type（事件类型） 字节侧 | 事件定义 客户侧 | 取值 | 字段定义 | 回传窗口期 |
| active | 激活 （必须回传） | 0 | 投放微信小游戏时，可将首次「调起微信小游戏」定义为激活事件 即，新用户/新设备首次联网打开（不同客户定义口径存在差异，可自行调整）微信小游戏 | 下发clue_token后第1天-第8天内的全量激活数据 |
| active_register | 注册 | 1 | 在调起微信小游戏后，且在联网环境下，在微信小游戏「完成创角」定义为注册事件 | 回传激活后第1天-第8天内的全量注册数据 |
| active_pay | 付费 （投付费必须回传） | 2 | 在调起微信小游戏后，且在联网环境下，「发生交易并完成的每一笔付款」定义为付费事件，付费事件应包括首充及复充数据，并回传付费金额 付费金额回传要求 props:{"pay_amount":xxx} xxx单位为分，格式int | 回传激活后第1天-第8天内的全量付费数据 |
| game_addiction | 关键行为 | 25 | 常见的关键行为有：IPU次数、观看激励视频次数、游戏时长等。具体可参考文档 | |
| next_day_open | 次留 | 6 | 用户激活后次日在互联网环境下打开微信小游戏 | 回传激活后第2天内的全量留存数据 |
| **出价产品** | **需回传的event_type（事件类型）和取值** |
|-|-|
| 激活 | 激活时回传event_type=0 |
| 激活且注册 | 激活时回传event_type=0
注册时回传event_type=1 |
| 激活且付费 | 激活时回传event_type=0
付费时回传event_type=2，回传包括pay_amount |
| 每次付费 | 激活时回传event_type=0
付费时回传event_type=2，回传包括pay_amount，多次付费多次回传 |
| 付费ROI | 激活时回传event_type=0
付费时回传event_type=2，回传包括pay_amount，多次付费多次回传 |
| 直投关键行为 | 激活时回传event_type=0
产生关键行为时回传event_type=25 |
| 次留双出价 | 激活时回传event_type=0
次日再次打开时回传event_type=6 |
**回传举例**：
> 用户在2022年2月25日12:40通过点击字节广告跳转小游戏进行了激活（字节在用户进行的这次跳转进行了对应的clue_token的下发），发生的场景和需要回传的示例如下：
| **时间** | **发生了什么** | **需要回传什么** |
|-|-|-|
| 2022-2-25 12:40:53 | 该用户完成了小游戏激活 | 必须回传
event type=0
timestamp=1645764053（2022-2-25 12:40:53） |
| 2022-2-25 13:18:23 | 该用户完成了首次付费，付费金额为6.6元 | 必须回传
event type=2
pay amount=660
timestamp=1645766303（2022-2-25 13:18:23） |
| …… | …… | …… |
| 2022-2-27 16:56:33 | 该用户完成了第三次付费，付费金额为19.9元 | 必须回传
event type=2
pay amount=1990
timestamp=1645952193（2022-2-27 16:56:33 ） |
> 用户1通过ad1调起微信但并未完成激活（字节对这次跳转下发了clue_token1），用户1再次通过ad2跳转小游戏并完成激活（字节对此次跳转下发了clue_token2），则广告主针对这次的激活转化事件，需通过clue_token2进行激活事件的回传，后续用户1产生的付费也需要通过clue_token2进行回传。
>
> 用户1通过ad3调起小游戏产生的付费，需通过产生激活的clue_token2进行回传
>
> 用户1通过其他途径调起小游戏产生的付费，需通过产生激活的clue_token2进行回传
**Resp**
> http code为200即为正常上报
>
> 接口要求是POST请求，GET请求会404
| 异常情况 | 状态码 | message | 可能原因 |
| token密钥无效 | 400 | Invalid token | 检查token密钥或事件回传url是否和下发的一致 |
| 请求鉴权失败 | 400 | Invalid signature | 检查token和生成的字符串是否正确 |
| body参数解析失败 | 400 | Invalid body | 检查字段类型 |
| event_type不合法 | 400 | Invalid event type |
|
| clue_token不合法 | 400 | Invalid clue token | clue_token格式错误，正确样例参考：“1631518677072900,1727615094120487” |
| 未匹配到任何线索信息 | 400 | 未匹配到任何线索信息,请使用真实环境数据进行上报 |
|
| clue_token不存在或系统异常 | 500 | system err | 非正常途径获取或生成的clue_token |
| 500 | 缺少必要的广告信息字段context.ad | 非线上广告场景下产生的转化，如计划预览等，无法用于上报 |
FAQ
有问题先自查该文档：