user_id

string

必选

用户id，不能包含中文

user_id唯一标识一个用户，作用：
1）产出样本时，用作Key去关联行为数据和用户数据，拼接用户侧特征
2）归因行为数据时，用作归因的聚合key之一
3）在线服务流环节中的个性化召回中，用作key去维护候选召回池

age

string

强烈建议

用户年龄或者年龄段

用作特征

city

string

强烈建议

用户城市

用作特征

gender

string

强烈建议

用户性别，例如：1：男性 2：女性 3：未知

用作特征

register_time

int32

强烈建议

用户注册时间戳，精确到秒，如1622476800

用作特征

tags

string

强烈建议

用户标签，多个标签使用$##$分隔，如“标签1$##$标签2$##$标签3”

用作特征

update_time

int32

强烈建议

用户信息更新时间戳，精确到秒，如1622476800

提供精确的字段更新时间，平台会根据此字段来判断是否做字段更新，如果该字段不准确则可能导致无法更新；如无法提供精确的更新时间，建议此字段传空。

area

string

建议

用户所在商圈

用作特征

client_version

string

建议

客户端版本

用作特征

country

string

建议

用户国家

用作特征

device_id

string

建议

设备标识

device_model

string

建议

设备型号，如HONER

用作特征

district

string

建议

用户所在区县

用作特征

id_type

string

建议

id类型，手机/邮箱/微信 等

用作特征

language

string

建议

用户语言

用作特征

membership_level

string

建议

用户会员等级

用作特征

network

string

建议

网络类型，5G/WIFI

用作特征

os

string

建议

操作系统，如IOS，Android

用作特征

os_version

string

建议

设备操作系统版本

用作特征

platform

string

建议

平台，如APP，WAP，H5

用作特征

province

string

建议

用户省份

用作特征

subscriber_type

string

建议

订阅类型

用作特征

user_type

int32

建议

用户类型，例如：1：登陆用户 2：访客

用作特征

goods_id

string

必选

商品id

goods_id唯一标识一个商品，作用：
1）产出样本时，用作Key去关联行为数据和商品数据，拼接商品侧特征
2）归因行为数据时，用作归因的聚合key之一

status

int32

必选

可推荐状态，0：不可推荐，1：可推荐

1）status=0的商品不会在推荐结果中出现
2）需要下架商品时，把status的值修改为0即可，若商品表是实时同步，生效周期为分钟级。当商品上下架频繁时，建议实时同步商品更新信息

brand

string

强烈建议

商品品牌。推荐全部传输品牌id，也可全部传输品牌明文。

1）用作特征
2）服务流会用到该字段进行召回过滤/规则打散

cate

string

强烈建议

商品不同级类目之间用$##$分隔，且自左向右类目层级逐渐细化。类目值推荐全部传名称，举例如“家电$##$电视$##$OLED电视”。某一段为空时直接传空字符串，如第二段为空， 则传“家电$##$$##$OLED电视”。

1）用作特征
2）服务流会用到该字段进行召回过滤/规则打散

cate_cnt

int32

强烈建议

商品类目层级数。cate_cnt必须等于len(cate.split('$##$'))，用于校验cate数据。所有商品的分类体系应该一致，即对于所有商品来说，cate_cnt应该相同。（此字段即将弃用，不建议使用）

current_price

float

强烈建议

商品现价

1）用作特征
2）服务流会用到该字段进行召回过滤
3）如果优化指标是GMV，商品现价必须要传

pub_time

int32

强烈建议

商品发布时间戳，精确到秒，如1622476800

有时效性要求时必填，用于新品的推荐策略

spu_id

string

强烈建议

spu维度的id

用作特征

tags

string

强烈建议

商品标签，如首页展示标签“特惠”，“热卖”,或详情页“满50包邮”,“假一赔三”等。多值示例：“特惠$##$热卖"

用作特征

title

string

强烈建议

商品标题

用作特征

update_time

int32

强烈建议

商品信息更新时间戳，精确到秒，如1622476800

提供精确的字段更新时间，平台会根据此字段来判断是否做字段更新，如果该字段不准确则可能导致无法更新；如无法提供精确的更新时间，建议此字段传空。

comment_cnt

int32

建议

商品累计评论次数

用作特征

description

string

建议

商品描述

用作特征

detail_pic_num

int32

建议

商品图片数量

用作特征

free_shipping

string

建议

商品是否包邮，如 1：包邮 2：不包邮 3：满足条件包邮

用作特征

origin_price

float

建议

商品原价/划线价

用作特征

pic_url

string

建议

商品封面图url

用作特征

praise_cnt

int32

建议

商品累计点赞次数

用作特征

rating

string

建议

商品评分

用作特征

region

array

建议

商品可售区域，API传输要用json序列化的string，如"["a","b","c",...]"

用作特征

sale_number

int32

建议

商品累计销量

用作特征

share_cnt

int32

建议

商品累计分享次数

用作特征

shipping_money

float

建议

商品运费

用作特征

shop_id

string

建议

商品所属店铺id（如有）

用作特征

source_id

string

建议

商品来源类型，如自营/第三方(如有)

用作特征

bhv_time

int32

必选

行为发生时间戳，以秒为单位的unix timestamp，如1622476800，需要在当天时间分区内

作用：
1）行为数据归因时，需要根据bhv_time来对行为排序，从而判断行为发生的先后顺序
2）挖掘用户行为序列特征时，需要将特征列表按bhv_time排序
影响：bhv_time需要传准确的值，否则会影响归因的结果和特征的质量，对推荐效果折损较大。

bhv_type

string

必选

行为类型。不同行为的bhv_type值可以自定义。
平台内置行为类型如下：[曝光：exposure]，[点击： click]，[购买成功：conversion]，[收藏：favorite]，[加购物车： cart]，[搜索：search]，[点击购物车：click_cart]，[立即购买：check]，[分享：share]，[下单：order]，[不喜欢：dislike]。

1）不同优化目标强依赖于相应bhv_type的行为，比如优化目标为点击率，那么点击行为必传；若优化目标为转化率，那么点击和转化行为必传
2）挖掘用户特征，传的行为类型越多，平台挖掘的用户特征越多，推荐效果越好
3）用作消重和规则系统

goods_id

string

必选

商品id。用户行为和具体商品相关时此字段必传（如点击），用户行为和具体商品不相关时此字段留空（如搜索，或点击进入分类页）。

需要与商品表中的goods_id相匹配

scm

string

必选

scm主要用于标识行为产生自哪个合作方。如字节推荐接口返回的候选产生行为，scm可传bytedance，其他可传google、other等等。如无法区分其他合作方，历史数据中可传other，需要保证上线后字节推荐接口返回的候选产生的行为scm都传bytedance。

用于统计不同来源算法的效果

spm

string

必选

SPM(Super Position Model)全称超级位置模型，主要用于标识行为发生的位置。SPM位置编码由A/B/C/D四段构成，各分段分别代表 A:业务， B:页面， C:页面区块， D:区块内点位。段之间用$##$分隔，即A$##$B$##$C$##$D，spm各段建议传明文。某一段为空时直接传空字符串，如第二段为空， 则传“A$##$$##$C$##$D”。
1.业务：业务名称，如今日头条
2.页面：如首页、发现页-推荐等
3.页面区块：如广告位、猜你喜欢
4.区块内点位：在区块内的具体位置

1）归因的时候用作归因依据
2）当传多场景行为数据时，需要spm作为特征刻画不同场景用户行为分布的差异
3）服务流会用到该字段进行召回过滤
4）统计效果/数据校验按照spm统计单场景效果

user_id

string

必选

用户id

登录用户需要与用户表中user_id一致；未登录用户建议使用device_id/imei填充user_id

parent_goods_id

string

强烈建议

相关推荐场景点击进入详情页的商品id

在相关推荐场景中，该字段用来注明行为发生于哪个商品的详情页中。 1）用作特征 2）召回

query

string

强烈建议

搜索query，在搜索行为或搜索结果页行为中传输

在搜索场景中用作特征

request_id

string

强烈建议

请求推荐接口时的request_id

1）便于排查问题
2）后续平台支持request_id作为归因key

area

string

建议

用户发生行为的商圈

用作特征

city

string

建议

用户发生行为的城市

用作特征

client_version

string

建议

客户端版本

用作特征

country

string

建议

用户发生行为的国家

用作特征

device_model

string

建议

设备型号

用作特征

dislike_type

string

建议

负反馈规则的维度。需要用到负反馈规则时，必须勾选并传输。例如，若不喜欢此商品，需同时过滤同一品牌的其他商品，则传输brand。需要用到多个属性做负反馈时，dislike行为分别传输多个dislike_type和dislike_value。 注意：1）当前goods_id不需要再填充到dislike_type，可直接用于负反馈规则；2）dislike_type必须为商品表中的字段，包括：brand, cate, tags, spu_id, shop_id以及自定义字段；3）使用cate字段过滤时，必须指定到某一级，即：cate_1, cate_2...以此类推。

和dislike_value一起，作为负反馈规则的条件

dislike_value

string

建议

负反馈规则的维度值，即dislike_type字段对应的字段值。需要用到负反馈规则时，必须勾选。例如，若不喜欢此商品，需同时过滤同一品牌的其他商品，则传输brand的值。若此字段不传，则默认使用当前goods对应的属性值过滤。 注意：1）使用tags字段过滤时，可以传输多个值（以$##$分隔），触发其中任意值的都视作触发负反馈规则；2）使用cate字段过滤时，传输dislike_type指定cate级别的值。

和dislike_type一起，作为负反馈规则的条件

district

string

建议

用户发生行为的区县

用作特征

ipv4

string

建议

ipv4地址

用作特征

ipv6

string

建议

ipv6地址

用作特征

item_num

int32

建议

订单内该商品的购买数量（例如一笔订单内买了10包抽纸），一般只有下单/支付行为携带该字段

若一条转化中购买了多个商品，需要将转化行为copy item_num份，生成item_num个转化样本。

network

string

建议

网络类型

用作特征

order_id

string

建议

订单id，一般只有下单/支付行为携带该字段

用于统计效果数据（订单数，gmv指标）、或者归因层面标注conversion数据是否重复

os

string

建议

操作系统，如IOS，Android

用作特征

os_version

string

建议

设备操作系统版本

用作特征

pay_amount

float

建议

订单的实际(待)支付金额，一般只有下单/支付行为携带该字段

用于效果指标统计，更准确且更便捷

platform

string

建议

平台，如APP，WAP，H5

用作特征

province

string

建议

用户发生行为的省份

用作特征

spu_id

string

建议

商品所属的spu_id

常用于归因使用，通常conversion_to_click时，会使用spu_id归因，而非goods_id（sku_id）。在行为中直接携带后就无需关联商品表了。

trace_id

string

建议

trace_id用于将用户的连续行为关联起来，例如用户曝光了某商品，并点击、收藏和购买了该商品，那么这一系列的行为可以用trace_id进行关联，将点击、收藏和购买事件归因到对应的曝光事件。此字段由客户侧生成。

后续平台支持trace_id用于归因

trans_data

string

建议

trans_data是个性化推荐请求api返回结果中所携带的transData字段（详细作用可见api文档），用于追踪商品相关的所有行为，进行深入分析，提升推荐效果。

便于平台帮助客户分析优化点

exposure

曝光

强烈建议传输

click

点击

强烈建议传输

conversion

购买成功

• 订单提交并支付成功行为，即完全转化
• conversion行为建议传pay_amount、order_id字段
• 如一次购买多件商品，请通过多个conversion事件进行传输

favorite

收藏

cart

加购物车

search

搜索

• 点击搜索按钮这个行为，bhv_type是search，这时候必填搜索的query，goods相关字段不填
• 搜索结果页的点击、收藏和购买等行为，bhv_type是click/cart/conversion，通过spm标识来自搜索场景。

click_cart

点击购物车

check

详情页立即购买

点击“立即购买”的行为

share

分享

order

下单

• 提交订单（即建单）或者到了提交订单页面的行为
• order行为建议传order_id字段

dislike

不喜欢