用户行为添加/更新

前置条件

获得数据源，并在资产分发打开该数据源ID 的指定应用场景的分发开关。

请求地址

https://api.e.qq.com/v1.3/user_actions/add

所属权限

数据上报（User Actions）

请求方法

POST

请求参数

参数名	描述
access_token	密钥信息，可在 DataNexus 的数据源 - 【查看密钥】获取
timestamp	当前的时间戳，单位为秒，允许客户端请求最大时间误差为 300 秒。MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳签名算法。MarketingAPI 所使用的时区为 GMT+8，例如当时间戳为 1494840119 时，表示 2017-05-15 17:21:59
nonce	随机字串标识，不超过 32 个字符，由调用方自行生成，需保证全局唯一性

请求体类型

application/json

请求体参数

名称	类型	必填	描述
account_id	integer	Y	推广帐号 id或 DataNexus 账号 id
user_action_set_id	integer	Y	数据源 id，通过DataNexus创建数据源时分配的唯一 id。请注意，当填写的数据源类型为 {WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME} 时，必填 user_id 字段中的 wechat_openid (或 wechat_unionid) 及 wechat_app_id。
actions	array	Y	返回数组列表，不能大于 50KB，数组最小长度 1，最大长度 50
action_time	integer	Y	行为发生时，客户端的时间点。UNIX 时间，单位为秒，如果不填将使用服务端时间填写，最大值 2147483647
user_id	object	C	用户标识，app 数据上报时必填，user_id 与 click_id 二选一必填
hash_imei	string	C	Android设备填写，IMEI 设备号，转小写后md5编码，并选取32位小写数字字母上传。例如原文IMEI：A000002C9060F7，加密时md5(a000002c9060f7)，加密后：f2d5a650733ca8c27d502b1c08da14e5
md5_sha256_imei	string	C	Android设备填写，IMEI 设备号先采用 MD5 加密，再采用SHA256加密，加密前转化成 14 位或 15 位数字+小写字母串，加密后为 64 位小写数字字母组合。例如：加密前 a000002c9060f7，加密后 d64db6590359b386397db4d8a61dbc8fbd586b8a0b822ee6bc19316402d583b4
hash_idfa	string	C	iOS设备填写，先转为8-4-4-4-12格式，再大写，最后进行md5加密，将加密后的32位小写数字字母上报。例如：原文4FCFEFA1-096D-4176-B352-1870ED6DB777，加密后，09c593c62a6074ae5f859e97a222c0e8。iOS设备14版本及以上，建议增加上报caid
md5_sha256_idfa	string	C	iOS设备填写，IDFA 号先采用 MD5 加密，再采用 SHA256 加密，加密前转化成 14 位或 15 位数字 + 小写字母串，加密后为 64 位小写数字字母组合。示例：加密前 a000002c9060f7，加密后 d64db6590359b386397db4d8a61dbc8fbd586b8a0b822ee6bc19316402d583b4
gdt_openid	string	C	GDT Cookie Mapping 分配的 openid，不做处理，字段长度为 64 字节
hash_phone	string		电话号码直接 MD5 编码，如 md5(13500000000)，字段长度为 32 字节
sha256_phone	string		SHA256 算法加密后的手机号，加密前为 11 位的纯数字串，加密后为不计大小写的 64 位数字字母串，字段长度为 64 字节
hash_android_id	string	C	Android设备填写，对 android_id 进行 MD5 编码，字段长度为 32 字节
hash_oaid	string	C	Android设备填写，OAID 设备号 MD5 加密，加密前使用 OAID 原值直接 MD5，不要转换大小写或去连接符，加密后32位小写数字字母组合。例如：原文97e7ef3f-e5f2-d0b8-ccfc-f79bbeaf4841，加密后，87f8274c36eb73fabcbf143a10eca6a4
md5_sha256_oaid	string	C	Android设备填写，OAID 设备号先采用 MD5 加密，再采用 SHA256 加密，加密前使用 OAID 原值直接 MD5，不要转换大小写或去连接符，加密后为64位数字字母组合，小写。例如：加密前 12AD57A5C1D04C00A5B2F2F32213C617fa44f21b8c8744531b222481150a846f，加密后7d36cf61fafac6df50aa7c874148e8241fcb57c61268037d19ed86389100bab0
wechat_openid	string	C	微信应用填写，wechat_openid 和 wechat_unionid 二者必选其一上报。微信 openid 是微信用户在公众号/小程序/小游戏 appid 下的唯一用户标识（appid 不同，则获取到的 openid 不同），可用于永久标记一个用户。您只能上传您已经获得授权关联的 APPID 内的 openID。否则会解析失败，字段长度为 64 字节
wechat_unionid	string	C	微信应用填写，微信数据源 wechat_openid 和 wechat_unionid 二者必选其一上报。微信 openid 是用户在公众号/小程序/小游戏下的唯一用户标识。例如：oWQ0O5MUpWG9P4WAZlhYUNTHwIj0。微信数据源 user_action_set_id 类型为WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME
wechat_app_id	string	C	微信应用填写，微信分配的 APPID。请填写所填的 wechat_openid 对应的 APPID。请确保您已经获得所填 APPID 的授权关联，否则将无法通过鉴权。当您填写 wechat_openid 时，此项必填。当您未填 wechat_openid，此项填写无效。请注意，当所填 user_action_set_id 的类型为{WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME}时，此字段必填，字段长度为 64 字节
caid	string	C	iOS设备填写，全称 CAA Advertising id，中国广告协会互联网广告标。通过采集 IOS 系统 12 个非隐私参数使用固定规则生成的设备指纹，由数字与小写字母组成的 32 位长度的字符串。上报 caid 时 caid_version 为必填项，建议上报最新的 caid 版本，例如：0a211fcbca0f336a891fc798c4db757d，字段长度为 64 字节
caid_version	integer	C	iOS设备填写，caid 版本编号。当前生效枚举值：[1005：中广协20220111；1006：中广协20230330]。建议上报最新的caid版本，完整枚举值
action_type	enum	Y	标准行为类型，见枚举值，当值为 'CUSTOM' 时表示自定义行为类型
external_action_id	string		用户自定义的行为 id 标识，最大值 255 字节
action_param	object		行为所带的参数，最大值 204800 字节
claim_type	integer		归因类型，腾讯平台会基于归因类型进行对应方式的归因，见枚举值
value	integer		订单价值，单位：分，100代表1元。体现转化带来的价值，一般在 action_type 为 COMPLETE_ORDER 或 PURCHASE 行为时选填
object	string		行为对象，例如 action_type 为 VIEW_CONTENT 时，object=product代表“商品页面浏览
length_of_stay	integer		停留时间，单位：天，例如action_type为START_APP作为留存行为时必填，length_of_stay=1，表示上报的是次日留存行为。枚举值：1、3、5、7，对应归因优化目标次日留存、移动app 3日留存、移动app 5日留存、移动app 7日留存
consult_type	string		咨询类型，见枚举值
trust	integer		反作弊过滤，广告主判定该转化行为，是否真实可靠。见枚举值；为空/不上报，与trust=0处理逻辑一致
custom_action	string		自定义行为类型，当 action_type=CUSTOM 时必填，最大值 128 字节
trace	object		跟踪信息
click_id	string		点击ID，user_id 与 click_id 二选一必填，广点通的click_id长度是20位数字+字母组合；微信的click_id长度是10-50，如wx0im5kwh44gh2yq，字段长度为 64 字节
url	string	C	网页应用填写，url，请填写效果数据发生 h5 页面 URL 地址，如datanexus.qq.com，最大值 2048 字节
product_inform	object		商品信息
content_type	enum		商品库行业。当您需要传输的商品信息为商品库行业标准类目时需要填写；如果传输的商品信息为商品 id，则无需填写。详见枚举值
product_catalog_id	string		商品库 id。您已经同步到腾讯的商品库所对应的商品库 id，当填了商品 id 时，必须填写商品库 id，字段长度为 64 字节
product_id	string[]		与行为相关的商品 id 列表。请填写商品库 id 内对应的商品 id，数组最大长度为 1000
category_path	string[]		与行为相关的类目名称列表。对于所需回传的每一个商品类目，请按照“一级类目名称/二级类目名称/三级类目名称/四级类目名称”的格式回传完整类目路径，数组最大长度为 16
channel	enum		渠道信息，标识该条行为发生在何渠道上，详见枚举值，转化归因场景中，填写TENCENT或留空时，数据进入转化归因
ext_info	object		拓展设备信息
package_name	string		app 安装包名称，长度最大 255 字节
app_version	string		app 安装包版本，长度最大 255 字节
mac	string		mac，长度最大 255 字节
device_brand	string		设备品牌，长度最大 255 字节
model	string		设备机型，长度最大 255 字节
os_version	string		操作系统版本，长度最大 255 字节
language	string		设备的系统语言，长度最大 255 字节
ip	string		设备 ip，需上报行为发生时的 ip，长度最大 255 字节
user_agent	string		设备 User-Agent 信息，长度最大 255 字节
wifi_name	string		设备使用 wifi 名称，长度最大 512 字节

信息

action_param是一个Map，key 类型为 string，value 的类型支持以下几种：

int 或 int[] : 64位整数；
float 或 float[]: 最大值100000000000 (一千亿)，保留3位小数精度，超过的截断，而非四舍五入；
boolean 或 boolean[]: 支持字面值为：true,false；
string 或 string[]: 字符串。

其类型约束在服务端控制，如果不满足约束，将返回对应的错误。

请求体示例

JAVA
Golang
Python
Nodejs
PHP

{
  "account_id": 1111111111,
  "user_action_set_id": 1111111111,
  "actions": [
    // 以下为 1 次请求的第 1 个行为：自然流量（"channel": "NATURAL")带来的自定义行为（CUSTOM）
    {
      "external_action_id": "示例唯一行为 id_请指定",
      "action_time": 1492998081,
      "user_id": {
        "hash_imei": "f9efca36a..."
      },
      "action_type": "CUSTOM",
      "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": [
          "家用电器/厨房小电/豆浆机",
          "本地生活旅游出行/旅游出行/机票火车票"
        ]
      },
      "channel": "NATURAL"
    },
    // 以下为 1 次请求的第 2 个行为：腾讯流量（"channel": "TENCENT"）带来的购买（PURCHASE）行为。1次请求最多上报50个行为，格式以此类推
    {
      "external_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"
    }
  ]
}

func main() {
    url := "https://api.e.qq.com/v1.3/user_actions/add?access_token=xxxxxxxx&timestamp=1679379053&nonce=xxxxxxxxxx"
    data := `{
  "account_id": 1111111111, //示例账户id
  "user_action_set_id": 1111111111, // 在DATANEXUS平台创建数据源ID
  "actions": [
      {
      "external_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"
    }
  ]}`
    payload := bytes.NewReader([]byte(data))
    req, _ := http.NewRequest(http.MethodPost, url, payload)
    req.Header.Add("content-type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        // handle error
    }
    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)
    fmt.Println(string(body))
}

import requests

url = "https://api.e.qq.com/v1.3/user_actions/add?access_token=xxxxxxxx&timestamp=1679379053&nonce=xxxxxxxxxx"
payload = {
  "account_id": 1111111111, //示例账户id
  "user_action_set_id": 1111111111, // 在DATANEXUS平台创建数据源ID
  "actions": [
    // 腾讯流量（"channel": "TENCENT"）带来的购买（PURCHASE）行为。1次请求最多上报50个行为，格式以此类推。
    {
      "external_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"
    }
  ]}
headers = {
    'content-type': "application/json",
    }
response = requests.request("POST", url, data=json.dumps(payload), headers=headers)
print(response.text)

const request = require("request");

let options = {
    method: 'POST',
    url: "https://api.e.qq.com/v1.3/user_actions/add?access_token=xxxxxxxx&timestamp=1679379053&nonce=xxxxxxxxxx",
    headers: { 'content-type': 'application/json' },
    body: {
  "account_id": 1111111111, //示例账户id
  "user_action_set_id": 1111111111, // 在DATANEXUS平台创建数据源ID
  "actions": [
    // 腾讯流量（"channel": "TENCENT"）带来的购买（PURCHASE）行为。1次请求最多上报50个行为，格式以此类推。
    {
      "external_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"
    }
  ]},    
      json: true
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://api.e.qq.com/v1.3/user_actions/add?access_token=xxxxxxxx&timestamp=1679379053&nonce=xxxxxxxxxx');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'content-type' => 'application/json'
));

$request->setBody('{
  "account_id": 1111111111, //示例账户id
  "user_action_set_id": 1111111111, // 在DATANEXUS平台创建数据源ID
  "actions": [
    // 腾讯流量（"channel": "TENCENT"）带来的购买（PURCHASE）行为。1次请求最多上报50个行为，格式以此类推。
    {
      "external_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"
    }
  ]}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

应答体结构

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

应答示例

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

FAQ

Q：自定义行为参数 custom_action 的填写要求？

A：自定义行为参数校验规则：需以字母开头，大小写均可，且只能包含大小写字母和数字，长度 99 以下。

Q：行为参数 action_param 怎么填写？

A：填写内容由行业根据应用情况约定，具体可查阅接入规范。

该内容是否有帮助？

请求地址​

所属权限​

请求方法​

请求参数​

请求体类型​

请求体参数​

请求体示例​

应答体结构​

应答示例​

FAQ​