彩虹数据支持多种 SDK 上报数据，接口会有所不同，但底层数据都使用统一的数据格式。本节介绍彩虹后台的数据结构、数据类型以及数据限制。

上报数据的格式

数据整体是 JSON 格式，描述用户产生的一次行为，或者是设置一次用户属性。

事件(Event)数据样例：

{
    "$account_id": "a5c719fc61-123",
    "$distinct_id": "8c0eebf0-2383-44bc-b8ba-a5c719fc61888",
    "$type": "track",
    "$ip": "192.168.1.100",
    "$uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$event_time": "2021-09-13 14:36:30.527",
    "$event_name": "test",
    "properties": {
        "argString": "abcd",
        "argNum": 1234,
        "argBool": true
    }
}

用户属性设置(Profile)数据样例：

{
    "$account_id": "a5c719fc61-123",
    "$distinct_id": "8c0eebf0-2383-44bc-b8ba-a5c719fc61888",
    "$type": "user_set",
    "$event_time": "2021-09-13 14:36:30.527",
    "properties": {
        "userArgString": "abcd",
        "userArgNum": 1234,
        "userArgBool": true
    }
}

$type 的值可以替换为 user_setOnce、user_add、user_unset、user_append、user_del。

从结构和功能上，可以将一条 JSON 数据分为两个部分：

1. 基本信息部分（与 properties 同层），只包括以下几项：

• 表示触发用户的账号 ID $account_id 与访客 ID $distinct_id
• 表示触发时间 $event_time，可精确到秒或毫秒
• 表示数据类型（事件还是用户属性设置）的 $type
• 表示事件名称的 $event_name（仅事件数据带有）
• 表示用户 IP 的 $ip
• 表示数据唯一性的 $uuid

注意

请注意，除以上几项外，其余以 $ 开头的属性都需要放在 properties 的内层。

2. 数据主体部分（properties 内层），是该条数据的内容，也就是事件中的属性，或者需要设置的用户属性，在后台分析时作为属性或分析对象被直接使用。

从结构上来看，这两部分与报文头（Header）和报文体（Content）有些类似，接下来将会详细介绍这两部分各字段的含义。

数据信息部分

与 properties 同层的数个字段组成了该条数据的信息部分。这些字段包含了这条数据的触发用户、触发时间等数据信息，其特点是所有字段都以 $ 开头，本节将会梳理各字段的意义以及如何配置。

用户信息（$account_id 与 $distinct_id）

$account_id 与 $distinct_id 是彩虹后台用来识别用户的两个字段，其中 $account_id 为用户在登录状态下的 ID，$distinct_id 为用户在未登录状态下的标识，彩虹后台会根据这两个字段判断该行为的触发用户，其中优先根据 $account_id 进行判断。

$account_id 与 $distinct_id 至少要传入一个。如果所有事件都是在用户登录状态下触发的，则只传入 $account_id 是可行的；如果有事件是在未登录状态（包括注册前）触发的，则建议将两个字段都填入。

数据类型信息（$type 与 $event_name）

$type 决定了该条数据的类型，是用户的行为记录、还是修改用户属性的操作处理，每一条数据都需要配置 $type 字段。$type 的取值分为两类，track 代表这条数据是用户行为记录，以 user_ 开头代表对用户属性进行操作，具体意义如下：

$type 取值	说明
track	向事件表传入一个事件，事件的上传都为 track
user_set	对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
user_setOnce	对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
user_add	对用户表进行操作，为一个或多个数值型用户属性做累加计算
user_unset	对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
user_append	对用户表进行操作，为用户的列表类型属性值添加元素
user_del	对用户表进行操作，删除该名用户

当 $type 的取值为 track 时，即该条数据是行为记录时，必须配置事件的名称 $event_name：必须以字母开头，只能包含数字、字母（忽略大小写）和下划线 _，长度最大为 50 个字符。请注意配置时不要带有空格。如果该条数据是修改用户属性的操作，则不需要 $event_name 字段。

提示

需要注意的是，用户属性是用户具有节点意义的属性，不建议在短时间内进行频繁修改。对于需要频繁变更的属性，建议放在事件中作为事件属性。

触发时间（$event_time）

$event_time 为事件产生的时间，必须要配置，格式必须是精确到毫秒（yyyy-MM-dd HH:mm:ss.SSS）或秒（yyyy-MM-dd HH:mm:ss）的字符串。

尽管对 User 表的操作数据也需要配置 $event_time，但对于用户属性的操作会按照后台收到数据的先后顺序进行操作。

触发地点（$ip）

$ip 是设备的 IP 地址，可选配置，彩虹将会根据 IP 地址计算用户的地理位置信息。如果您在 properties 中传入了 $country、$province、$city 等地理位置属性，则会以传入的值为准。

数据唯一 ID（$uuid）

$uuid 是用以表示数据唯一性的字段，可选配置，格式必须为 uuid 的标准格式。彩虹会根据数据量，在一段时间内，在接收端校验是否短时间内出现相同 $uuid 的数据（即重复数据），并将重复数据直接抛弃，不再入库。

注意

需注意，通过 $uuid 进行的接收端校验只会对近几个小时接收到的数据进行校验，主要解决因网络抖动问题造成的短时数据重复，无法将接收到的数据与全量数据进行校验。

数据主体部分

数据的另一部分，则是 properties 内层所包含的数据，properties 是一个 JSON 对象，里面的数据以键值对的形式表示。如果是用户行为数据，其代表了该行为的属性及指标（相当于行为表中的字段），这些属性及指标可在分析时直接使用；如果是用户属性的操作处理，则代表需要设置的属性内容。

• key 值为该属性的名称，类型是字符串，自定义的属性必须以字母开头，只能包含数字、字母（忽略大小写）和下划线 _，且长度最大只能 50 个字符；另外还存在以 $ 开头的彩虹预置属性，但需要注意，大多数情况下建议只使用自定义的属性，不使用 $。
• value 值为该属性的值，可以是数值、字符串、时间与布尔值。

注意

需要注意，所有属性的类型会根据第一次收到该属性值的类型所决定，后续数据的类型必须与相应属性的类型一致，类型不匹配的属性将被丢弃（该条数据其余符合类型的属性将保留）。

数据处理规则

彩虹服务器在收到数据之后，会进行一些处理，本节将会结合实际使用场景，介绍后台的处理规则：

收到新事件数据

在收到新增事件的数据后，彩虹后台会自动地创建新增事件与其属性的关联模型；如果收到了新的属性，则首次收到该属性时的属性类型将会设置为该属性的类型，属性的类型之后将不能修改。

增添事件的属性

如果需要对已有事件增添属性，只需要在上传数据时将新增属性一并传入即可，彩虹后台将会动态地关联事件与新增属性，不需要进行其他配置。

属性不一致的处理

当收到一条事件数据，其中某属性的类型与后台已存的该属性的类型不一致，则该属性的值将会被抛弃（即取值为 null）。

弃用事件属性

如果需要弃用事件某个属性，则只需要在彩虹后台的元数据管理中将该属性隐藏即可，后续传输的数据可不传该属性。彩虹后台不会删除该属性的数据，隐藏操作也是可逆的，如果在属性被隐藏后仍传输该属性，该属性的值仍会被保留。

多事件共有属性

不同事件的同名属性被视为是同一属性，类型一致，因此需要保证所有同名属性的类型一致，以避免由于类型不一致而导致的属性值被抛弃。

用户表操作逻辑

修改用户在用户表中的数据，也就是上报数据中 $type 字段为 user_set、user_setOnce、user_add、user_unset、user_append 或 user_del 的数据，本质上可以看作是一条指令，也就是对该条数据所指用户的用户表数据进行操作，操作的类型由 $type 字段决定，而操作的内容以 properties 中的属性所决定。

以下是主要的用户表属性操作的具体逻辑：

操作类型	具体逻辑
覆盖用户属性（user_set）	根据数据中的用户 ID 确定进行操作的用户，再根据 properties 中的属性，覆盖所有属性，如果某个属性不存在则新建该属性。
初始化用户属性（user_setOnce）	根据数据中的用户 ID 确定进行操作的用户，再根据 properties 中的属性，对未赋值（为空）的属性进行设置，如果该用户的某需要设置的属性已经有值，则不会进行覆盖，如果某个属性不存在则新建该属性。
累加用户属性（user_add）	根据数据中的用户 ID 确定进行操作的用户，再根据 properties 中的属性，对数值型的属性进行累加操作，如果传入负值相当于原属性值减去传入值，如果该用户的某需要设置的属性未赋值（为空），则会默认设置为 0 后再进行累加操作，如果该属性不存在则新建该属性。
清空用户属性值（user_unset）	根据数据中的用户 ID 确定进行操作的用户，再根据 properties 中的属性，清空其中的所有属性（即设置成 NULL），如果某个属性不存在不会新建该属性。
添加列表型用户属性的元素（user_append）	根据数据中的用户 ID 确定进行操作的用户，再根据 properties 中的属性，对列表型的属性进行添加元素操作。
删除用户（user_del）	根据数据中的用户 ID 确定进行操作的用户，将该用户从用户表中删除，该用户的事件数据不会被删除。

数据限制

事件类型及属性数量限制

出于性能考虑，彩虹后台会默认地对项目的事件类型及属性的数量进行限制。

其它限制

彩虹后台对数据接收存在其它相关限制，具体以彩虹后台说明为准。

其他规则

• 使用 UTF-8 对数据进行编码，以避免乱码问题
• 彩虹后台的属性名与事件名不区分大小写，建议使用 _ 作为分词分隔符
• 彩虹后台默认只接收最近三年的数据，超过三年的数据将无法录入