电商业务上传数据接口

1.数据类别

电商数据包含有以下三种:用户行为数据、用户meta数据,商品meta数据(备注:其中用户行为、商品meta数据为必需);输入数据请遵循以下规范。

下面字段为可能收集的全部字段,如果应用方采集不到对应的数据信息,对应字段可以为空。

备注:Item ID是商品ID,商品meta数据、用户行为数据以及预测服务请求接口三者对同一商品物料的id必须保持一致。

2.数据样例

2.1.用户行为数据(Action)

{
 "common":{
 "logid":"18102949407735214587", //log全局唯一id,由客户自主生成,依据此标志去除重复请求数据,必填
 "timestamp":1489471203000, //发送时间戳,毫秒,int,必填
 "ip":"xxx.xxx.xxx.xxx" //发送端的ip,必填
 },
 "data" :
 {
 "he": // 报文头部
 {
 "o": // 操作系统类型 "Android" 和 "iOS",
 "s": // 操作系统 API Level,string "21"
 "sv": // 操作系统版本 Release,string,"4.2"
 "a": // App版本 int,42
 "n": // App版本 string,"4.0.0"
 "d": // Device Id,MAC 地址 
 "dd": // Android IMEI号 string
 "ad": // iOS IDFA string
 "w": // 宽度,int, 分辨率像素
 "h": // 高度,int, 分辨率像素
 "k": // app key,string, 标示token,全局唯一,需申请, 必填
 "c": // 发行渠道, string, "AppStore"
 "lang": // 系统语言,string, 参考系统标准API[1]
 "op": // 运营商,string
 "m": // 终端型号,string,"Le X620",Build.MODEL
 "ma":// 终端制造商,string,"LeMobile",Build.MANUFACTURER
 "cl": // 基站定位,string
 "gl": // gps 定位,string "时间戳|经度_纬度",经纬度为小数
 "wl": // wifi 定位, string ""
 "l": // 联网方式,"wifi","3G","4G"
 "t": // unix时间戳,毫秒,
 "z" : // 时区, string, 参考系统标准API[2]
 },
 "ev": // 自定义事件统计
 [
  {
   "i": // id,事件Id,必填,使用event名称
   "t": // timestamp,事件开始时间戳, 单位为毫秒
   "d": // duration,事件持续时间
   "ext":{
       "uid": // 用户id,
       "iid": // 物料id,
       "src":  //source, 用来区分物料item展示的位置信息,方便数据统计;例如:首页推荐、详情页推荐、用户中心推荐等
       "man": //manual_edit, 用来区分当前事件操作对象是否是人工运营的结果;
       "trace_id": //trace_id, 用来作为百度推荐结果的识别标记,用来关联推荐展现和点击行为;
       "sample_name": // sample_name, 用于后端优化效果,来源于预测接口中返回的sample_name
     }
  }, ...
 ]
 }
}

2.2.用户数据(用户meta数据)

{             
 "i": //user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID 
 "dd": // Android string IMEI,list
 "ad": //IOS string IDFA,list
 "n"://nickname,昵称
 "a":"32" //age,年龄
 "ag":  / /age group 年龄区间,25-30
 "g": “m” //gender,性别, male female
 "ma": “s” //marriage,婚姻状况, single,  married
 "job": “student” //jobs,职业情况
 "edu": “doctor” //education,教育背景
 "inc": 8000 //income,收入情况
 "desc": //用户描述信息
 "ba": 18.1//balance, 账户余额
 "co": 880//coin, 拥有商家的虚拟货币量(例如:x豆);
 "op": "add" //本条记录的操作类型,默认add。除了值为'del'表示删除,其他全部按add逻辑处理;
}

备注:一些和商品相关的基础的用户元数据信息,例如:购买商品列表、搜索商品列表、关注商品列表、评价商品列表以及购物车商品列表等信息,由于是动态变化的,就不在用户meta数据中记录,改为通过用户行为数据来进行统计。

2.3.物料数据(商品meta数据)

{             
"i": // id,商品ID
"ti": // title,商品标题信息
"desc"://description,商品描述信息,包括功能和相关参数
"add": //additional,商品附加信息,如:免运费,支持货到付款,七天退货等
"cats":[
{"cat_1": “手机通讯” //category_first,商品所属一级分类
 "cat_2": “手机” //category_second,商品所属二级分类;
 "cat_3": “apple” //category_third,商品所属三级分类;
},...
]
"pri": 5888 //price, 价格
"pt": //putaway time,上架时间,unix时间戳,毫秒
"store": //所属店铺,适合平台类电商
"area": //商品所属区域,适用于分区域销售策略存在差异的情况
"op": "add" //本条记录的操作类型,默认add。除了值为'del'表示删除,其他全部按add逻辑处理
}

备注:一些和用户相关的基础的商品元数据信息,例如:商品访问量、商品销量、商品评价数、商品好评率,由于是动态变化,就不在商品meta数据中记录,改为通过用户行为数据来进行统计。

3.用户行为数据格式

3.1.基础信息

该部分信息主要包含有设备和app自身基础信息。

Field Mandatory Type Description
o recommended string 操作系统
"Android" 和 "iOS"
s recommended string 操作系统API Level
sv recommended string 操作系统版本
i recommended string cuid
a recommended int APP版本号,23
n recommended string APP版本名,Android xxx
k recommended string 此APP的KEY
d recommended string Device ID,MAC地址"98:FE:94:50:2A:E8"
dd required string Android IMEI(备注:dd和ad字段至少存在其一)
ad required string iOS IDFA(备注:dd和ad字段至少存在其一)
w recommended int 屏幕分辨率宽度
h recommended int 屏幕分辨率高度
c recommended string APP分发渠道
lang recommended string 操作系统语言
op recommended string 网络运营商,"46000"
m recommended string 终端型号,"Le X620",Build.MODEL
ma recommended string 终端制造商,"LeMobile",Build.MANUFACTURER
cl recommended string 基站地位 "0_0_0"
gl recommended string GPS定位,"时间戳/经度_维度",经纬度为小数
wl recommended string WIFI定位
l recommended string 联网方式NETWORK_TYPE,"WIFI","4G"等
t recommended int Unix时间戳,毫秒
z recommended string 时区

3.2.事件信息

事件写入ev中,包含事件本身类型、时间信息以及其他自定义字段。

Field Mandatory Type Description
i required string action id,事件id,用来标识区分事件,其具体值参见下面的表格。
t required int Unix时间戳,毫秒
d required int duration,事件时长,秒
序号 Event Description
1 impression 浏览(商品展现曝光)
2 click 点击(进入商品详情页)
3 search 搜索
4 search_click 搜索点击
5 collect 收藏(关注)
6 cart 购物车操作
7 buy 下单购买
8 evaluate 评价
9 share 分享

ev中的ext字段详见后续小节。

3.2.1.浏览(曝光)

i为impression,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.2.点击

i为click, 以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID
iid required string item_id,商品ID
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0;
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0;
1-人工运营的结果。
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.3.搜索

i为search,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
q required string query,用户查询词,"iphone8"
iids optional list search item id list,搜索结果中的商品id列表
t optional string type,搜索类型,取值有:
active - 主动搜索
hotword - 热门搜索
sug - 搜索提示
history - 搜索历史
other - 其他
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.4.搜索点击

i为search_click,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,点击商品ID
q required string query,用户查询词,"iphone8"
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.5.收藏(关注)

i为collect,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
a required string action, 收藏(关注)操作,取值有:
cancel - 取消收藏(关注)
collect - 收藏(关注)
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据 trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.6.购物车操作

i为cart,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
a required string action, 购物车操作,取值有:
in- 加入购物车
out- 移出购物车
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.7.购买(下单)

i为buy,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
src ptional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.8.评价

i为evaluate,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
a required string action, 评价动作,取值有:
score - 打分
view - 看评价
write - 写评价
reply - 回复评价
like - 点赞评价
unlike-踩评价
s required float score, 用户对商品的评价得分
c optional string content, 评价内容
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

3.2.9.分享

i为share,以下填入ext字段中。

Field Mandatory Type Description
uid required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID。
iid required string item_id,商品ID
ch recommended string channel分享渠道,取值有:
wechat - 微信
moments - 朋友圈
qzone - QQ空间
weibo - 新浪微博
qq - QQ
mail - 邮件
sms - 短信
link - 复制链接
unknown - 未知
src optional int 用来区分app不同场景位置的推荐结果用户行为,默认值为0。
例如:
0- 首页推荐;
1- 详情页推荐;
2- 用户中心推荐。
man optional int 用来区分是否是人工运营结果上的推荐结果用户行为(适用于存在人工运营推荐结果和策略自动产出推荐结果合并的情况),默认值为0。
1-人工运营的结果;
0-非人工运营结果。
trace_id optional string 若不传无法在console上看统计报表中相关统计数据。
trace_id,标示了属于百度推荐系统的推荐结果,用于关联从预测服务中获取的推荐结果,可以从response_body中获得。
备注:分为两种情况:
1. 客户内部可以生成用于关联每次推荐请求和结果的展现点击等行为的id,则将其透传即可,推荐服务会在返回结果中复用该id值并以trace_id的形式返回;
2. 客户内部不生成该id,则推荐服务会在内部生成该trace_id,并在返回结果中回传给客户端,以供客户端使用;
客户需要在内部有一套机制,保证对同一次请求获得的Item推荐结果后续在展现和点击行为匹配的一致性,并在用户行为数据中使用对应的固定trace_id进行返回;以便服务端进行推荐效果数据统计、小流量实验分层效果统计等。
sample_name optional string 后端进行效果优化迭代时的必须字段,该字段来自于预测服务返回结果中的sample_name。

4.用户meta数据格式

Field Mandatory Type Description
i required string user_id,用户ID,用户唯一标识,登录用户需要和物料库一致,未登录用户UUID
dd required list Android IMEI(备注:dd和ad字段至少存在其一)
ad required list IOS IDFA(备注:dd和ad字段至少存在其一)
n recommended string nickname,昵称
a recommended int age,年龄
ag recommended string age group,年龄区间, 25-30
g recommended string gender,性别,"m" 代表 male,"f"代表female,"u"代表unknow
ma recommended string marriage, 婚姻状况, 包括:single, married, unknown
job recommended string jobs,职业情况,例如:student, teacher, lawyer, official, worker
edu recommended string education, 教育背景,包括:master, doctor,bachelor
inc recommended int income, 收入情况
desc recommended string 用户描述信息
ba recommended float balance,账户余额
co recommended int coin,拥有平台虚拟货币数量(例如:X币, X豆)
op optional string operation type,操作类型,本条记录的操作类型,默认add。除了值为'del'表示删除,其他全部按add逻辑处理

备注:一些和商品相关的基础的用户元数据信息,例如:购买商品列表、搜索商品列表、关注商品列表、评价商品列表以及购物车商品列表等信息,由于是动态的,就不在用户meta数据中记录,改为通过用户行为数据来统计。

5.商品meta数据格式

Field Mandatory Type Description
i required string id,商品ID
ti required string title,商品标题信息
desc recommended string description,商品描述信息,包括功能和相关参数
add recommended string additional,商品附加信息,如:免运费,支持货到付款,七天退货等
cats recommended List 商品所属分类体系,单个商品可以属于多个分类,但是每个分类下的一级、二级、三级子类必须要对应起来
pri required float price, 价格
pt required int putaway time,上架时间,unix时间戳,毫秒
store optional string 所属店铺,适合平台类电商
area optional string 商品所属区域,适用于分区域销售策略存在差异的情况
op optional string operation type, 操作类型,本条记录的操作类型,默认add。除了值为'del'表示删除,其他全部按add逻辑处理;可以用来做撤稿操作;

Category对象说明如下:

Field Mandatory Type Description
cat_1 recommended string category_first,商品所属一级分类,例如:手机通讯
cat_2 recommended string category_second,商品所属二级分类,例如:手机
cat_3 recommended string category_third,商品所属三级分类,例如:apple

备注:一些和用户相关的基础的商品元数据信息,例如:商品访问量、商品销量、商品评价数、商品好评率,由于是动态变化,就不在商品meta数据中记录,改为通过用户行为数据来进行统计。

6.说明

编码问题:建议传输数据中所有的string字段统一使用utf-8编码。

附录1:系统参数获取标准API

1.1.系统语言获取方式

备注:以Java语言为例。

private boolean isZh() {
        Locale locale = getResources().getConfiguration().locale;
        String language =** locale.getLanguage()**;
        if (language.endsWith("zh"))
            return true;
        else
            return false;
    }

1.2.时区的获取方式

备注:以Java语言为例。

TimeZone tz = TimeZone.getDefault();

String s = "TimeZone "+ **tz.getDisplayName** (false, TimeZone.SHORT)+" Timezon id :: " +tz.getID();  
System.out.println(s);