文档中心

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。

字段	类型	说明
Content-Type	string	application/json
X-MCS-AppKey	string	您应用的APP Key

说明

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

2.2 请求body

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

2.3 user格式

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

2.4 header格式

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

2.5 events格式

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

3.HTTP Response 格式

HTTP 状态码

状态码	返回信息	含义
200	{"message":"success", "sc": num} num为成功条数	成功，返回成功event数，失败的查看events上报格式，全部错误则返回num=0
400	Your request is malformed.	请求格式错误, 查看X-MCS-AppKey与header，user的定义
413	You 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