支持的数据格式与事件/属性分类

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

使用各类型SDK采集上报数据时：

• 需要先在各端中集成对应的SDK。
• 后续SDK会将采集的数据通过JSON格式进行上报。
• 收到上报数据后，系统会对JSON数据进行处理并落库，落库后的数据类型与上报的JSON中的数据类型有对应关系。

其中：

• 各端集成SDK时，部分系统预置事件/属性支持在代码中配置是否需要采集上报，也支持定义自定义事件/属性。
• 支持采集上报的JSON数据类型，以及与落库后的数据库数据类型的对应关系详情请参见下文的属性数据类型章节；上报的JSON示例可参见下文的日志结构章节。
• 数据采集上报后，系统对上报数据进行处理落库时，不同类型的数据可进行计算生成不同的指标数据，便于后续的分析使用，支持的计算应用详情请参见下文的不同数据类型应用章节。
• 数据采集上报时，采集上报的限制条件详情请参见下文的上报数据的限制章节。

根据增长分析的业务数据分析场景，Finder为您将事件和属性进行了以下业务层面的定义分类，后续您在SDK集成与埋点配置时，可根据业务需要配置对应的事件/属性。

注意事项

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

属性数据类型对应关系

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

• 不同属性数据类型，可计算的指标

  类别	分析功能	数据类型	计算方法
  事件	事件分析	-（全部）	总次数 总人数 人均次数
  事件	分布分析	-（全部）	总次数 天数 小时数
  事件属性	通用	int float	按……求和 按……求平均值 按……求人均值 按……求分位数
  事件属性	通用	Int float string list datetime	按……求去重数 按……和用户去重

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

  类型	为空	不为空	=	≠	大于	小于	大于等于	小于等于	包含	不包含	正则匹配
  字符串	✓	✓	✓	✓					✓	✓	✓
  整型	✓	✓	✓	✓	✓	✓	✓	✓
  浮点型	✓	✓	✓	✓	✓	✓	✓	✓
  数组	✓	✓							✓	✓
  日期时间	✓	✓
  版本	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓

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

  操作符名称	说明
  固定范围	所选属性的时间在一个固定的时间范围内，可以是过去365天到未来365天内的任何一天或多天。
  在当前时间	所选属性的时间位于查询发起的时刻到用户所设定的相对时段之间。 可选条件： 过去 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0） 未来 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
  在今天和	所选属性的时间位于查询发起的当天（自然天）到用户所设定的相对天数（自然天）范围之间。 可选条件： 过去 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0） 未来 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
  在事件发生	所选属性的时间位于相对当前事件的发生时间的一段时间内。由于用到了事件的发生时间，所以仅当作为事件的过滤条件时才会出现这种操作符。 可选条件： 当天、当周和当月：事件发生时所在的自然天、周或月 之前 {N} {天,秒,分,小时,周} 内（此时的天、周计算时不是自然天、自然周，而是相对事件发生时刻推算出的时刻） 之后 {N} {天 , 秒,分,小时,周} 内（同前） N 的取值范围： 天：1 <= N <= 365（当前都按天级的限制执行） 秒：1 <= N <= 365 分：1 <= N <= 365 小时：1 <= N <= 168 周：1 <= N <= 52

  说明

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

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

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 属性长度和范围的限制

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

• 私有化

  {
      "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 计算，但只精确到天
  }
  

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’入库，相当于属性信息丢失，但事件正常上报。
具体转换成功信息如下表：

Q3： 是否接受时间戳string的上报，会自动解析成datetime格式吗？

A3：时间戳不支持，只支持日期时间的格式。

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

A4：不支持。支持的datetime上报格式为"yyyy-MM-dd HH:mm:ss"。

Q5： 埋点 设计时，如何选择正确的数据类型？

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

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