数据格式
本章节将会详细介绍海纳嗨数支持的数据结构、数据类型以及数据限制。通过本章节,您将了解如何构建符合规则的数据,排查数据传输问题。
如果您使用的是 数据导入 或 RESTful API 上传数据,需要按照本章节中的数据规则对数据进行格式处理。
1. 数据结构
海纳嗨数接受的是符合规则的 JSON 数据:如果使用的是 SDK 接入,则数据将会被转化成 JSON 数据进行传输。如果使用导入工具方式上传数据,则数据需要是符合规则的 JSON 数据。
JSON 数据以行为单位:即一行一条 JSON 数据,对应物理意义上的一条数据,数据意义上对应的是用户产生一次行为,或者是设置一次用户属性。
1.1 事件时间限制
导入错误时间的数据,会影响真实数据分析的准确性,因此默认情况下海纳对事件时间进行限制:
A、使用客户端 SDK (iOS、Android、js、小程序等)导入,只接收事件时间向前10天内和向后24小时内的数据(相比于系统当前时间);
B、使用后端语言 SDK (如 Java、C# 等)或导入工具(如 Datax、dataimporter、Logstash + Filebeat等)。
1.2 事件结构
事件记录:
记录一个 Event 及关联的 Properties。
{
"anonymous_id": "F77C4B19-6E05-4ED3-B415-348A3E34BD97",
"account_id ": "10001",
"time": "2022-08-09 15:12:33",
"type": "track",
"event": "app_start",
"_track_id": 123456,
"properties": {
"H_app_version":"1.3",
"H_wifi":true,
"H_ip":"252.79.22.65",
"H_province":"上海市",
"H_city":"上海市",
"H_lib_method": "code",
"H_os_version": "13.7",
"H_lib": "iOS",
"H_manufacturer": "Apple",
"H_lib_version": "4.4.0",
"H_os": "iOS"
"event_duration": 0,
"product_name":"苹果",
"resume_from_background": true,
}
}
对于上述字段的说明如下:
- anonymous_id:类型是字符串,对用户的标识,对未登录用户,匿名用户标识符(与 account_id 二选一,或者同时存在);
- account_id:类型是字符串,对用户的标识,对已登录用户,区分用户的唯一标识符(与 anonymous_id 二选一,或者同时存在);
- event_time:类型是时间,事件发生的实际时间精确到秒;
- type:track 表明是记录一个 Event ,这里我们假设是APP启动行为;
- event:事件名,需是合法的变量名,不能以特殊字符或数字开头,且只包含:大小写字母、数字、下划线,其中以 H_ 开头的表明是系统的预置事件,自定义事件名请不要以 H_ 开头;
- properties:这个 Event 的具体属性,以 dict 的形式存在。其中以H_开头的表明是系统的预置属性,它的类型和中文名已经预先定义好了。自定义属性名需要是合法的变量名,不能以特殊字符或数字开头,且只包含:大小写字母、数字、下划线,自定义属性不能以 H_ 开头;同一个名称的 property,在不同 event 中,必须保持一致的定义和类型;字段名不区分大小写。
- H_app_version:用户所使用的 App 的版本;
- H_wifi:这条事件发生时,用户是否在使用 wifi;
- H_ip:用户使用设备的 IP。若数据中出现H_ip,且数据中没有 H_province 或 H_city 字段,将使用该 IP 解析出省市信息填入缺失字段;
- H_province、H_city:省、市,在没有填充这两个字段的时候,会根据 IP 进行解析;
event_duration、product_name、resume_from_background:设置一些自定义事件属性,前提必须先在元事件管理中配置,否则则会抛弃上送字段,不入库处理。
登录事件记录:
这个接口是一个登录功能(将设备ID与登录账户绑定),可在业务登录时或者打开APP时判断是否登录调用该事件。
{
"anonymous_id":"F77C4B19-6E05-4ED3-B415-348A3E34BD97",
"account_id":"10001",
"original_id":"F77C4B19-6E05-4ED3-B415-348A3E34BD97",
"time": "2022-08-09 15:12:33",
"type": "track_signup",
"event": "H_SignUp",
"_track_id": 123456,
"properties": {
"H_manufacturer":"Apple",
"H_model": "iPhoneXR",
"H_os":"iOS",
"H_os_version":"13.5",
"H_app_version":"13.3",
}
}
这条JSON数据表示,一个匿名 ID 为 F77C4B19-6E05-4ED3-B415-348A3E34BD97 的用户,成功完成了注册,注册后的注册 ID 是 10001。并且系统后台,会将 original_id 为 F77C4B19-6E05-4ED3-B415-348A3E34BD97 的用户和 account_id 为 10001 的用户,代表匿名ID与注册ID进行绑定。
1.3 用户结构
Profile 相关操作,主要是用来设置用户属性 的,提供了如下一系列接口:
用户属性记录:
{
"anonymous_id":"F77C4B19-6E05-4ED3-B415-348A3E34BD97",
"account_id":"10001",
"type": "user_set",
"event_time": "2022-08-09 16:09:09",
"_track_id": 123456,
"properties": {
"H_province":"湖南",
"name": "小红",
"age":33,
"Gender":"男",
"H_signup_time": "2015-06-26 11:43:15.610"
}
}
直接设置一个用户的user_setOnce 与 user_set 接口不同的是,如果用户表对应该字段值已经存在,上送的值不会覆盖原来的值,如果 不存在,则会自动创建。因此,user_setOnce 比较适用于为用户设置首次激活时间、首次注册时间等只在首次设置时有效的属性。
属性值加减(user_add)
{
"anonymous_id":"F77C4B19-6E05-4ED3-B415-348A3E34BD97",
"account_id":"10001",
"type": "user_add",
"time": "2022-09-09 16:33:21",
"_track_id": 123456,
"properties": {
"level": 1
}
}
增加或减少一个用户的某个 数值 类型的属性值,比如给用户属性 level 的值加 1 或者减 1 。如果用户表(users)中不存在这个用户,则会在用户表中自动创建该用户的 id 记录,并给该用户设置相应的属性值,会在默认值 0 的基础上增加上传的值。
1.4 属性数据类型
分析属性数据类型定义
数据类型 | 类型名称 | 限制 | 备注 |
---|---|---|---|
DECIMAL | 数值 | 小数点后最多保留3位 | 如:12,12.34 |
VARCHAR | 文本 | 使用 UTF-8 编码后最大长度 1024 字节,如需调整最大长度可以联系分析师 | 如:"zhangsan","city" |
DATETIME | 日期时间 | yyyy-MM-dd HH:mm:ss.SSS 或 yyyy-MM-dd HH:mm:ss 或 yyyy-mm-dd (时分秒按00:00:00处理) | -- |
BOOLEAN | 布尔 | -- | 如: true,false,对应数据库0,1 |
预置属性
为了帮助客户能够更方便地使用我们的产品,我们目前分别为 事件 和 用户 提供了一些预置字段,详细查看预置属性与系统字段。
预置属性的作用:
- 预置属性会在SDK中自动采集,也可以手动设置关闭。
- 海纳嗨数系统会基于部分预置属性做业务逻辑处理,比如预置属性H_IP,如果前端没上送,则海纳嗨数系统会取请求中的IP填充。
- 部分预置属性用于全埋点过程中自动采集,可以手动设置相关预置属性采集关闭。
保留字段
为了保证自定义属性不与系统变量名冲突,设置属性时清规避系统字段,系统字段如下:
user_id
distinct_id
anonymous_id
account_id
update_time
part_date
event
event_time
server_time
timezone_offset
最后编辑:王建华 更新时间:2024-10-31 14:08