数据格式

数据分析工作台的数据传输过程以JSON作为数据传输格式，通过表名与属性名锁定一个唯一属性。这也意味着，同一个数据表中的同一个属性，数据类型必须保持一致。

同时，在JSON的基础上，我们定义了数种数据类型：

考虑到用户触达终端产品类型的不同，我们为不同的产品类型设计了不同的SDK用来采集数据，租户可以根据自己的产品类型进行选择，需要注意的是，使用不同SDK进行数据采集时，需要的数据格式是统一的，下面将从事件，用户，物品三大方面介绍基本数据格式，以及不同接口的作用。

事件相关

track

track接口主要用来记录一条Event及其所携带的properties，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"track",//接口类型
    "event":"item_view",//事件名
    "project":"test",//项目名
    "time_free":true, //事件发生时间过滤选择
    "properties":{
        "$lib":"Android",//SDK类型
        "$os_version":"9.1.0",//操作系统版本
        "$lib_version":"3.1.5",//SDK版本
        "$os":"Android",//操作系统
        "$maunfacturer":"HUAWEI",//设备制造商
        "$wifi":ture,//是否为Wifi
        "item_id":"09f3k94e903f23e894j2",//物品ID
        "item_classify":"手机",//物品分类
        "item_price":3999.0,//物品价格
        "item_name":"HUAWEI P20",//物品名称
        "$ip":"180.78.25.13",//IP地址
        "$province":"北京市",//省份
        "$city":"北京市"//城市
    }
}

各个字段的含义如下：

track_signup

此接口可以理解为特殊的事件接口，主要用在注册以及登录事件中，用以关联用户的匿名ID与业务ID，所以除了常规的传入distinct_id以外，还需要传入original_id（设备ID），工作台在接收数据后，ID-mapping模块会将业务ID与匿名ID进行关联，打通用户注册登录前后的数据链条，同时，如果使用者采用了多对一关联方案，还可以打通用户在多端设备上的行为数据，完整监测用户旅程。下方为数据样例：

{
    "distinct_id":"12345",//业务ID
    "original_id":"ABCDE"//匿名ID
    "time":1609312457,//时间戳
    "type":"track_signup",//接口类型
    "event":"$SignUP",//事件名
    "project":"test",//项目名
    "properties":{
        "$lib":"Android",//SDK类型
        "$os_version":"9.1.0",//操作系统版本
        "$lib_version":"3.1.5",//SDK版本
        "$os":"Android",//操作系统
        "$maunfacturer":"HUAWEI",//设备制造商
        "$wifi":ture,//是否为Wifi
        "$ip":"180.78.25.13",//IP地址
        "$province":"北京市",//省份
        "$city":"北京市"//城市
    }
}

此条数据表示，一个匿名用户在设备ID为“ABCDE”的设备上发生了注册行为，触发了注册事件，事件数据同时携带了业务ID distinct_id与匿名ID original_id，ID-mapping模块将会把这两个ID进行关联，并在内部分配一个统一的ID进行标识，后续用户在此设备上进行操作时，无论登录与否，都会被视为一个用户。

用户相关

profile_set

此接口用以配置一个用户的属性，如果该用户已经存在，则覆盖原本的数据，如果该用户不存在，则直接创建，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_set",//接口类型
    "project":"test",//项目名称
    "properties":{
        "$lib":"Android",//SDK类型
        "$os_version":"9.1.0",//操作系统版本
        "$lib_version":"3.1.5",//SDK版本
        "$os":"Android",//操作系统
        "$maunfacturer":"HUAWEI",//设备制造商
        "$wifi":ture,//是否为Wifi
        "$ip":"180.78.25.13",//IP地址
        "$province":"北京市",//省份
        "$city":"北京市"//城市
    }
}

此条数据的接口类型为profile_set，表示该条数据将写入User表：

如果User表中不存在distinct_id为“12345”的用户，将直接创建一个distinct_id为“12345”的用户，同时将properties中的所有属性值同时写入。

如果User表中存在distinct_id为“12345”的用户，此条数据所携带的属性值将覆盖原先表中的数据。

profile_set_once

此接口与profile_set的功能大致相同，区别在于，如果该用户已存在，那么这条数据将会被忽略，如果该用户不存在，则直接创建，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_set_once",//接口类型
    "project":"test",//项目名称
    "properties":{
        "$lib":"Android",//SDK类型
        "$os_version":"9.1.0",//操作系统版本
        "$lib_version":"3.1.5",//SDK版本
        "$os":"Android",//操作系统
        "$maunfacturer":"HUAWEI",//设备制造商
        "$wifi":ture,//是否为Wifi
        "$ip":"180.78.25.13",//IP地址
        "$province":"北京市",//省份
        "$city":"北京市"//城市
    }
}

此条数据的接口类型为profile_set_once，表示该条数据将写入User表：

如果User表中不存在distinct_id为“12345”的用户，将直接创建一个distinct_id为“12345”的用户，同时将properties中的所有属性值同时写入。

如果User表中存在distinct_id为“12345”的用户，此条数据将会被忽略。

profile_increment

此接口用来对用户的某个数值类型的数据进行增加或减少，如果用户表中已经存在该用户，那么直接对设置的字段进行更改操作，如果不存在该用户，那么将直接创建一条用户记录，并附带设置的属性值，所设置的属性值会在默认为0的基础上进行增减，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_increment",//接口类型
    "project":"test",//项目名称
    "properties":{
        "vip_level":1,//对VIP等级执行+1操作
    }
}

此条数据的接口类型为profile_increment，表示该条数据将写入User表：

如果User表中不存在distinct_id为“12345”的用户，将直接创建一个distinct_id为“12345”的用户，接下来以VIP等级为0的基础上，对VIP等级执行+1操作，也就是最终写入User表时该用户的VIP等级为1。

如果User表中存在distinct_id为“12345”的用户，则直接对此用户的VIP等级执行+1操作，例如原先该用户的VIP等级为3，上方数据写入后，此用户的VIP等级会变更为4。

profile_append

此接口用来对用户属性中某个集合类型的字段进行添加一个或多个数据的操作，需要注意的是，如果此次添加的值与该字段的原有值发生重复，是不会进行去重操作的，如果此次添加的值本身存在重复值，也是不会进行去重操作的，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_append",//接口类型
    "project":"test",//项目名称
    "properties":{
    "hobbies":"["basketball","basketball","football"]",//在hobbies字段中添加值
    }
}

此条数据的接口类型为profile_append，表示该条数据将写入User表：

如果User表中不存在distinct_id为“12345”的用户，将直接创建一个distinct_id为“12345”的用户，同时在hobbies字段中添加数据中的三个值。

如果User表中存在distinct_id为“12345”的用户，则直接在此用户的hobbies字段中加入数据中三个值。假定用户的hobbies字段中已经存在basketball这个值，在写入时也不会进行去重，最终hobbies字段中将存在三个“basketball”。

profile_delete

此接口用来删除某个distinct_id的全部用户属性数据，数据样例如下：

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_delete",//接口类型
    "project":"test",//项目名称
    "properties":{
    }
}

此条数据表示直接将distinct_id为“12345”的用户属性数据从User表中删除。

profile_unset

此接口用来将用户的某个属性值设置为空，在该接口的使用过程中，需要设置为空的字段可以赋予任何除null以外的值。

{
    "distinct_id":"12345",//用户唯一标识
    "time":1609312457,//时间戳
    "type":"profile_unset",//接口类型
    "project":"test",//项目名称
    "properties":{
        "hobbies":True,
    }
}

词条数据表示将distinct_id为“12345”的用户的hobbies字段设置为空。

数据类型校验

数据类型的判定以第一次数据上报时的数据类型为准，例如第一次数据上报时vip_level的数据类型为number数值类型，那么在之后针对于同一表下的vip_level字段的数据类型将以number类型作为判断依据。

当数据上报时如果发现上报的数据类型与元数据类型不符，将触发数据格式强制转换操作，各个数据类型的强制转换规则如下表所示：

特别注意

在历史数据的导入过程中，有时会使用到$is_login_in这个字段，该字段的数据类型为布尔类型，其含义表示该条数据的distinct_id是否是一个业务ID，如该字段值为true，在该业务ID没有与设备ID进行管理的大前提下，如果用户在导入过程中开启了多对一的情况下，该业务ID后续可与设备ID进行绑定，如果用户在导入过程中没有开启多对一，那么该业务ID后续将无法与其他设备ID进行绑定。

如果该字段值为false，那么表示该条数据的distinct_id不是业务ID，而是一个设备ID，后续可以与业务ID进行绑定。