通用规范
不管选择何种方式接入数据,为了满足当前场景的数据应用要求,需按照以下规范上报用户实体数据。
1 用户 ID
其中,用户ID在 Android APP、iOS APP、微信应用(小程序、小游戏、公众号)、web应用、线下等端,识别用户的设备号或用户id不同,因此不同端有不同的合法ID类型。具体如下。
信息分类 | 数据源类型 | 合法ID类型 |
---|---|---|
用户ID | Android应用 | imei、oaid、android_id、手机号、click_id |
用户ID | iOS应用 | caid(推荐)、idfa(iOS 14版本及以上,不建议上报)、手机号 |
用户ID | 微信应用 | openid、unionid、clickid |
用户ID | web应用 | imei、oaid、android_id、手机号、click_id、idfa、caid、openid、unionid |
用户ID | 线下 | imei、oaid、android_id、手机号、click_id、idfa、caid、openid、unionid |
2 公共信息
用户实体基础信息结构如下。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
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' 时表示自定义行为类型 |
outer_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 | 商品库行业。当您需要传输的商品信息为商品库行业标准类目时需要填写,详见 枚举值 | |
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 字节 |
3 行业规范
针对 2 中的 action_type
和 action_param
做了进一步规范的行业如下。
金融 - 保险、金融 - 券商、金融 - 投顾、金融 - 银行、金融 - 贷款、金融 - 期货、金融 - 财商、金融 - 基金
FAQ
Q:为什么在 DataNexus 上传了文件,如翼里还是没有人群包?
A:在 DataNexus 上传及分发文件之后,需要返回如翼「创建人群」页面,选中上传的文件再生成人群包。整体人群创建流程为:在 DataNexus 上传文件并分发到腾讯广告如翼→返回如翼创建人群→计算成功后即可使用。
Q:DataNexus 上传文件后,返回如翼创建人群没找到对应文件?
A:首先确认如翼创建人群所选的数据类型,是否和 DataNexus 文件上传的一致;其次确认 DataNexus 上传的文件是否有分发给腾讯广告如翼,且分发开关是开启状态。如何确认文件分发情况,请见 资产分发 。
Q:使用 DataNexus 上传的文件创建人群包,提示格式错误?
A:首先,在 DataNexus 上传人群文件,建议上传单列文件;若上传的是多列文件,建议下载上传页面-接入文档中的.csv模板,填写数据后保存再上传,避免出现解析错误。
其次,确认填写的 ID 是否和所选的数据类型是一致的,例如上传时选择的ID类型是“手机号-MD5”,文件中的 ID 一列也必须填写 MD5 加密过的手机号。
Q:只有 ID 信息,人群文件的模板怎么填?
A:如果只是上传文件用于「如翼」人群创建,可直接在上传页面选择「单列文件」上传,一行一个号码,支持 .txt 或 .csv (UTF-8编码)格式文档。