You need to enable JavaScript to run this app.
导航
电商行业数据模板
最近更新时间:2023.10.18 20:09:21首次发布时间:2021.06.08 18:58:58

对于电商行业的客户,接入智能推荐平台需要准备 3 张数据表,具体字段需求参见下文“数据字段说明”:
用户表(user)
建议上传前做去重处理。user_id为用户唯一标识。
物品表(item)
此处指商品(goods),建议上传前做去重处理。goods_id为商品唯一标识。
行为表(behavior)
测试数据建议提供1-2周的数据,历史数据建议提供3个月以上数据,可同步的时间越长,效果往往会越好。

数据字段说明

字段规范:

  • 字段类型:原始字段类型,与新建项目“表定义”中模板字段类型一致。
  • 字段等级:字段等级按字段需求程度分为必选、强烈建议和建议,必选字段在表定义时必须勾选。
  • 描述:该字段的具体含义。
  • 字段作用:该字段在推荐流程当中的作用。

说明

建议尽可能多传字段,数据越丰富,预期推荐效果越好。

API传输数据类型规范:

  • string、float、int 类型数据传输时使用原类型传即可。
  • bool类型的字段需要在平台上定义为int传输。
  • array类型需要用json string传输,如array类型的[1,2,3,4]需要传入json string的"[1,2,3,4]";array类型的["a","b","c","d"]需要传入json string的"[\"a\",\"b\",\"c\",\"d\"]";不要有 control characters ('\t', '\n', '\r', '\0'等)。

注意

API对字段的校验规则:

  1. 必传校验。以下字段如果不传,会拒绝整条数据,包括:
  • 用户表:user_id
  • 物品表:goods_id、status
  • 行为表:bhv_time、bhv_type、user_id、spm、scm
  1. 字段类型校验。
  • 必传字段强校验,数值类型传string会cast,无法cast的话会拒绝整条数据。
  • 非必传但schema中定义的字段,数值类型传string也会cast,无法cast的话会拒绝整条数据。
  • 未在schema中定义的字段,不做类型校验。

如果因为类型校验失败,api会返回1001状态码,且在返回结果的errors字段中会有错误数据例子和错误原因说明。

用户表

字段名称

字段类型

字段等级

描述

字段作用

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文档),用于追踪商品相关的所有行为,进行深入分析,提升推荐效果。

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

行为类型说明

电商行业支持以下11种模板行为,如需更多行为,可进行自定义,详见数据表定义

bhv_type

行为名称

说明

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

不喜欢