You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
生态与合作
支持与服务
开发者
了解我们
导航

HTTP API(私有化查看)

最近更新时间2023.05.12 19:03:01

首次发布时间2022.05.26 17:07:40

1.请求接口

单条数据上传:

  • Path: https://${host}/v2/event/json
  • Method: POST

多条数据上传(每次最多20条):

  • Path: https://${host}/v2/event/list
  • Method: POST

${host}:私有化部署客户为埋点数据上报申请的域名,请根据实际的域名进行替换,客户域名更新后也需要同步更新上报的路径地址。

2.请求规范

(1) 请求的header里带"Content-Type: application/json",以及“X-MCS-AppKey”,作为app的标识;
(2) 请求的body包含user,header,event三个部分,其中的header是埋点数据本身的header;
(3) 单次上传events数控制在20条以内,超过50条会报413;
(4) 上传如采用/v2/event/list接口,json数目控制在20条以内,超过50条会报413。

2.1 请求header

字段类型说明
Content-Typestringapplication/json
X-MCS-AppKeystring您应用的APP Key

APP Key的获取位置请参考以下截图

2.2 请求body

userobjectuser属性字典,详见 2.3
headerobjectheader属性字典,详见 2.4
events[object]events列表,每个元素为一个事件,详见 2.5

2.3 user格式

字段类型必选说明
user_unique_idstring用户的唯一身份标识,需要保证同一个用户在本应用内全局唯一,即需要与客户端上报一致
device_idstringapp端设备标识,注意必须为纯数字
web_idstringweb端设备标识,注意必须为纯数字

2.4 header格式

字段类型必选说明
app_namestring应用的英文名称
app_packagestring包名
app_channelstringapp分发渠道
app_versionstringapp版本,三段分隔,如1.0.1
app_platformstring应用的端,不支持自定义修改
platformstring平台类型
os_namestring客户端系统,只允许设置为 "ios", "android", "web", "wap", "mac", "windows", "linux", "ipad", "iphone", 其他的值会解析成unknown
os_versionstring客户端系统版本号
device_modelstring设备型号
ab_sdk_versionstringab实验分组信息
traffic_typestring流量类型
client_ipstring客户端ip
customjson object自定义header字段,单层json map。上述字段都是保留字段不能使用。自定义事件公共属性放在这,会显示在any_event事件下
regionstring所在区域国家(系统设置),us等,(放在custom中)
languagestring语言(系统设置),en等,(放在custom中)
app_regionstring国家(app设置),us等,(放在custom中)
app_languagestring语言(app设置),en等,(放在custom中)
timezonestring时区,-12~12,(放在custom中)
utm_sourcestring推广来源
utm_campaignstring推广活动
utm_mediumstring推广媒介
utm_contentstring推广内容
utm_termstring推广关键词

2.5 event格式

字段类型必选说明
eventstring事件名
paramsstring事件参数,单层json map
local_time_mslongunix_timestamp( 毫秒)
3.HTTP Response 格式

HTTP 状态码

状态码返回信息含义

200

{"message":"success", "sc": num}
num为成功条数

成功,返回成功event数,失败的查看events上报格式,全部错误则返回num=0

400

header/user/events empty error.
get/invalid appid error.
no appkey and no appid error.

请求格式错误, 查看X-MCS-AppKey与header,user的定义

400

too many elements in one request!
too many events error.

单个请求事件数过多,或请求json数组元素过多(只针对list接口)

4.请求示例

4.1 /v2/event/json接口

curl -X POST -H "Content-Type: application/json" -H "X-MCS-AppKey: 12345678key" -d '{"user": {...}, "header":{...}, "events":{...}}' https://mcs.ctobsnssdk.com/v2/event/list

请求body:

{
    "user": {
            // 建议先在客户端上报用户的user_unique_id,然后再在服务端使用
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app",
        "custom":"{\"A\":\"a\"}"         //事件公共属性
    },
    "events": [
        {
            "ab_sdk_version": "91223,83097",   //AB实验vid
            "event": "test_go_detail",    //事件名称
            "params": "{\"paramName\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生时刻的时间戳
        }
    ]
}

字段说明:

local_time_ms : 这个是毫秒时间戳,标识这个事件发生的时刻

4.2 /v2/event/list接口

curl -X POST -H "Content-Type: application/json" -H "X-MCS-AppKey: 12345678key" -d '[{"user": {...}, "header":{...}, "events":{...}}]  https://mcs.ctobsnssdk.com/v2/event/list

请求body:

[{
    "user": {
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app"
    },
    "events": [
        {
            "event": "test_go_detail",    //事件名称
            "params": "{\"paramName\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生时刻的时间戳
        }
    ]
}]

字段说明:

local_time_ms : 这个是毫秒时间戳,标识这个事件发生的时刻

5.上报用户属性

用户属性是通过特殊的事件进行上报,通过设置下面几个event可以修改用户属性:

事件名功能
__profile_set设置用户属性
__profile_set_once设置用户属性,属性为set_once,设置后不可更改
__profile_increment增加数值类用户属性的值
__profile_unset删除用户属性
__profile_append增加数组类用户属性的元素
__profile_remove删除数组类用户属性里的元素

5.1 上报用户属性

用户属性放在params
示例请求,作用为设置一个用户属性age,删除一个用户属性name,body:

{
    "user": {
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app"
    },
    "events": [
        {
            "event": "__profile_set",    //操作名
            "params": "{\"age\": 10}",    //设置属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        },
        {
            "event": "__profile_unset",    //操作名
            "params": "{\"name\":\"tom\"}",    //设置属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}

5.2 验证上报的用户属性

可以在行为细查页面中查看特定用户的数据,如果是大量数据,可以在事件分析中对用户属性进行分析。

6.上报业务对象属性

6.1 创建业务对象

创建业务对象之后需要等待5-10分钟之后再上报;
每个应用目前最多可创建10个业务对象;每个业务对象最多可创建50个属性;

需要先创建业务对象,在 “数据管理” --> “业务对象”下创建。
业务对象内置的id属性,对应的字段名称为item_id,因此不需要再定义一个 id 属性。
业务对象属性是通过特殊的事件进行上报,通过设置下面几个event可以修改业务对象属性:

事件名功能
__item_set设置业务对象属性
__item_unset删除业务对象属性

业务对象属性放在params中,并且需要有item_name和item_id来标识唯一业务对象。
示例请求body:

{
    "user": {
            "user_unique_id": "__rangers"   // 业务对象上报,固定为__rangers
    },
    "header": {
        "app_name": "news_article"//App名称
    },
    "events": [
        {
            "event": "__item_set",    //操作名
            "params": "{\"item_name\":\"phone\",\"item_id\":\"1\",\"price\": 1000}",    //设置属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}

6.2 上报关联事件

创建好的 item 对象需要与事件关联才可以使用。关联就是将某一个或多个具体业务对象的 id 值作为上报到事件的预置属性params.__item当中的过程。
下列示例代码演示了将 sku 和 order 两个创建好的业务对象与事件 new_order 进行关联的方式。__items 为事件预置属性,仅用于上报业务对象;
示例如下:

...
"event": "new_order",
"params": {
    "__items": "[{\"sku\":[{\"id\":\"sku_id_1\"},{\"id\":\"sku_id_2\"}]},{\"order\":[{\"id\":\"order_id_here\"}]}]",
    ...
},
...

__item 是转为 stringjson 对象,其格式为:

[
    {"item_name_1": [
        {"id": "id_value_1"},
        {"id": "id_value_2"},
        ...
    ]},
    {"item_name_2": [
        {"id": "id_value_1"},
        {"id": "id_value_2"},
        ...
    ]}
]

item_name_1 就是在上一步中定义的业务对象名称。如果这里关联的业务对象名称没有被定义过,那么相应的数据就会被抛掉,不会入库。如果 id 值没有找到对应的业务对象,也同样会被抛掉,不会入库,无法使用。

7.导入历史数据

如果数据的客户端时间超过七天,正常情况下无法导入,如需导入7天前历史数据,需在header中增加历史数据的标识 __is_history;如下:

[{
   "user": {
       "user_unique_id": "74481585297"   //用户唯一标示
   },
   "header": {

       "custom": {
              "__is_history": "true" //导入历史数据标识,默认为false;
       }
   },
   "events": [
       {
           "event": "test_go_detail",    //事件名称
           "params": "{\"paramName\":\"a\"}",    //事件属性
           "local_time_ms": 1489573628001   //事件发生时刻的时间戳
       }
   ]
}]

字段说明:

local_time_ms : 这个是毫秒时间戳,标识这个事件发生的时刻,注意不是导数的时间
上报完成后,需要在界面上点击刷新数据,即可以查询到上报的历史数据。

8.上报数据限制

请参考文档:

9.验证数据上报成功

方式1 : 可以在“高级分析”--> “自定义SQL”里直接查询
方式2: 如果知道特定的user_unique_id,可以在行为细查里查询
方式3: 可以在事件分析页面进行查询分析

10.常见问题

如果有服务端上报设备 id 的需求,需要上传device_id。

[{
    "user": {
        "user_unique_id": "123456",
        "device_id":"691295821177554113"
    },
    "header": {

    },
    "events": [
        {
            "event": "test_go_detail",    //事件名称
            "params": "{\"paramName\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}]