帮助中心 > 技术文档 > 基础知识 > 数据格式

本章节将会详细介绍海纳嗨数支持的数据结构、数据类型以及数据限制。通过本章节,您将了解如何构建符合规则的数据,排查数据传输问题。
如果您使用的是 数据导入 或 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
作者:刘建雄  创建时间:2022-08-09 14:54
最后编辑:王建华  更新时间:2024-10-31 14:08