注意
环境 | URL | Methord |
---|---|---|
SaaS |
| POST |
SaaS-海外 |
| |
SaaS云原生 |
| |
私有化 |
注意 ${host}:私有化部署客户为埋点数据上报申请的域名,请根据实际的域名进行替换,客户域名更新后也需要同步更新上报的路径地址。 |
字段 | 类型 | 说明 |
---|---|---|
Content-Type | string | application/json |
X-MCS-AppKey | string | 您应用的APP Key |
APP Key的获取位置请参考以下截图:
字段 | 类型 | 说明 |
---|---|---|
user | object | user属性字典,详见 2.3。 |
header | object | header属性字典,详见 2.4。 |
events | [object] | events列表,每个元素为一个事件,详见 2.5。 |
字段 | 类型 | 必选 | 说明 |
---|---|---|---|
user_unique_id | string | 是 | 用户的唯一身份标识,需要保证同一个用户在本应用内全局唯一,即需要与客户端上报一致。 |
device_id | string | 否 | app端设备标识,注意必须为纯数字。 |
web_id | string | 否 | web端设备标识,注意必须为纯数字。 |
字段 | 类型 | 必选 | 说明 |
---|---|---|---|
app_name | string | 否 | 应用的英文名称 |
app_package | string | 否 | 包名 |
app_channel | string | 否 | app分发渠道 |
app_version | string | 否 | app版本,三段分隔,如1.0.1 |
app_platform | string | 否 | 应用的端,不支持自定义修改。 |
access(SaaS) | string | 否 | 网络类型,落库为network_type。 |
carrier(SaaS) | 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事件。 |
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 | 否 | 推广关键词 |
字段 | 类型 | 必选 | 说明 |
---|---|---|---|
event | string | 是 | 事件名 |
params | string | 是 | 事件参数,单层json map |
local_time_ms | long | 是 | unix_timestamp( 毫秒) |
状态码 | 返回信息 | 含义 |
---|---|---|
200 | {"message":"success", "sc": num} | 成功,返回成功event数,失败的查看events上报格式,全部错误则返回num=0。 |
400 | header/user/events empty 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 |
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 :这个是毫秒时间戳,标识这个事件发生的时刻。
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 :这个是毫秒时间戳,标识这个事件发生的时刻。
注意
本节仅适用于【SaaS云原生】、【私有化】版本,SaaS-非云原生版本请参考User Profile API(服务端)。
用户属性是通过特殊的事件进行上报,通过设置下面几个event可以修改用户属性:
事件名 | 功能 |
---|---|
__profile_set | 设置用户属性。 |
__profile_set_once | 设置用户属性,属性为set_once,设置后不可更改。 |
__profile_increment | 增加数值类用户属性的值。 |
__profile_unset | 删除用户属性。 |
__profile_append | 增加数组类用户属性的元素。 |
__profile_remove | 删除数组类用户属性里的元素。 |
用户属性放在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 //事件发生的时间戳 } ] }
可以在行为细查页面中查看特定用户的数据,如果是大量数据,可以在事件分析中对用户属性进行分析。
注意
本节仅适用于【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 //事件发生的时间戳 } ] }
已在数据管理>业务维度页面添加业务维度;并已完成上述步骤:创建业务对象。
创建好的 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
是转为 string
的 json
对象,其格式为:
[ {"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_1
、id_value_2
即为item id的取值,例如订单号id1、订单号2。
注意
如果事件数据上时,item数据没有被定义(即没有在数据管理中添加业务维度),则关联关系不生效,则无法正常使用item分析。
注意
【SaaS-非云原生版本】历史数据导入需要隔天才能查看,【SaaS云原生】、【私有化】版本可实时查看。
如果数据的客户端时间超过七天,正常情况下无法导入。如需导入历史数据,需在header
的custom
字段中增加历史数据的标识__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: 这个是毫秒时间戳,标识这个事件发生的时刻,注意不是导数的时间。
上报完成后,需要在界面上点击刷新数据,即可查询到上报的历史数据。
请参考文档: