附录3-API接入-用户行为上报

1. 用户行为上报API

1.1 接口介绍

1)用户行为上报请求格式

① HTTP Method:POST

② URL:https://nbrecsys.4paradigm.com/action/api/log?clientToken={注册账号的token}

③ Content-Type:application/json

④ Request Body:

  • 注意:用户行为单次上传不要超过100条
  • 举例:
{
    "date":"2019-04-09 11:58:57",
    "actions":[
        {
            "itemId":"12345678990",
            "actionTime":1554803592000,
            "action":"show",
            "itemSetId":"100",
            "sceneId":"101",
            "userId":"ceshiyonghu1",
            "requestId":"1122334455",
            "lib":"android",
            "deviceId":"41B2FD07-695A-4A27-8D26-C30ECE6F7EAD",
            "context":"dKZRv70cAir4/Y7ADmF/Ty2UQy4Pyf/QuOGAd0nx7D+NWes2WYs5sulnewqMFHn4YeUuUnMgdW/mHzMzILuxaYqMo+X"
        },
        {
            "itemId":"0987654321",
            "actionTime":1554803693000,
            "action":"detailPageShow",
            "itemSetId":"100",
            "sceneId":"101",
            "userId":"ceshiyonghu2",
            "requestId":"3456765432",
            "lib":"ios",
            "deviceId":"41B2FD07-695A-4A27-8D26-C30ECE6F7EAD",
            "context":"dKZRv70cAir4/Y7ADmF/Ty2UQy4Pyf/QuOGAd0nx7D+NWes2WYs5sulnewqMFHn4YeUuUnMgdW/mHzMzILuxaYqMo+X"
        }
    ]
}

2)用户行为上报返回格式

① Return-Type:application/json

② Return Body:

  • 举例:
{
    "statuses":[
        {
            "ActionLogStatusCode": 0
        },
        {
            "ActionLogStatusCode": 0
        }
    ]
}

1.2 Body字段介绍

1)用户行为上报请求Body

字段名称 字段类型 是否必传 释义 举例
date string 必传 用户行为日志发送的时间点,格式为“年-月-日 时:分:秒”。 2019-04-10 20:18:37
itemId string 必传 物料有且唯一的ID。 2834716231
actionTime long 必传 用户行为发生的时间点,UNIX时间戳格式,必须精确到毫秒。 1554803693000
action string 必传 用户行为。 show
itemSetId string 必传 物料库的ID。查找请见二、使用帮助 100
sceneId string 必传 场景的ID。查找请见二、使用帮助 101
userId string 必传 用户的ID。 11111111
context string 必传 推荐服务的标记。请求推荐服务时会获取每一条推荐结果的context,行为上报时把context原封不动回传即可。 dKZRv70cAir4/Y7ADmF/Ty2UQy
requestId string 非必传 推荐服务请求的ID。长度范围在8~18位的字符串,仅支持英文和数字。 1122334455
lib string 非必传 用户的终端的类型。包括android、ios。 ios
deviceId string 非必传 用户的终端的标识。安卓终端使用IMEI,苹果终端使用IDFA。 41B2FD07-695A-4A27-8D26-C30ECE6F7EAD

2)当前支持的用户行为

行为 是否必传 对应字段内容 什么时候上传该行为 备注
曝光/展现 必传 show 用户刷到这条物料的时候。 如无该行为,把其它合适的行为代为填充使用
点击 必传 detailPageShow 用户点击刷到的这条物料的时候。 如无该行为,把其它合适的行为代为填充使用
收藏 非必传 collect 用户收藏这条物料的时候。
关注 非必传 follow 用户关注这条物料的时候。
分享 非必传 share 用户分享这条物料的时候。
评论 非必传 comment 用户评论这条物料的时候。
赞/顶/喜欢 非必传 like 用户点赞这条物料的时候。
踩/不喜欢/不感兴趣 非必传 dislike 用户点踩这条物料的时候。
下载 非必传 download 用户下载这条物料的时候。
阅读/播放 非必传 duration 用户阅读/播放完这条物料离开的时候。

备注:对于 阅读/播放 行为,请配合下面2个字段进行使用,以使行为信息收集更加充分:

字段名称 字段类型 释义 举例
duration string 阅读时长/播放时长,精确到秒 15.6
duration_percentage string 阅读比例/播放比例,即某条视频的播放时长相较于视频总时长的比例,精确到小数点后2位,范围是0.00~1.00(超过1也可以,因为用户有可能重播了) 0.76

代码示例:

curl -X POST
        'https://nbrecsys.4paradigm.com/action/api/log?clientToken={您的商家token}'
        -H 'Content-Type: application/json'
        -d '{
              "date":"2018-08-19 11:58:57",
              "actions":[
                  {
                      "itemId": "123",
                      "actionTime": 1536215804000,
                      "action": "duration",
                      "duration": "15.6",
                      "duration_percentage": "0.77",
                      "itemSetId": "215",
                      "sceneId":"455",
                      "userId": "ceshiyonghu1",
                      "requestId": "1122334455",
                      "lib": "android",
                      "deviceId": "41B2FD07-695A-4A27-8D26-C30ECE6F7EAD",
                      "context":"dKZRv70cAir4/Y7ADmF/Ty2UQy4Pyf/QuOGAd0nx7D
                      +NWes2WYs5sulnewqMFHn4YeUuUnMgdW/mHzMzILuxaYqMo+X"
                  }
              ]
          }'

3)用户行为上报异常返回Body

字段名称 字段类型 释义 举例
code int 状态码 3201
info string 状态提示信息 token错误
data

4)code(状态码)字段介绍

状态码(code) 状态提示信息(info)
3201 token错误
3401 上传日志的时间错误,date属性异常或者不存在
3402 上传行为为空或者异常

如果URL参数都无误,针对每个用户行为的情况则返回如下:

{
    "statuses": [
        {
            "ActionLogStatusCode": 0
        },
        {
            "reason": [
                "error 'actionTime', too far away:1544195274000"
            ],
            "actionTime": "1544195274000",
            "error": {
                "msg": "action字段异常",
                "ActionLogStatusCode": 2
            },
            "userId": "b4a35d0e066b4b6eb798a360e6617042a6cc7194"
        }
    ]
}

ActionLogStatusCode为0则表示正常,如果出现error则表示这个用户行为异常。

1.3 代码示例

1)用户行为上报请求

curl -X POST
        'https://nbrecsys.4paradigm.com/action/api/log?clientToken=1qaz2wsx3edc'
        -H 'Content-Type: application/json'
        -d '{
              "date":"2019-04-10 11:58:57",
              "actions":[
                  {
                      "itemId": "123",
                      "actionTime": 1536215804000,
                      "action": "show",
                      "itemSetId": "215",
                      "sceneId":"455",
                      "userId": "ceshiyonghu1",
                      "requestId": "1122334455",
                      "lib": "android",
                      "deviceId": "41B2FD07-695A-4A27-8D26-C30ECE6F7EAD",
                      "context":"dKZRv70cAir4/Y7ADmF/Ty2UQy4Pyf/QuOGAd0nx7D
                      +NWes2WYs5sulnewqMFHn4YeUuUnMgdW/mHzMzILuxaYqMo+X"
                  },
                  {
                      "itemId": "123",
                      "actionTime": 1536215804000,
                      "action": "detailPageShow",
                      "itemSetId": "215",
                      "sceneId":"455",
                      "userId": "ceshiyonghu2",
                      "requestId": "3456765432",
                      "lib": "ios",
                      "deviceId": "41B2FD07-695A-4A27-8D26-C30ECE6F7EAD",
                      "context":"dKZRv70cAir4/Y7ADmF/Ty2UQy4Pyf/QuOGAd0nx7D
                      +NWes2WYs5sulnewqMFHn4YeUuUnMgdW/mHzMzILuxaYqMo+X"
                  }
              ]
          }'

2)用户行为上报返回

{
    "statuses":[
        {
            "ActionLogStatusCode": 0
        },
        {
            "ActionLogStatusCode": 0
        }
    ]
}
Copyright ©2017 4Paradigm All Rights Reserved            文件修订时间: 2019-10-09 11:23:23

results matching ""

    No results matching ""