小程序转化数据API自归因

前置条件

上传微信行为数据时，首先必须获取 openID 所对应的 APP ID 授权。如果未经授权或 APPID 和 openID 不是对应关系，将导致归因失败。授权操作详见微信数据接入。

1 转化数据上报说明及示例

微信小程序的 API 自归因利用__CALLBACK__(cb)或 click_id、wechat_openid、wechat_app_id 作为用户标识，从而实现腾讯点击数据和全网转化数据的匹配。因此必须将 cb 或 clickid 或 wechat_openid 和 wechat_app_id，连同转化类型（ActionType）一并上报给腾讯广告，经过腾讯广告计算后，将最终数据呈现在投放端。

名词解释

cb：直接从点击转发出去的__CALLBACK__字段中 URLDecode 获得，每次点击唯一，作为上报地址使用。
click_id：对于推广 Web 落地页而言，在腾讯广告推广时，每次点击都会生成一个 click_id，在跳转到落地页时，会将 click_id 作为参数传入对应的 URL 中。对于腾讯广告非微信流量为 URL 中的参数 qz_gdt 的值，对于微信流量为 URL 中的参数 gdt_vid 的值。

2 选择监测链接，通过 callback 上报

2.1 配置监测链接

监测类型
广告点击
广告曝光
视频号

2.2 获得 access_token

方式1:通过 DataNexus 代为生成永久密钥

当接口权限集 = 数据上报（User Actions）时，在数据源接入页面，点击【查看密钥】，获得 token 信息。

interface_prepare_08

方式2:自行生成密钥

当接口权限集 ≠ 数据上报（User Actions），请通过 Oauth 2.0 获得 access_token 引导完成操作。

2.3 开启鉴权

进入 DataNexus - <广告效果监测> 页面，选择【查看开启配置】。勾选后，点击【确定】。

tracking_api_list_03

__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，可采集到的设备标示
        "wechat_openid":"",//当为小程序类转化时，此字段与wechat_unionid必传其一
        "wechat_unionid":"",//当为小程序类转化时，此字段与wechat_openid必传其一
        "wechat_app_id":"",//用户发生该行为对应的小程序appid，该字段必填，并确保该appid已对该账户进行了授权（请参考帮助中心-转化归因使用指南-微信小程序转化归因操作手册中的appid授权部分）
                },
        "action_type":"COMPLETE_ORDER", // 必填 行为类型
        "action_param":{
            ......
        }
        }
    ]
}'

2.4.2 应答示例

{
  "code": 0,
  "message": "",
  "message_cn": {},
  "trace_id": "ee1fe1f904985216ca4d761c07840d16_0" //DataNexus 赋予的唯一 id 值，供排查问题使用，若咨询反馈中心请提供该字段的值
}

3 未选择监测链接，直接上报

3.1 post 形式上报 click_id

使用此方式时，需要满足：

您在创建转化时候没有使用点击监测，这一步可以和您的广告投放方确认，在投放管理平台 → 上方工具箱 → 转化归因-Web类-小程序转化时没有使用监测服务
在上报前必须在投放管理平台 → 上方工具箱 → 转化归因-Web类-微信小程序转化，创建 wechat_app_id 字段中对应的 appid 转化。这一步可以联系您的广告投放方完成，填写的 appid 与您上报时的 wechat_app_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开头）。上报地址__CALLBACK__是直接从点击转发出去的__CALLBACK__字段中 URLDecode 获得，上面示例中的 url&path 是示例请求，请勿直接上报。

4 确定行为类型

在数据上报接口的必填字段 action_type 中，填写需要上报的转化行为类型。常用的优化目标对应行为类型请见下表，完整转化行为请参考 action_type 标准行为类型枚举。

优化目标名称	标准行为（action_type）	行为参数（action_param）	投放端指标	备注
下单	COMPLETE_ORDER		下单量	若要上报金额请在param中添加参数“value”：123
表单预约	RESERVATION
注册	REGISTER		注册量
激活	ACTIVATE_APP		激活量	对同一个应用30天内重复的设备激活行为去重
次日留存	START_APP	length_of_stay=1	次日留存量	对同一个应用30天内重复的设备次留行为去重
首次付费	PURCHASE		首次付费量	若要上报金额请在param中添加参数“value”：123
确认意向	CONFIRM_EFFECTIVE_LEADS		有效线索量
授信	CREDIT		金融授信量	若要上报金额请在param中添加参数“value”：123
关注	FOLLOW
付费	PURCHASE			若要上报金额请在param中添加参数“value”：123
加企业微信客服	SCANCODE		加企业微信客服次数
关键页面访问	VIEW_CONTENT
广告变现	AD_PURCHASE			若要上报金额请在param中添加参数“value”：123
公众号内注册	REGISTER
商品详情页浏览	PRODUCT_VIEW
7日留存	START_APP	length_of_stay=7
跳转按钮点击	LANDING_PAGE_CLICK
扫码加粉	SCANCODE_WX
综合线索收集	CLAIM_OFFER 或 ONLINE_CONSULT 或 MAKE_PHONE_CALL 或 RESERVATION 或 SCANCODE
关键行为	action_type报“CUSTOM”，custon_action报“UV_CORE_ACTION”
在线咨询	ONLINE_CONSULT
24小时下单	COMPLETE_ORDER			若要上报金额请在param中添加参数“value”：123
加群	ADD_GROUP
快应用加桌面	ADD_DESKTOP
电话拨打	MAKE_PHONE_CALL
小游戏创角	CREATE_ROLE
进件	APPLY			若要上报金额请在param中添加参数“value”：123
快速下单	COMPLETE_ORDER
互动问答	RESERVATION_CHECK
领券	CLAIM_OFFER
预付定金	PRE_PAY			若要上报金额请在param中添加参数“value”：123
主动一句话咨询	CONSULT	consult_type=”INTELLIGENT_TOOL” AND consult_active_type=”1_1″
三句话咨询	CONSULT	consult_type=”INTELLIGENT_TOOL” AND consult_active_type=”3_0″

5 转化上报常用参数列表（action_param）

参数名	类型	描述	是否必填	取值范围	备注
value	int	订单价值，单位：分	否	-	体现转化带来的价值，在上报COMPLETE_ORDER或PURCHASE行为时可选填
object	string	行为对象	否	^.{0,200}$	在上报VIEW_CONTENT行为时参数填写为object=product，表示上报的是商品页面浏览行为
consult_type	string	咨询类型	否	^.{0,200}$	MAKE_PHONE_CALL 电话咨询、ONLINE_CONSULT 网页咨询和RESERVE_PHONE_NUMBER 电话回拨

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：在 <投放管理平台>-<工具>-<转化归因> 中选择【已有数据源上报】即可。

tracking_api_list_01

该内容是否有帮助？

1 转化数据上报说明及示例​

2 选择监测链接，通过 callback 上报​

2.1 配置监测链接​

2.2 获得 access_token​

方式1:通过 DataNexus 代为生成永久密钥​

方式2:自行生成密钥​

2.3 开启鉴权​

2.4 post 形式上报 cb​

2.4.1 请求体示例​

2.4.2 应答示例​

3 未选择监测链接，直接上报​

3.1 post 形式上报 click_id​

3.1.1 请求体示例​

3.1.2 应答示例​

4 确定行为类型​

5 转化上报常用参数列表（action_param）​

6 数据上报错误提示​

FAQ​