跳到主要内容

APP转化数据API自归因


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

1.1 配置监测链接​

监测类型
广告点击
广告曝光
应用激活

1.2 获得 access_token​

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

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

interface_prepare_08


方式2:自行生成密钥​

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


1.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 日全量自动切换为【开启鉴权】状态，请广告主尽早排期切换。


1.4 post 形式上报 cb​

1.4.1 请求参数​

名称类型必填描述
actionsarrayY
返回数组列表，不能大于 50KB，数组最小长度 1，最大长度 50
action_timeintegerY
行为发生时，客户端的时间点。UNIX 时间，单位为秒，如果不填将使用服务端时间填写，最大值 2147483647
user_idobjectC
用户标识，app 数据上报时必填，user_id 与 click_id 二选一必填
hash_imeistring
Android 设备填写，md5 后的 IMEI 设备号，详见 加密方法
md5_sha256_imeistring
Android 设备填写，md5 和 sha 256 后的 IMEI 设备号，详见 加密方法
hash_android_idstring
Android 设备填写，md5 后的 android_id 设备号，详见 加密方法
hash_oaidstring
Android 设备填写，md5 后的 oaid 设备号，详见 加密方法
md5_sha256_oaidstringC
Android 设备填写，md5 和 sha 256 后的 oaid 设备号，详见 加密方法
hash_idfastring
iOS 设备填写，md5 后的 IDFA 设备号，详见 加密方法
md5_sha256_idfastring
iOS 设备填写，md5 和 sha 256 后的 IDFA 设备号，详见 加密方法
gdt_openidstring
GDT Cookie Mapping 分配的 openid，不做处理，字段长度为 64 字节
hash_phonestring
电话号码直接 MD5 编码，如 md5(13500000000)，字段长度为 32 字节
sha256_phonestring
SHA256 算法加密后的手机号，加密前为 11 位的纯数字串，加密后为不计大小写的 64 位数字字母串，字段长度为 64 字节
wechat_openidstring
微信 openid 保持原值。微信 openid 是微信用户在公众号/小程序 appid 下的唯一用户标识（appid 不同，则获取到的 openid 就不同），可用于永久标记一个用户。您只能上传您已经获得授权关联的 APPID 内的 openID。否则会解析失败。请注意，当所填 user_action_set_id 的类型为{WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME}时，此字段和 wechat_unionid 必填其一，字段长度为 64 字节
wechat_unionidstring
微信 unionid 保持原值。微信 unionid 是微信用户在同一个微信开发者账号下的唯一用户标识（开发者账号不同，则获取到的 unionid 就不同），可用于永久标记一个用户。您只能上传您已经获得授权关联的 APPID 所属开发者账号内的 unionid。否则会解析失败。请注意，当所填 user_action_set_id 的类型为{WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME}时，此字段和 wechat_openid 必填其一，字段长度为 64 字节
wechat_app_idstring
微信分配的 APPID。请填写所填的 wechat_openid 对应的 APPID。请确保您已经获得所填 APPID 的授权关联，否则将无法通过鉴权。当您填写 wechat_openid 时，此项必填。当您未填 wechat_openid，此项填写无效。请注意，当所填 user_action_set_id 的类型为{WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME}时，此字段必填，字段长度为 64 字节
caidstring
iOS 设备填写，全称 CAA Advertising id，中国广告协会互联网广告标，详见 加密方法
caid_versioninteger
caid 版本编号。建议上报最新的 caid 版本，最大值 2147483647
action_typeenumY
标准行为类型，见 枚举值，当值为 'CUSTOM' 时表示自定义行为类型
outer_action_idstring
用户自定义的行为 id 标识，最大值 255 字节
action_paramobject
行为所带的参数，最大值 204800 字节
claim_typeinteger
归因类型，腾讯平台会基于归因类型进行对应方式的归因，见 枚举值
valueinteger
订单价值，单位：分，100代表1元。体现转化带来的价值，一般在 action_type 为 COMPLETE_ORDER 或 PURCHASE 行为时选填
objectstring
行为对象，例如 action_type 为 VIEW_CONTENT 时，object=product代表“商品页面浏览
length_of_stayinteger
停留时间，单位：天，例如action_type为START_APP作为留存行为时必填，length_of_stay=1，表示上报的是次日留存行为。枚举值：1、3、5、7，对应归因优化目标次日留存、移动app 3日留存、移动app 5日留存、移动app 7日留存
consult_typestring
咨询类型，见 枚举值
trustinteger
反作弊过滤，广告主判定该转化行为，是否真实可靠。见 枚举值；为空/不上报，与trust=0处理逻辑一致
custom_actionstring
自定义行为类型，当 action_type=CUSTOM 时必填，最大值 128 字节
traceobject
跟踪信息
click_idstring
点击ID，user_id 与 click_id 二选一必填，广点通的click_id长度是20位数字+字母组合；微信的click_id长度是10-50，如wx0im5kwh44gh2yq，字段长度为 64 字节
urlstringC
网页应用填写，url，请填写效果数据发生 h5 页面 URL 地址，如datanexus.qq.com，最大值 2048 字节
product_informobject
商品信息
content_typeenum
商品库行业。当您需要传输的商品信息为商品库行业标准类目时需要填写。详见 枚举值
product_catalog_idstring
商品库 id。您已经同步到腾讯的商品库所对应的商品库 id，当填了商品 id 时，必须填写商品库 id，字段长度为 64 字节
product_idstring[]
与行为相关的商品 id 列表。请填写商品库 id 内对应的商品 id，数组最大长度为 1000
category_pathstring[]
与行为相关的类目名称列表。对于所需回传的每一个商品类目，请按照“一级类目名称/二级类目名称/三级类目名称/四级类目名称”的格式回传完整类目路径，数组最大长度为 16
channelenum
渠道信息，标识该条行为发生在何渠道上，详见 枚举值，转化归因场景中，填写TENCENT或留空时，数据进入转化归因

1.4.2 请求体示例​

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进行去重
        "action_time":1492998081,
        "user_id":{// 必填 user_id，可采集到的设备标示
        "hash_imei":"7a4e6b9571b8911f9a035b3a76228ef7",// 示例，请勿直接上报，android设备上报imei
        "hash_idfa":"abbaa569f8ab7cb1715c8aabe1db1247",// 示例，请勿直接上报，ios设备上报idfa
        "hash_android_id":"",
        "oaid":"",
        "hash_oaid":"",
        "caid":"a424aafe3c44b7e3618a95c0d55a56de",// 示例，请勿直接上报，ios设备上报caid
        "caid_version":"1004",// 示例，请勿直接上报，ios设备上报caid_version
        },
        "action_type":"ACTIVATE_APP", // 必填 行为类型
        "action_param":{
        "value":123,// 选填，用作付费/下单金额等上报
        "int_example":456,// 选填，int类型参数示例
        "int_array_example":[
        123,
        456
        ],// 选填，int类型数组示例
        "string_example":"aaa",// 选填，string类型参数示例
        "string_array_example":[
        "aaa",
        "bbb"
        ]// 选填，string类型数组示例
        }
        }
    ]
}'

1.4.3 应答体结构​

名称类型是否一定返回描述
codeintegerY返回码，等于0表示成功，不等于0表示错误，具体见文档附录
messagestringY错误描述，code不等于0时，message为错误描述
message_cnstring中文错误描述，code不等于0时，message_cn为错误情况的中文描述
dataobject资源数据，具体返回内容见各接口定义，只在code等于0时可能返回
errorsobject详细错误信息，只在code不等于0时可能返回

1.4.4 应答示例​

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


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

2.1 post 形式上报 click_id​

2.1.1 请求体示例​

{
  "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"
    }
  ]
}

2.1.2 应答示例​

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


3 确定行为类型​

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

优化目标名称标准行为（action_type）行为参数（action_param）投放端指标备注
下单COMPLETE_ORDER下单量若要上报金额请在param中添加参数“value”：123
表单预约RESERVATION
注册REGISTER注册量
激活ACTIVATE_APP激活量对同一个应用30天内重复的设备激活行为去重
次日留存START_APPlength_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_APPlength_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
主动一句话咨询CONSULTconsult_type=”INTELLIGENT_TOOL” AND consult_active_type=”1_1″
三句话咨询CONSULTconsult_type=”INTELLIGENT_TOOL” AND consult_active_type=”3_0″


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

参数名类型描述是否必填取值范围备注
valueint订单价值，单位：分否-体现转化带来的价值，在上报COMPLETE_ORDER或PURCHASE行为时可选填
objectstring行为对象否^.{0,200}$在上报VIEW_CONTENT行为时参数填写为object=product，表示上报的是商品页面浏览行为
length_of_stayint停留时间，单位：天否-在上报START_APP作为留存行为时必填。length_of_stay=1，表示上报的是次日留存行为


5 数据上报错误提示​

错误码中文提示英文提示
20001回调 url 内容错误CB_CONTENT_ERROR
20002没有与转化 ID 对应的转化规则CONV_ID_ILLEGAL
20003无效数据源 IDACTION_SET_ID_ABNORMAL
20004无效账户 IDACCOUNT_ID_ABNORMAL
20005编码 base64 密钥失败ENCODE_B64_KEY_ERROR
20006回调 url base64 解码失败DECRYPT_B64_CB_ERROR
30000Api 访问失败API_ERROR



FAQ​

Q：上报行为如何自定义去重？

A：可以在 actions 内加入outer_action_id参数进行自定义去重。

参数名类型说明描述
outer_action_idstring去重标识，字段长度最小1字节，最大长度255字节，且只能为数字，字母，下划线，连接符组成平台会基于user_action_set_id，outer_action_id 和action_type三个字段做去重 ，如果历史上报数据中存在某条数据的这三个字段与当前上报数据完全一样的，则当前数据会被过滤掉

Q：新版转化归因是否支持使用非 callback 上报？

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

tracking_api_list_01




该内容是否有帮助？