数据格式

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

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

数据类型	类型中文名	类型限制	数据示例
STRING	字符串	使用UTF-8编码，最大长度为1024字节	"数据分析"
NUMBER	数值	-9E15~9E15，小数点后至多3位	12.234
DATETIME	日期时间	年的取值范围是[1900,2099]，时间格式上最长符合yyyy-mm-dd hh-mm-ss.sss	2020-01-01 01:12:23 12.23
BOOL	布尔	无	ture
LIST	集合	最多由500个元素组成，单元素长度限制为255字节	["game","sports"]

考虑到用户触达终端产品类型的不同，我们为不同的产品类型设计了不同的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":"北京市"//城市
	}
}

各个字段的含义如下：

distinct_id：用以唯一标识用户的ID，在用户未登录时，此处填充内容应为设备ID或CookieID等匿名ID，对于已经登录的用户，此处应填充用以标识用户的业务ID，类型为字符串类型。

time：时间戳，用以记录事件触发时的时间，单位为毫秒，类型为数值类型。

type：接口类型，track接口标识该条数据作为一个事件写入Event表中。

event：事件名，用以标识该事件，事件名的命名需要符合标准变量规则，即只包含大小写字母，数字及下划线，且不能以数字开头，上述的数据样例中事件名前没有包含符号，表示该事件为自定义事件，预置事件的事件名前以开头作为表示，自定义事件命名时不能以$符号开头。

project：项目名称，用以标识该事件隶属于哪个项目，项目命的命名同样受变量命名的规则限制，当不指定该字段的值时，需要使用该字段的时候则填充default，即默认项目，如指定该字段的值，所指定的项目必须是已经存在于系统中的项目，否则该条数据将被拒绝。

time_free：该字段建议在导入历史数据时使用，SDK实时采集的过程中不建议使用该字段，该字段表示不根据事件触发时间过滤该事件，如果出现该字段且值不为null，则不再校验事件触发时间是否在可导入的时间范围内。

properties：该事件所携带的具体属性，属性的命名需符合变量的标准命名方式，即只包含数字，大小写字母及下划线，属性名前带有$符号的属性代表该属性为预置属性，属性名称及属性显示名称已经预先定义完成且不可更改，在不同的事件中同名的属性命名及数据类型需保持一致，同时限制大小写，例如存在某属性名称为item_id且数据类型为字符串，那么其他事件中该属性不可命名为ITEM-ID或Item_Id，数据类型也需保持为字符串，否则数据校验将不会通过。

lib：SDK类型，表示采集该事件所使用的SDK类型，类型为字符串类型。

os_version：设备的操作系统版本，类型为字符串类型。

lib_version：SDK版本，类型为字符串类型。

os：设备的操作系统类型，类型为字符串类型。

maunfacturer：设备的制造商，类型为字符串类型。

wifi：触发该事件时设备的网络类型是否为wifi，类型为布尔类型。

item_id：物品ID，类型为字符串类型。

item_classify：物品类型，类型为字符串类型。

item_price：物品价格，类型为数值类型。

ip：设备的IP地址，类型为字符串类型。

province：设备所处的省份，由IP解析获得，类型为字符串类型。

city：设备所处的城市，由IP解析获得，类型为字符串类型。

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”。

样例中的数据中，hobbies字段值存在重复，写入的过程不会去重

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类型作为判断依据。

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

原始类型	目标类型	转换方法
数值类型	布尔类型	不为0的值转换为true，为0的值转换为false
数值类型	日期时间类型	按照UNIX的时间戳的秒或毫秒进行转换
数值类型	字符串类型	原值作为字符串
布尔类型	数值类型	ture转换为1，false转换为0
布尔类型	字符串类型	原值作为字符串
字符串类型	数值类型	空字符串则抛弃，其余的转换为数值类型
字符串类型	布尔类型	原值按照true与false转换为布尔类型的true与false
字符串类型	日期时间类型	按照匹配的日期时间格式进行转换
字符串数组	字符串类型	原值作为字符串
日期时间类型	字符串类型	原值作为字符串

如果数据无法转换格式，则会直接忽略这条数据。

特别注意

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

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