You need to enable JavaScript to run this app.
导航

支持的数据格式(自定义事件/属性)

最近更新时间2024.01.29 19:17:19

首次发布时间2021.02.23 10:41:47

增长分析支持多种语言的SDK,这些SDK接口上报的数据,在底层数据模型中需要使用统一的数据格式,系统为您提供的预置事件/属性已遵循此统一的数据格式,如果您需要自定义事件/属性,需严格按照支持的数据格式来定义自定义事件/属性的数据格式。本文为您介绍详细的数据格式要求。

背景信息

使用各类型SDK采集上报数据时,会将采集的数据通过JSON格式进行上报,收到上报数据后,系统会对JSON数据进行处理并落库,落库后的数据类型与上报的JSON中的数据类型有对应关系。

其中:

  • 支持采集上报的JSON数据类型,以及与落库后的数据库数据类型的对应关系详情请参见下文的属性数据类型章节;上报的JSON示例可参见下文的日志结构章节。
  • 数据采集上报后,系统对上报数据进行处理落库时,不同类型的数据可进行计算生成不同的指标数据,便于后续的分析使用,支持的计算应用详情请参见下文的不同数据类型应用章节。
  • 数据采集上报时,采集上报的限制条件详情请参见下文的上报数据的限制章节。

1.属性数据类型

注意事项

  • 自定义事件/属性时,取值不要包含转义字符。
    创建自定义事件或属性时,需保障对应事件及属性的格式符合本文的格式要求,且自定义属性的取值不要包含例如转义字符类的特殊字符,例如“\n”。如果包含这类特殊字符,可能会导致后续数据能上报成功,但是查询分析时会导致查询结果不正确,您需要删除其中的特殊字符或使用虚拟属性,详情请参见显微镜功能中的常见问题。
  • 一个属性的数据类型由首次落库时的数据类型决定。
    例如,您在控制台界面新增了一个事件属性,此事件属性的数据类型为string。新建完成后此属性即已落库,后续在进行数据上报时,如果上报的属性数据类型又变为number,则不影响已落库的属性数据类型,只会导致上报的属性数据类型与已落库的属性数据类型不一致而导致可能出现上报错误等问题。
    您可以控制台界面的应用管理>数据管理中,可查看现有环境中属性的数据类型。
    图片

属性数据类型对应关系

属性数据类型有以下几种:

采集数据类型-中文名

采集数据类型-JSON

数据库类型

额外说明

示例数据

整数

number

int64

取值范围:[-9223372036854775808, 9223372036854775807]

1024

浮点数

number

float64

8字节,最大精度16位

10.24

字符串

string

string

长度不超过 1024 字符,utf-8编码

"1024"

数组

array

list

最多支持500个元素,元素数据类型支持 string,一个数组中所有元素类型需保持一致。

注意

数据落库时,会对 list 的元素进行去重,例如 [5,5,5] ,变成[5] ; [5,5,6] ,变成[5,6] ; [5,6,5] ,变成[5,6] 。

["10", "24"]

日期时间

string

datetime

上报格式:

  • "yyyy-MM-dd HH:mm:ss"
  • "yyyy-MM-dd HH:mm:ss+Offset"(其中 +Offset 为时区偏移)
  • "yyyy-MM-dd HH:mm:ss.SSS"(其中 SSS 为毫秒)
  • "yyyy-MM-dd HH:mm:ss.SSS+Offset"(同前)

日期的取值范围:[1970, 2099]

说明

如果是形如 "2020-07-07 01:22:33" 的 datetime 上报,默认按应用级的时区;
如果您需要指定 timezone,需要上报 “2020-07-07T13:46:08.342+08:00” 格式的方式。

"2020-10-24 23:47:12"
"2020-10-24 23:47:12+08:00"
"2020-10-24 23:47:12.102"
"2020-10-24 23:47:12.102+08:00"

版本

string

string

版本类数据的上报格式为:

  • 2段~6段
  • 英文句点分隔
  • 每段最长5位数字。

系统发现上报数据的取值的格式匹配时,会自动将数据类型设置为版本类型。版本类型可按数值排序规则进行排序,也可进行大于及小于的运算符进行筛选。
对应格式要求的正则表达式为:^[0-9]{1,5}(.[0-9]{1,5}){1,5}$

"10.2"
"1.02.4"
"1.02.4.12345.22345.32345"

其他类型

object/boolean

string

支持上报 object 和 boolean (bool:是/否)数据类型的数据,但会被转化成 string 进行存储。

--

2.不同数据类型支持的计算应用
  • 不同属性数据类型,可计算的指标

    类别

    分析功能

    数据类型

    计算方法

    事件

    事件分析

    -(全部)

    总次数
    总人数
    人均次数

    事件

    分布分析

    -(全部)

    总次数
    天数
    小时数

    事件属性

    通用

    int
    float

    按……求和
    按……求平均值
    按……求人均值
    按……求分位数

    事件属性

    通用

    Int
    float
    string
    list
    datetime

    按……求去重数
    按……和用户去重

  • 不同属性数据类型,作为筛选条件可用的操作符

    类型

    为空

    不为空

    =

    大于

    小于

    大于等于

    小于等于

    包含

    不包含

    正则匹配

    字符串

    整型

    浮点型

    数组

    日期时间

    版本

    • 字符串类型可以选择“为空”和“不为空”用于匹配 null 或非 null。
    • 日期类型属性有一个单独的筛选规则(如下表):

    操作符名称

    说明

    固定范围

    所选属性的时间在一个固定的时间范围内,可以是过去365天到未来365天内的任何一天或多天。

    在当前时间

    所选属性的时间位于查询发起的时刻到用户所设定的相对时段之间。
    可选条件:

    1. 过去 {N} 小时 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须大于 M,365 >= N > M >0)
    2. 未来 {N} 小时 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须小于 M,365 >= N > M >0)

    在今天和

    所选属性的时间位于查询发起的当天(自然天)到用户所设定的相对天数(自然天)范围之间。
    可选条件:

    1. 过去 {N} 天 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须大于 M,365 >= N > M >0)
    2. 未来 {N} 天 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须小于 M,365 >= N > M >0)

    在事件发生

    所选属性的时间位于相对当前事件的发生时间的一段时间内。由于用到了事件的发生时间,所以仅当作为事件的过滤条件时才会出现这种操作符。
    可选条件:

    1. 当天、当周和当月:事件发生时所在的自然天、周或月
    2. 之前 {N} {天,秒,分,小时,周} 内(此时的天、周计算时不是自然天、自然周,而是相对事件发生时刻推算出的时刻)
    3. 之后 {N} {天 , 秒,分,小时,周} 内(同前)

    N 的取值范围:

    • 天:1 <= N <= 365(当前都按天级的限制执行)
    • 秒:1 <= N <= 365
    • 分:1 <= N <= 365
    • 小时:1 <= N <= 168
    • 周:1 <= N <= 52

    说明

    选择不同数据格式注意事项:

    * 需要求和、平均值、按照区间范围筛选的必须要用int、float数值类型。
    * 需要时间筛选条件的必须定义数据类型为datetime格式。
    

3.上报数据的限制

3.1 一般限制

  • 单个应用的上报的事件数总量不限制;
  • 单个应用支持元事件种类不超过1000个(不同应用之间互不影响,不含虚拟事件);
  • 单个事件的属性数量推荐300个以内,最多不超过500个(不同事件之间互不影响);
  • 用户属性的属性数量最多不超过 500个;
  • 单个应用自定义事件公共属性数量不超过100个;
  • 事件名建议不超过64个字符,最长不超过255个字符;
  • 事件属性名和用户属性名称最长不超过64个字符;
  • 属性值长度建议不超过255字符,特殊情况如url等最大支持1024字符;
  • 事件属性名称禁止命名为user_unique_id、ssid、event_id;
  • 属性名不允许和预置属性名称相同;预置属性文档可查看预置属性

说明

超过上述限制时,超过的事件、属性数据可能会被系统自动丢弃。更多请查看数据质量

3.2 事件时间限制

使用客户端 SDK (iOS、Android)导入的数据,服务端默认只接收事件发生时间在接收时间向前 7 天内和向后24小时内数据。

3.3 命名限制

  1. events表中,同一个属性名,不允许存在多个属性类型,只有一种属性类型。
  2. users表中,同一个属性名,不允许存在多个属性类型,只有一种属性类型。
  3. 同一个属性名,如果在events和users表中同时存在,在两表中数据类型可以相同,也可以不同。

3.4 属性长度和范围的限制

中文名

数据库类型

额外说明

整数

int64

取值范围:[-9223372036854775808, 9223372036854775807]

浮点数

float64

8字节,最大精度16位

字符串

string

最大支持 1024 字符。

版本(字符串)

version(string)

格式:1. 2段~6段 2. 英文句点分隔 3. 每段最长5位
示例:1.1.2.4321

数组

list

最多支持500个元素,元素数据类型支持 string,一个数组中所有元素类型需保持一致。

日期时间

datetime

日期取值范围:[1900, 2099]

4.日志结构

入库后可看到的数据格式分别如下:

  • 私有化

    {
        "time": 1606301031,
        "server_time": 1606249381,
        "local_time_ms": 1606301031000,
        "device_id": "6912716898461553676",
        "os": "ios",
        "params": {
            "package": "package",
            "app_version": "1.0.6",
            "device_model": "iphone 6s plus",
            "timezone": "8.0",
            "os_version": "10.3.2",
            "session_depth_range": "5",
            "session_id": "762891435873043",
            "network_carrier": "TELCEL",
            "language": "zh",
            "exit_page": "http://datarangers.com.cn/pages/index/3",
            "product_name": "default_to_b",
            "resolution": "375x667",
            "platform": "ios",
            "loc_country_id": "1814991",
            "app_channel": "线下扫码下载",
            "device_brand": "苹果",
            "browser": "chrome",
            "os_name": "ios",
            "loc_province_id": "1280239",
            "session_duration_range": "100-200",
            "client_ip": "118.213.201.135",
            "loc_city_id": "1279540",
            "browser_version": "68.0.3440",
            "network_type": "mobile",
            "duration": 117,
            "session_depth": 5,
            "screen_width": 375,
            "localtime_ms": 1606301031000,
            "screen_height": 667,
            "session_duration": 117,
            "is_login": 1
        }
    }
    
    
  • SaaS

    {
            "user": {
                "ssid": "",                // SSID
                "user_unique_id": "",      // user_unique_id,存储于 string_profiles{'uuid'}
                "web_id": 0,               // 网页端的匿名ID,存储于 string_profiles{'web_id'}
                "device_id": 0,            // 移动端,小程序端的匿名ID
                "user_register_time": ""   // 用户首次事件触发时间
            },
            "params": {
                "language": "zh-CN",
                "region": "",
                "app_version": "unknown",
                "app_region": "",
                "app_channel": "",
                "app_language": "",
                "os_version": "10",
                "os_name": "10",
                "device_model": "Windows NT 10.0",
                "device_brand": "",
                "network_type": "",
                "network_carrier": ""
            },
            "items":{
                "sku": [{
                    "id": "",
                    "property_1": "",     // 当前item定义的属性1
                    "property_1": "",     // 当前item定义的属性2
                }]
            },
            "event_name": "predefine_pageview",
            "app_id": "2174",             // string, rangers 中的应用id
            "app_name": "数据发现者",       // string, rangers 中的应用名
            "server_time": 1606783082,    // int(timestamp), 服务端收到事件的时间, 精确到 ms
            "time": 1606783080,           // int(timestamp), time = local_time_ms/1000,单位为秒。
            "event_date": 1606783080      // date, 基于 time 计算,但只精确到天
    }
    

5.FAQ

Q1:事件属性数据类型传输错误,需要修改怎么办?

描述:在业务迭代过程中,属性含义出现变化,或者上报过程中出现错误,需要修改怎么办?
A1

  1. 第一步:管理员在产品前端界面修改,选择应用管理-数据管理。
    图片

  2. 第二步:找到对应属性名称。
    图中预置属性(增长分析SDK默认采集的属性,无需手动上报)数据类型为灰色,表示不可修改。只有代码埋点过程中手动上报的属性,才可以修改属性类型。
    图片

  3. 第三步:选择修改的属性类型。
    图片
    图片
    系统会根据修改的数据类型进行提示,其中转换数据规则如下。仅针对事件属性,不适用于用户属性。

    原数据类型

    原数据示例

    新数据类型

    新数据示例

    历史数据

    新数据

    其他说明

    值为数值类string

    "1"

    int

    1

    不丢失

    按新数据类型上报,入库正常

    允许修改,且历史数据不丢失,可以查询。

    值为数值类string

    "0.1"

    float

    0.1

    不丢失

    按新数据类型上报,入库正常

    值为非数值类 string

    "abc"

    int

    0

    有损

    按新数据类型上报,入库正常

    float

    0.1,0.61.1,1.7

    int

    向下取整(取小数点之前的整数),0.1,0.6会变成0;1.1和1.7会变成1。

    不丢失

    按新数据类型上报,入库正常

    int

    1

    string

    丢失

    丢失

    按新数据类型上报,入库正常

    允许修改,但历史数据不再能查询,再变更回原类型,依然可用。比如string->int->string。

    int

    1

    float

    丢失

    丢失

    按新数据类型上报,入库正常

    float

    0.1

    string

    丢失

    丢失

    按新数据类型上报,入库正常

    除上述表中,其他情况的转换,例如string-datetime,历史数据会丢失,按新数据类型上报,入库正常,并且不可转换为原类型,操作不可逆,请谨慎操作。

  4. 第四步:需要研发代码层面,按照新的数据格式进行上报。

注意

修改前端数据类型后,请及时修改代码,否则会有入库失败或者数据丢失。

Q2: 各端数据类型传输不一致,系统如何处理?如何修改?

描述:例如IOS端先传入A属性的格式为数值类型,安卓端后传入A属性的格式为字符串类型,此时系统如何处理,结果会如何?
A2:一个属性的类型由首次导入的数据类型决定,如果后续传入不同数据类型的数据,系统会尝试做转换,如果转换成功,则入库。如果转换失败,则属性信息值为‘0’入库,相当于属性信息丢失,但事件正常上报。
具体转换成功信息如下表:

原数据类型

新数据类型

是否转换成功

其他说明

int、float、datetime、list

string

数值型string,例如‘1’,‘0.1’

int、float

原数据类型虽为string,但是值为数字123456

float

int

但是会丢失小数点后面的数据。

int

float

其余数据类型均转换失败。

注意

需要在数据校验侧规避这一问题,如果发生,请错误端及时调整数据格式,否则会引发数据丢失。

Q3: 是否接受时间戳string的上报,会自动解析成datetime格式吗?

A3:时间戳不支持,只支持日期时间的格式。

Q4:datetime是否接受按天级别格式的数据,"yyyy-MM-dd"

A4:支持。(上报格式:"yyyy-MM-dd")

Q5: 埋点 设计时,如何选择正确的数据类型?

中文名

数据库类型

应用场景

整数

int64

需要数值求和,平均值等计算,并且不会出现小数的情况。例如:年龄,整数金额。

浮点数

float64

需要数值求和,平均值等计算,并且会出现小数的情况。例如:折扣金额,时长。

字符串

string

常用的文本类属性,例如:页面标题,按钮名称,商品分类。不需要计算的ID类型,例如:内容ID,商品ID。

数组

list

集合,一个属性有多个值,但筛选又需要按单个筛选的。例如:一篇娱乐新闻属于多个内容标签,{‘热门’,‘娱乐’,‘新闻’}例如:一个商品属于多个商品标签{'折扣',‘秋季’,‘女性’}

日期时间

datetime

需要按照日期范围筛选的

版本

string

需要对版本进行排序时

Q6:为什么会一段的版本值?不是版本格式要求至少两段么?

默认情况下,系统在遇到被“.”切割为至少两段的数据时(例如 2.0),会自动判断其为版本类型。而对于已知的版本类型的字段,我们会将这个限制放开,允许没有”.“,例如:2 这样的值上报。因为在一些情况下,版本号只有一段。当然对于这种情况,你也可以选择将版本号作为 int 类型上报。