json格式取值_神策数据格式

最新推荐文章于 2024-09-03 15:36:32 发布

weixin_39588432

最新推荐文章于 2024-09-03 15:36:32 发布

阅读量691

点赞数

文章标签： json格式取值

神策分析支持多种不同语言的 SDK，这些 SDK 虽然在外部提供的接口上有所不同，但是在内部实现上都使用统一的数据格式，并且数据导入都支持直接导入以文件形式存储的符合要求格式的数据，在这里，我们对数据格式进行一个更加细致的描述。

注意：这里描述的是底层数据传输格式的定义，和具体 SDK 的调用接口无关
注意：$is_login_id 参数说明
1. 数据整体格式

日志文件是一行一个 JSON，物理上对应一条数据，逻辑上对应一个描述了用户行为的事件，或是描述一个或多个用户属性的 Profile 操作。

1.1. track：

记录一个 Event 及关联的 Properties。

数据样例：

{

"distinct_id": "123456",

"time": 1434556935000,

"type": "track",

"event": "ViewProduct",

"project": "ebiz_test",

"time_free": true, //建议在导入历史数据时使用，SDK 采集的实时数据不建议使用

"properties": {

"$is_login_id":true, //此参数请慎重使用，详细介绍请参考文档底部 8.1 $is_login_id 参数说明

"$app_version":"1.3",

"$wifi":true,

"$ip":"180.79.35.65",

"$province":"湖南",

"$city":"长沙",

"$user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_2 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/58.0.3029.113 Mobile/14F89 Safari/602.1",

"$screen_width":320,

"$screen_height":640,

"product_id":12345,

"product_name":"苹果",

"product_classify":"水果",

"product_price":14.0

}

对于上述字段的说明如下：

distinct_id：类型是字符串，对用户的标识，对未登录用户，可以填充设备标识、CookieID 等，对于登录用户，则应该填充注册账号；这里的例子，我们假设是一个未注册用户，所以填充的是一个设备编号；
time：类型是数值，事件发生的实际时间戳，精确到毫秒；
type：track 表明是记录一个 Event ，这里我们假设是一个商品浏览行为；
event：事件名，需是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和 $，其中以 $ 开头的表明是系统的保留字段，自定义事件名请不要以 $ 开头，且 event 字段长度最大为 100；
project：这条数据所属项目名，若不指定该参数，则需要使用该字段时取值 default，即默认项目。指定的项目必须是系统中已经存在的项目，否则这条数据将无效，更多项目相关请参见多项目；
time_free：可选字段，表示不根据事件发生时间过滤该事件。只要出现 time_free 这个 key 且 value 不为 null，将不再校验 time 是否在允许导入的时间范围内。导入历史数据时可能会用到该字段；
properties：这个 Event 的具体属性，以 dict 的形式存在。其中以$开头的表明是系统的保留字段，它的类型和中文名已经预先定义好了。自定义属性名需要是合法的变量名，不能以数字开头，且只包含：大小写字母、数字、下划线，自定义属性不能以 $ 开头；同一个名称的 property，在不同 event 中，必须保持一致的定义和类型；同一个名称的 property 大小写不敏感，如果已经存在小写属性就不可再导入对应大写属性(比如元数据中有 abc 属性名，不能再传 ABC,Abc 等属性名)，否则数据会校验失败不入库。$is_login_id：distinct_id 对应的是否是一个注册 ID；$app_version：用户所使用的 App 的版本；$wifi：这条事件发生时，用户是否在使用 wifi；$ip：用户使用设备的 IP。若数据中出现 $ip，且数据中没有 $province 或 $city 字段，将使用该 IP 解析出省市信息填入缺失字段；$province、$city：省、市，在没有填充这两个字段的时候，会根据 IP 进行解析；$user_agent：可选参数。如果传入该参数，则解析 User-Agent，解析结果包括：设备制造商、设备型号、操作系统、操作系统版本、浏览器、浏览器版本、爬虫名称(如果是爬虫)；目前是神策是通过 UA 判断并有一个默认的属性 $bot_name (爬虫名称)，但是有两种情况无法判断，第一种：如果 UA 里没有标明、且会触发 JS 脚本的非法爬虫。第二种：如果爬虫没有触发 JS 脚本，那么也不会触发我们的 SDK ，所以本身就不会被统计到。对于爬虫种类，不能提前把所有的种类都加进去，主流的神策都加了，其它的属于不太常见的，量较少。$screen_width、$screen_height：屏幕的宽和高；product_id、product_name、product_classify、product_price：跟商品相关的一些具体属性。

1.2. track_signup：

这个接口是一个较为复杂的功能，请在使用前先阅读标识用户，并在必要时联系我们的技术支持人员。

数据样例：

{

"distinct_id":"12345",

"original_id":"2b0a6f51a3cd6775",

"time": 1434557935000,

"type": "track_signup",

"event": "$SignUp",

"project": "ebiz_test",

"properties": {

"$manufacturer":"Apple",

"$model": "iPhone 5",

"$os":"iOS",

"$os_version":"7.0",

"$app_version":"1.3",

"$wifi":true,

"$ip":"180.79.35.65",

"$province":"湖南",

"$city":"长沙",

"$screen_width":320,

"$screen_height":640

}

这条数据表示，一个匿名 ID 为 2b0a6f51a3cd6775 的用户，成功完成了注册，注册后的注册 ID 是 12345。并且系统后台，会将 original_id 为 2b0a6f51a3cd6775 的用户和 distinct_id 为 12345 的用户，当做同一个用户对待。需要注意的是，此接口中的 original_id 为必须字段，表示与注册 ID 进行关联的匿名 ID。

1.3. Profile 相关操作

Profile 相关操作，主要是用来设置用户的 Profile 的，提供了如下一系列接口：

1.3.1. profile_set：

直接设置一个用户的 Profile，如果用户或者 Profile 的字段已存在，则覆盖，不存在则自动创建。

数据样例：

{

"distinct_id": "12345",

"type": "profile_set",

"time": 1435290195610,

"project": "ebiz_test",

"properties": {

"$province":"湖南",

"FavoriteFruits": ["苹果","香蕉","芒果"],

"Age":33,

"$city":"长沙",

"IncomeLevel": "3000~5000",

"$name": "小明",

"Gender":"男",

"$signup_time": "2015-06-26 11:43:15.610"

}

1.3.2. profile_set_once

直接设置一个用户的 Profile。与 profile_set 接口不同的是，如果用户或者 Profile 的字段已存在，则这条记录会被忽略而不会覆盖已有数据，如果 Profile 不存在则会自动创建。因此，profile_set_once 比较适用于为用户设置首次激活时间、首次注册时间等只在首次设置时有效的属性。

数据样例：

{

"distinct_id": "12345",

"type": "profile_set_once",

"time": 1435290195610,

"project": "ebiz_test",

"properties": {

"$province":"湖南",

"FavoriteFruits": ["苹果","香蕉","芒果"],

"Age":33,

"$city":"长沙",

"IncomeLevel": "3000~5000",

"$name": "小明",

"Gender":"男",

"$signup_time": "2015-06-26 11:43:15.610"

}

1.3.3. profile_increment：

增加或减少一个用户的某个 NUMBER 类型的 Profile 值，比如给用户属性 Age 的值加 1 或者减 1 。如果用户表( users 表)中不存在这个用户，则会在用户表中自动创建该用户的 id 记录，并给该用户设置相应的 Profile 属性值，会在默认值 0 的基础上增加上传的 Profile 值。

数据样例：

{

"distinct_id": "12345",

"type": "profile_increment",

"time": 1435290200354,

"project": "ebiz_test",

"properties": {

"Age": 1

}

1.3.4. profile_delete：

删除一个用户的整个 Profile。

数据样例：

{

"distinct_id": "12345",

"type": "profile_delete",

"time": 1437290200354,

"project": "ebiz_test",

"properties":{

}

1.3.5. profile_append：

向某个用户的某个数组类型的 Profile 添加一个或者多个值。如果本次上传的值，与系统中已存在的值有重复，默认是不会去重的。如果本次上传的值，有重复项，也不会去重的。

数据样例：

{

"distinct_id": "12345",

"type": "profile_append",

"time": 1437280200354,

"project": "ebiz_test",

"properties": {

"FavoriteFruits": ["橘子","西瓜"]

}

1.3.6. profile_unset：

将某个用户的某些属性值设置为空。另外，为了与其它接口保持一致，在提交的数据上，属性的值请设置为非 null 的任何值，例如 true。

数据样例：

{

"distinct_id":"12345",

"type":"profile_unset",

"time":1437280200354,

"project": "ebiz_test",

"properties":{

"Age":true,

"FavoriteFruits":true

}

1.4. Item 相关操作

Item 相关操作，主要是用来设置 Item 的具体内容，提供了如下一系列接口：

1.4.1. item_set：

直接设置一个 Item，如果 Item 的字段已存在，则覆盖，不存在则自动创建。

数据样例：

{

"type":"item_set",

"item_id":"12",

"item_type":"dub",

"project": "ebiz_test",

"properties":{

"title":"because of u",

"sub_title":"st",

"xxx":"xxx"

}

对上述字段的解释如下：

type：item_set 表明是设置一个 item；
item_id：表示 item 的 id
item_type：item 表的类型，区分不同的 item 表。需是合法的变量名，即不能以数字开头，且只包含：大小写字母、数字、下划线和 $，且 item_type 字段长度最大为 100；
project：这条数据所属项目名，若不指定该参数，则需要使用该字段时取值 default，即默认项目。指定的项目必须是系统中已经存在的项目，否则这条数据将无效，更多项目相关请参见多项目；
properties：这个 item 的具体属性，以 dict 的形式存在。属性名需要是合法的变量名，不能以数字开头，且只包含：大小写字母、数字、下划线；

1.4.2. item_delete：

删除整个 Item 内容。

数据样例：

{  "type":"item_delete",  "item_id":"16",  "item_type":"dub",  "project": "ebiz_test"}

Copy

CODE

1.5. 属性数据类型

1.5.1. 注意问题

发送端使用 JSON 作为数据传输格式，本系统以 JSON 数据类型为基础再加以额外限制，定义了若干种数据类型，但 不与 JSON 类型完全等价，详见后文属性类型说明。
(table_name, property_name) 二元组唯一确定一个属性，table_name 为数据表的表名，如 users、events，可在自定义 SQL 查询中看到。这意味着同表同名属性类型必须相同，而不同表的同名属性类型可以不同。消息类型与所写入的数据表的关系如下表：

一个属性的类型由首次导入时的类型决定，元数据-事件属性/用户属性页面展示的属性类型即为首次导入时的类型，后续导入数据时若类型和元数据中展示的类型不符，则尝试对数据进行类型转换，若无法转换或转换失败则 输入数据会被整条拒绝 。尝试进行的类型转换如下(空格不进行转换)：

上述表格左侧的列对应目标类型，上方的行对应原始类型。目标类型对应元数据中的数据类型，原始类型是数据上传时的属性值类型什么时候该使用数值类型的属性：需要进行聚合运算(例如求和、均值)或者按区间分组的值，典型的比如价格、时长、年龄等。除非有特殊需求，否则各类 ID(例如订单 ID)不建议作为数值类型存储。