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

HTTP API

更新时间:2023.03.28 11:08:16

说明:

  • 服务端上报的http接口增长分析平台为您默认开通,如果您接入的应用没有开通,请联系客户成功经理解决;
  • 本文档部分内容对于SaaS、SaaS云原生、私有化不同环境会有差异,请注意区分;
  • 使用此功能之前,建议您先阅读数据格式数据质量文档说明避免上报细节错误。
1.请求接口
环境UrlMethod备注

SaaS

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

POST

SaaS海外

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

POST

SaaS云原生

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

私有化

单条数据上传:
https://${host}/v2/event/json
批量数据上传(每批次最多20条):
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-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应用的端,不支持自定义修改
accessstring网络类型,落库为network_type
carrierstring运营商类型,落库为network_carrier
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 格式
状态码返回信息含义

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的定义

400not found app_key and not found app_id请求未带上X-MCS-AppKey,且header中未填写app_id \
400parse POST request error! err: can not parse JSON:...请求参数解析错误,无法解析json
413too many element in one request! length: xx , only allow 50请求数组过长(只针对/json/list接口,限制50)
413too many events in one request! length: 89 , only allow 50请求中event数过多(限制50)
500UserAgent is not allowedHTTP请求头的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云原生】、【私有化】版本,SaaS版本请参考User Profile API(服务端)

用户属性是通过特殊的事件进行上报,通过设置下面几个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
            }
        }
    ]
}

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

5.3 验证上报的用户属性

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

6.上报业务对象属性

请注意:本节仅适用于【SaaS云原生】、【私有化】版本,SaaS版本请参考User Profile API(服务端)

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.导入历史数据

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

8.上报数据限制

请参考文档:

9.验证数据上报成功

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