You need to enable JavaScript to run this app.
导航
HTTP API
最近更新时间:2024.08.21 19:33:57首次发布时间:2024.08.21 19:33:57

注意

  • 服务端上报的http接口默认开通,如果您接入的应用没有开通,请联系客户成功经理解决;
  • 本文档部分内容对于SaaS、SaaS云原生、私有化不同环境会有差异,请注意区分;

1.请求接口

环境

Url

Method

SaaS

  • 单条数据上传:https://mcs.ctobsnssdk.com/v2/event/json
  • 批量数据上传(每批次最多50条):https://mcs.ctobsnssdk.com/v2/event/list

POST

SaaS海外

  • 单条数据上传:https://mcs.tobsnssdk.com/v2/event/json
  • 批量数据上传(每批次最多50条):https://mcs.tobsnssdk.com/v2/event/list

POST

SaaS云原生

  • 单条数据上传:https://gator.volces.com/v2/event/json
  • 批量数据上传(每批次最多50条):https://gator.volces.com/v2/event/list

私有化

  • 单条数据上传:https://${host}/v2/event/json
  • 批量数据上传(每批次最多50条):https://${host}/v2/event/list

说明

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

2.请求规范

1.请求的header里带"Content-Type: application/json"以及“X-MCS-AppKey”,作为app的标识。通过http api上报时,如果用代码及一些工具时,一般请求头上会自动带上User-Agent字段,如果手动发送可能会提示User-Agent is not allowed,则需要手动在请求头上加入User-Agent字段;
2.请求的body包含user,header,event三个部分,其中的header是埋点数据本身的header;
3.单次上传events数建议控制在20条以内,超过50条会报413;
4.上传如采用/v2/event/list接口,json数目建议控制在20条以内,超过50条会报413。

2.1 请求header

字段

类型

说明

Content-Type

string

application/json

X-MCS-AppKey

string

您应用的APP Key

APP Key的获取位置请参考以下截图:
在开始集成前,首先需要在集团中接入一个项目及应用,进行SDK集成前,您需要获取对应应用的appid、appkey等信息。
私有化场景下您可以在「全局设置」->「系统设置」->「集团设置」-> 「项目列表」中查看项目详情,可查看其中的appid、appkey等信息,详情请参见集团设置
图片

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

用户的唯一身份标识,需要保证同一个用户在本应用内全局唯一,即需要与客户端上报一致。

device_id

string

app端设备标识,注意必须为纯数字。

web_id

string

web端设备标识,注意必须为纯数字。

2.4 header格式

字段

类型

必选

说明

app_name

string

应用的英文名称

app_package

string

包名

app_channel

string

app分发渠道

app_version

string

app版本,三段分隔,如1.0.1

app_platform

string

应用的端,不支持自定义修改。

access

string

网络类型,落库为network_type。

carrier

string

运营商类型,落库为network_carrier。

platform

string

平台类型

os_name

string

客户端系统,只允许设置为 "ios", "android", "web", "wap", "mac", "windows", "linux", "ipad", "iphone", 其他的值会解析成unknown。

os_version

string

客户端系统版本号

device_model

string

设备型号

ab_sdk_version

string

ab实验分组信息

traffic_type

string

流量类型

client_ip

string

客户端ip

custom

json object

自定义header字段,单层json map。上述字段都是保留字段不能使用。自定义事件公共属性放在这,会显示在any_event事件下。

region

string

所在区域国家(系统设置),us等,(放在custom中)

language

string

语言(系统设置),en等,(放在custom中)

app_region

string

国家(app设置),us等,(放在custom中)

app_language

string

语言(app设置),en等,(放在custom中)

timezone

string

时区,-12~12,(放在custom中)

utm_source

string

推广来源

utm_campaign

string

推广活动

utm_medium

string

推广媒介

utm_content

string

推广内容

utm_term

string

推广关键词

2.5 event格式

字段

类型

必选

说明

event

string

事件名

params

string

事件参数,单层json map

local_time_ms

long

unix_timestamp( 毫秒)

3. HTTP Response 格式

状态码

返回信息

含义

200

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

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

400

header/user/events empty error.
get/invalid appid error.

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

400

not found app_key and not found app_id

请求未带上X-MCS-AppKey,且header中未填写app_id。

400

parse POST request error! err: can not parse JSON:...

请求参数解析错误,无法解析json。

413

too many element in one request! length: xx , only allow 50

请求数组过长(只针对/json/list接口,限制50)

413

too many events in one request! length: 89 , only allow 50

请求中event数过多(限制50)

500

UserAgent is not allowed

HTTP请求头的User-Agent不合法,包括msnbot、Sosospider、Sosoimagespider、Sogou web、spider、Googlebot、Baiduspider、360Spider、YoudaoBot、YandexBot、EasouSpider、Mediapartners-Google、APIs-Google、AdsBot-Google、JikeSpider、MJ12bot、ia_archiver、Rogerbot、exabot、DOCOMO Sprider、python-requests、HttpClient、Go-http-client、Python-urllib、gohttp、curl/、Surf/、Scrapy

4. 请求示例

4.1 /v2/event/json接口

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

请求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://gator.volces.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. 上报用户属性

注意
本节仅适用于【SaaS云原生】、【私有化】版本。
用户属性是通过特殊的事件进行上报,通过设置下面几个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 批量上报用户属性

当需要批量上报用户属性时,可以在params里加上一个特殊字段__uuid_list来实现,__uuid_list是一个user_unique_id的列表,params中除__uuid_list字段的其他字段作为这个__uuid_list中所有user_unique_id的属性,参考代码:

{
    "user": {
        "user_unique_id": "user1"
    },
    "header":{"app_name":"init","app_id":"10000000"},
    "events": [
        {
            "event": "__profile_set",
            "params": {
                "__uuid_list": ["user1", "user2", "user3", "user4"],
                "age":20
            }
        }
    ]
}
matlab

注意
这个列表每次上报限制1000个用户。

5.3 验证上报的用户属性

可以在行为细查页面中查看特定用户的数据。

6. 导入历史数据

注意
【SaaS版本】历史数据导入需要隔天才能查看,【SaaS云原生】、【私有化】版本可实时查看。
如果数据的客户端时间超过七天,正常情况下无法导入。如需导入历史数据,需在headercustom字段中增加历史数据的标识__is_history,属性值设置为字符串"true"。 上报示例如下:

[{
   "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: 这个是毫秒时间戳,标识这个事件发生的时刻,注意不是导数的时间。
上报完成后,需要在界面上点击刷新数据,即可查询到上报的历史数据。

7. 上报数据限制

请参考文档:

8. 验证数据上报成功

如果知道特定的user_unique_id,可以在行为细查里查询。
图片