小游戏转化数据API自归因
上传微信行为数据时，首先必须获取 openID 所对应的 APP ID 授权。如果未经授权或 APPID 和 openID 不是对应关系，将导致归因失败。 授权操作详见微信数据接入。
1 转化数据上报说明及示例
微信小游戏的 API 自归因利用__CALLBACK__(cb) / click_id 和微信 openid 作为用户标识，从而实现腾讯点击数据和全网转化数据的匹配。因此必须将 cb / clickid、小游戏 appid、微信 openid 连同转化类型（ActionType） 一并上报给腾讯广告，经过腾讯广告计算后，将最终数据呈现在投放端。微信小游戏统一采用注册归因口径。
名词解释
cb：直接从点击转发出去的__CALLBACK__字段中 URLDecode 获得，每次点击唯一，作为上报地址使用。
click_id：在腾讯广告推广时，每次点击都会生成一个 click_id，用于唯一标识一次用户点击。在微信小游戏场景中，可以从⼩游戏数据监控参数的gdt_vid字段中获取（即微信广告traceid），详见微信⼩游戏⼴告数据监控指引
openid：对于微信小游戏的用户，每个用户都会在每个小游戏生成一个 openid，将 openid 与小程序 appid 作为转化数据的标识。
注册归因：指注册后的行为（如创角、付费等）会归因到前置的注册；建议配合注册口径报表使用。
2 选择监测链接，通过 callback 上报
2.1 配置监测链接
| 监测类型 |
|---|
| 广告点击 |
| 广告曝光 |
| 视频号 |
| 游戏预约 |
| 应用激活 |
| 归因转发 |
2.2 获得 access_token
方式1:通过 DataNexus 代为生成永久密钥
当接口权限集 = 数据上报（User Actions）时，在 数据源接入 页面，点击 【查看密钥】，获得 token 信息。
方式2:自行生成密钥
当接口权限集 ≠ 数据上报（User Actions），请 通过 Oauth 2.0 获得 access_token 引导完成操作 。
2.3 开启鉴权
进入 DataNexus - <广告效果监测> 页面，选择【查看开启配置】。勾选后，点击【确定】。
__CALLBACK__ 中下发的 url 将根据您的【开启鉴权】/【关闭鉴权】操作变化。
| 鉴权状态 | url |
|---|---|
| 开启鉴权 | http%3A%2F%2Fapi.e.qq.com%2Fconv%3Fcb%3DxXx%252BxXx%253D%26conv_id%3D123 |
| 关闭鉴权 | http%3A%2F%2Ftracking.e.qq.com%2Fconv%3Fcb%3DxXx%252BxXx%253D%26conv_id%3D123 |
__CALLBACK__ 中下发的 url 将于 2025 年 3 月 31 日全量自动切换为【开启鉴权】状态，请广告主尽早排期切换。
2.4 post 形式上报 cb
使用此方式时，需要满足： 您在创建转化时候填写了点击监测，这一步可以和您的广告投放方确认，在 投放管理平台→ 上方工具箱 → 转化归因-Web类-小程序转化时已经使用了监测服务。
2.4.1 请求体示例
curl -X POST \
https://api.e.qq.com/v3.0/user_actions/add?cb=YWRzX......iOWNi&conv_id=10001 //这里请求的url&path 直接从点击转发出去的__CALLBACK__字段中URLDecode获得，左边是示例请求，请勿直接上报
-H 'Content-Type: application/json' \
-H 'access-token: <ACCESS_TOKEN>' // 注意：这里是中划线（第 3 部分的非 callback 是下划线），静态 token 可从 DataNexus - 数据源 获得
-H 'timestamp: <TIMESTAMP>'
-H 'nonce: <NONCE>'
-H 'cache-control: no-cache' \
-d '{
"actions":[
{
"outer_action_id": "outer_action_identity", // 选填，若上报可能有重复请填写该id，系统会根据该ID进行去重，详见FAQ
"action_time": 1492998081,
"user_id": { // user_id，可采集到的设备标识
"hash_imei": "f9efca36a3c30e1cf28170d86ecbf5e9",
"hash_idfa": "f9efca36a3c30e1cf28170d86ecbf5e9",
"hash_android_id": "",
"wechat_app_id":"", //微信小游戏上报必填 且必须通过授权
"wechat_openid":"", //微信小游戏上报必填
"oaid":""
},
"action_type": "ACTIVATE_APP", // 必填 行为类型
"action_param": {
"value": 123,
"int_example": 123,
"int_array_example": [
123,
234
],
"string_example": "123",
"string_array_example": [
"123",
"234",
"abc"
]
}
}
]
}'
2.4.2 应答示例
{
"code": 0,
"message": "",
"message_cn": {},
"trace_id": "ee1fe1f904985216ca4d761c07840d16_0" //DataNexus 赋予的唯一 id 值，供排查问题使用，若咨询反馈中心请提供该字段的值
}
3 未选择监测链接，直接上报及 QQ小游戏转化数据上报
注意：QQ 小游戏的 API 自归因仍然采用旧链路的数据源上报方式。QQ小游戏统一采用点击归因口径。
3.1 post 形式上报 click_id
3.1.1 请求体示例
- JAVA
{
"account_id": 1111111111,
"user_action_set_id": 1111111111,
"actions": [
// 以下为 1 次请求的第 1 个行为：自然流量（"channel": "NATURAL")带来的自定义行为（CUSTOM）
{
"outer_action_id": "示例唯一行为 id_请指定", //选填，若上报可能有重复请填写该id，系统会根据该ID进行去重，详见FAQ
"action_time": 1492998081,
"user_id": {
"wechat_openid": "", //微信小游戏上报必填，此字段与wechat_unionid必传其一
"wechat_unionid": "", //微信小游戏上报必填，此字段与wechat_openid必传其一
"wechat_app_id": "" //用户发生该行为对应的小程序appid，该字段必填，并确保该appid已对该账户进行了授权（请参考帮助中心-转化归因使用指南-微信小程序转化归因操作手册中的appid授权部分）
},
"action_type": "COMPLETE_ORDER", // 必填 行为类型
"custom_action": "my_type",
"action_param": {
"value": 28,
"quantity": 5,
"brand_name": "my_brand",
"int_example": 123,
"int_array_example": [123, 234],
"double_example": 123.4500000000000028421709430404007434844970703125,
"double_array_example": [123.45, 234.56],
"bool_example": true,
"bool_array_example": [true, false],
"string_example": "123",
"string_array_example": ["123", "234", "abc"]
},
"product_inform": {
"content_type": "EC",
"category_path": [
"家用电器/厨房小电/豆浆机",
"本地生活旅游出行/旅游出行/机票火车票"
]
},
"trace": {
"click_id": "abc" // 必填 click_id
},
"channel": "NATURAL"
},
// 以下为 1 次请求的第 2 个行为：腾讯流量（"channel": "TENCENT"）带来的购买（PURCHASE）行为。1次请求最多上报50个行为，格式以此类推
{
"outer_action_id": "示例唯一行为 id_请指定",
"action_time": 1492998090,
"user_id": {
"hash_imei": "f9efca36a..."
},
"action_type": "PURCHASE",
"action_param": {
"value": 28,
"quantity": 5,
"brand_name": "my_brand",
"int_example": 123
},
"product_inform": {
"content_type": "EC",
"category_path": [
"家用电器/厨房小电/豆浆机",
"本地生活旅游出行/旅游出行/机票火车票"
]
},
"channel": "TENCENT"
}
]
}
3.1.2 应答示例
{
"code": 0,
"message": "",
"message_cn": {},
"trace_id": "ee1fe1f904985216ca4d761c07840d16_0" //DataNexus 赋予的唯一 id 值，供排查问题使用，若咨询反馈中心请提供该字段的值
}
微信小游戏的转化数据上报必须填写创建转化时填写的小游戏 APPID（以wx开头）和产生转化行为的用户 openid。 上报地址__CALLBACK__是直接从点击转发出去的__CALLBACK__字段中 URLDecode 获得，上面示例中的 url&path 是示例请求，请勿直接上报。
4 确定行为类型
在数据上报接口的必填字段 action_type 中，填写需要上报的转化行为类型。 常用的优化目标对应行为类型请见下表，完整转化行为请参考 action_type 标准行为类型枚举。
| 优化目标名称 | 标准行为（action_type） | 数据指标 | 备注 |
|---|---|---|---|
| 付费 | PURCHASE | 小游戏付费次数 小游戏付费金额（元） | 用户在小游戏中发生购买道具等付费行为 |
| 次留 | START_APP | 小游戏次留人数 | 用户首次进入小游戏后，次日再次进入小游戏 |
| 关键页面访问 | / | 停留大于30s人数 | 注册用户停留大于30s，数据由小游戏平台上报，无需广告主回传 |
| 小游戏创角 | CREATE_ROLE | 小游戏创角人数 | 广告主自定义的小游戏内角色创建行为 |
5 转化上报常用参数列表（action_param）
| 参数名 | 类型 | 描述 | 是否必填 | 取值范围 | 备注 |
|---|---|---|---|---|---|
| value | int | 订单价值，单位：分 | 否 | - | 体现转化带来的价值，在上报COMPLETE_ORDER或PURCHASE行为时可选填 |
| object | string | 行为对象 | 否 | ^.{0,200}$ | 在上报VIEW_CONTENT行为时参数填写为object=product，表示上报的是商品页面浏览行为 |
6 数据上报错误提示
| 错误码 | 中文提示 | 英文提示 |
|---|---|---|
| 20001 | 回调 url 内容错误 | CB_CONTENT_ERROR |
| 20002 | 没有与转化 ID 对应的转化规则 | CONV_ID_ILLEGAL |
| 20003 | 无效数据源 ID | ACTION_SET_ID_ABNORMAL |
| 20004 | 无效账户 ID | ACCOUNT_ID_ABNORMAL |
| 20005 | 编码 base64 密钥失败 | ENCODE_B64_KEY_ERROR |
| 20006 | 回调 url base64 解码失败 | DECRYPT_B64_CB_ERROR |
| 30000 | Api 访问失败 | API_ERROR |
FAQ
Q：上报行为如何自定义去重？
A：可以在 actions 内加入outer_action_id参数进行自定义去重。
| 参数名 | 类型 | 说明 | 描述 |
|---|---|---|---|
| outer_action_id | string | 去重标识，字段长度最小1字节，最大长度255字节，且只能为数字，字母，下划线，连接符组成 | 平台会基于user_action_set_id，outer_action_id 和action_type三个字段做去重 ，如果历史上报数据中存在某条数据的这三个字段与当前上报数据完全一样的，则当前数据会被过滤掉 |
Q：新版转化归因是否支持使用非 callback 上报？
A：在 <投放管理平台>-<工具>-<转化归因> 中选择【已有数据源上报】即可。
