You need to enable JavaScript to run this app.
导航
API
最近更新时间:2023.06.28 11:20:45首次发布时间:2021.07.05 21:23:10
概述

本文档主要介绍服务端API数据埋点的集成和使用方法

HTTP API

集成方案详见:HTTP API接入,不需要进行签名鉴权,按照接口规范直接调用url上报即可。

说明:服务端上报的http接口增长分析平台为您默认开通,如果您接入的应用没有开通,请联系产品解决方案同学支持。

1.请求接口

单条数据上传:

  • Path: https://mcs.ctobsnssdk.com/v2/event/json

  • Method: POST

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

  • Path: https://mcs.ctobsnssdk.com/v2/event/list

  • Method: POST

2.请求规范

(1) 请求的header里带"Content-Type: application/json",以及“X-MCS-AppKey”,作为app的标识;

(2) 请求的body包含user,header,events三个部分,其中的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

说明

获取X-MCS-AppKey:登录内容管理平台-「高级管理」-「应用管理」-「查看详情」-App_key。
alt

2.2 请求body

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

2.3 user格式

参数描述类型说明
user_unique_id用户唯一标识string必填,推荐核心字段

2.4 header格式

参数描述类型说明
os_name客户端系统名称,枚举值,ios/androidstring推荐选填,数据统计展示字段
os_version客户端系统版本号string推荐选填,只允许设置为 "ios", "android", "web", "wap", "mac", "windows", "linux", "ipad", "iphone", 其他的值会解析成unknown
device_brand设备品牌string推荐选填,并尽量使用枚举值(取值可自行定义,如:tianyu、hongmi等)
device_model设备型号string推荐选填
client_ip客户端 ipstring推荐选填,地理位置推断依据
app_name应用的英文名称string推荐选填
app_version客户端版本号,三段分割,如 1.0.1string推荐选填
custom自定义 header 字段,单层 json mapstring选填,自定义通用维度

2.5 events格式

参数描述类型说明
event事件名,见图文、视频、小视频、短内容埋点文档string必填
params事件自定义字段,json mapstring必填, 具体参照
图文埋点通用说明
短视频埋点通用说明
小视频埋点通用说明
local_time_ms事件时间戳(推荐客户端时间戳),单位:毫秒long必填,用于事件归档

3.HTTP Response 格式

HTTP 状态码

状态码返回信息含义
200{"message":"success", "sc": num}
num为成功条数
成功,返回成功event数,失败的查看events上报格式,全部错误则返回num=0
400Your request is malformed.请求格式错误, 查看X-MCS-AppKey与header,user的定义
413You had too many events in your request.单个请求事件数过多,或请求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": {
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "device_brand": "tianyu",         //设备品牌
        "device_model": "SM-G9250",    //设备型号
        "client_ip": "10.100.1.1",     //客户端ip地址
        "app_name": "news_article",    //App名称
        "app_version": "5.1.3"         //App版本
    },
    "events": [
        {
            "event": "test_go_detail",    //事件名称
            "params": "{\"__items\":[{\"group_item\":[{\"id\":63559}]}],\"params_for_special\":\"content_manager_system\",\"A\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}

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": {
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "device_brand": "tianyu",         //设备品牌
        "device_model": "SM-G9250",    //设备型号
        "client_ip": "10.100.1.1",     //客户端ip地址
        "app_name": "news_article",    //App名称
        "app_version": "5.1.3"         //App版本
    },
    "events": [
        {
            "event": "test_go_detail",    //事件名称
            "params": "{\"__items\":[{\"group_item\":[{\"id\":63559}]}],\"params_for_special\":\"content_manager_system\",\"A\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}]

5.上报数据限制

  • 单个应用的事件数量不超过1000个(不同应用之间互不影响);

  • 单个事件的属性数量推荐300个以内,最多不超过500个(不同事件之间互不影响);

  • 单个应用自定义公共属性数量不超过100;

  • 事件名称和属性名称长度建议在50字节以内,事件属性名最长不超过80字节,公共属性名最长不超过64字节;

  • 属性值长度建议不超过255字节,特殊情况如url等最大支持1024字符。

(超过上述限制时,超过的事件、属性数据可能会被系统自动丢弃)