You need to enable JavaScript to run this app.
导航
HTTP API
最近更新时间:2024.10.09 17:44:03首次发布时间:2024.04.30 15:17:27

注意

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

1. 请求接口

环境

URL

Methord

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

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字段(用于标识发起请求的客户端软件的信息,不影响调研API的结果)。
    • 如果手动发送可能会提示User-Agent is not allowed,则需要手动在请求头上加入User-Agent字段,此场景下,您可以随机填写一个user-Agent字段的取值,或先使用类似Postman等工具调用一下API,复制其中的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的获取位置请参考以下截图:
图片

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(SaaS)
network_type(私有化)

string

网络类型,落库为network_type。

carrier(SaaS)
network_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(任意事件)事件下。

说明

any_event事件为系统保留事件,不代表任一真实事件,以事件分析的界面操作为例,您可以在选择指标的时候选择any_event事件。
图片
通过custom上报的自定义事件公共属性后续会显示在any_event(任意事件)事件下。

region

string

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

language

string

语言(系统设置),en等

app_region

string

国家(app设置),us等

app_language

string

语言(app设置),en等

timezone

string

时区,-12~12

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云原生】、【私有化】版本,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 验证上报的用户属性

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

6. 上报业务对象属性

6.1 创建业务对象

注意

本节仅适用于【SaaS云原生】、【私有化】版本,SaaS-非云原生版本请参考业务维度(item)数据接入(SaaS-非云原生版)

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

前提条件

在进行业务维度数据接入前,您需要先根据业务情况,规划好需要分析的业务维度有哪些、每个业务维度需要有哪些属性,并在DataFinder的数据管理中创建好对应的业务维度。后续数据接入的业务维度和属性数据需与已添加的业务维度信息保持一致。添加业务维度的操作请参见业务维度
业务对象内置的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与事件关联

创建好的 item 对象需要与事件关联才可以使用。您需要在配置数据接入时,同时配置好业务维度和事件数据的关联规则,即将某一个或多个具体item的item id 值配置到事件的预置属性params.__items当中。

注意

SaaS场景下一个事件当前可最多支持三个item。

下列示例代码演示了将 sku 和 order 两个创建好的业务维度与事件 new_order 进行关联的方式。__items 为事件预置属性,仅用于上报业务维度。
示例如下:

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

__items 是转为 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 就是在上一步中定义的业务维度名称,例如order;id_value_1id_value_2即为item id的取值,例如订单号id1、订单号2。

注意

如果事件数据上时,item数据没有被定义(即没有在数据管理中添加业务维度),则关联关系不生效,则无法正常使用item分析。

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:可以在事件分析页面进行查询分析。