# 数据格式
方舟支持多种 SDK 上报数据,接口会有所不同,但底层数据都使用统一的数据格式,尤其是通过工具导入数据时,也需要符合相应的数据格式。同时,不同的属性,会有不同的数据类型,在分析时对应不同的计算方式,所以在上报数据时需要注意采用合适的格式。
## 上报数据的格式
数据整体是 JSON 格式,描述一条事件或者属性。
**Event 数据样例**
```javascript
[
{
"appid":"demo",
"xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
"xwhat":"confirmOrder",
"xwhen":1533110482778,
"xcontext":{
"$pagename":"com.analysys.demo.activity.MainActivity",
"$channel":"豌豆荚",
"$manufacturer":"Xiaomi",
"$app_version":"4.0.4.001",
"$model":"MIX 2S",
"$os":"Android",
"$os_version":"8.0.0",
"$network":"WIFI",
"$screen_width":1080,
"$screen_height":2030,
"$brand":"Xiaomi",
"$is_first_day":true,
"$lib":"Android",
"$platform":"Android",
"$is_login":false,
"$lib_version":"4.0.4",
"$debug":2,
"order_price":1213.23
}
}
]
```
上述字段说明:
* `appid`:字符串类型,记录项目的 AppKey,创建项目后生成;
* `xwho`:字符串类型,记录用户 ID,调用接口生成;
* `xwhat`:字符串类型,记录事件 ID,必须是合法的变量名,由字母、数字和下划线组成,不能以数字开头,对于系统预置的事件以 $ 开头 ;
* `xwhen`:数据值类型,记录事件发生的时间戳,精确到毫秒;
* `xcontext`:事件的属性,以 dict 的形式存在,其中每个属性,有相应格式。以 $ 开头表示为系统预置的属性,其属性值数据类型都是约定好的,自定义的属性不要以 $ 开头,同一个属性 ID 在不同事件中的定义和数据类型应该保持一致。
**Profile 数据样例**
```javascript
[
{
"appid":"demo",
"xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
"xwhat":"$profile_set",
"xwhen":1533110558121,
"xcontext":{
"Email":"yonghu@163.com",
"$mac":"9c:2e:a1:fe:b7:eb",
"$lib":"Android",
"$platform":"Android",
"$is_login":false,
"$lib_version":"4.0.4",
"$debug":2
}
}
]
```
Profile 信息是通过一些特殊的事件上报,数据格式要求和事件相同。Profile 系列事件包括:
* $profile_set
* $profile_set_once
* $profile_unset
* $profile_increment
* $profile_append
* $profile_delete
> 特别说明:
>
> 建议您在上报数据时,用户属性ID 和 事件属性ID 使用小写英文字母和下划线组合命名,例如 pagename 、page_name;
>
> 不建议使用含大写字母的属性ID,例如 pageName 、pageTitle。
>
> 因为易观方舟会将 事件属性ID 和 用户属性ID 中的大写字母强制转换为小写字母。
## 属性值的数据类型
除了整体数据要以 JSON 作为数据传输格式之外,属性值的数据类型也会对应一定格式。
方舟定义了以下数据类型:
| 数据类型 | JSON类型 | 说明 | 示例 |
| ---- | -------- | ------------------------------------------------------------------------------ | ------------------------- |
| 字符串 | string | 使用UTF-8编码后最大长度1024字节 | "易观方舟" |
| 数值 | number | -9E14到9E14, 小数点后最多保留3位 | 123 或者123.12 |
| 布尔 | boolean | true/false | true/false |
| 日期 | datetime | 格式:yyyy-MM-dd HH:mm:ss.SSS 或yyyy-MM-dd HH:mm:ss 或yyyy-mm-dd | "2018-06-18 18:18:18.188" |
| 集合 | array | 元素为字符串,去重后最大元素个数 100,其中每个元素使用 UTF-8 编码后最大长度 255字节;是去重的无序的字符串集合,输入可有重复,导入过程中会去重 | \[ "写作","摄影","烹饪" ] |
方舟预置的一些事件属性和用户属性,也会同时定义好数据类型,详见[《预置事件和属性》](default-data/)。
>[danger]**方舟不会自动对数据类型错误的属性进行转换**
>假如我们有一个表示商品数量的属性 product_number 首次上报时是数值(number)类型,那么数据库就会将存储这个属性的字段的类型设置为数值(number)。如果接下来 product_number 收到非数值类型的值时,这一整条日志都会被标记为异常,进入错误队列,而不会进入方舟参与到正常计算中。
>错误队列中的数据会保留7天,如果需要恢复当中的数据,请随时联系我们。
>[info]如果发现数据异常变少,可以通过“**数据入库检查**”中的“**错误数据日志**”查看日志是否因为此种情况而被抛弃。
**不同数据类型属性值的应用**
数据上报中的属性,在分析时可以作为条件查询,也可以作为维度去细分,之所以需要定义不同属性值的数据类型,就是为了进行合适的运算和维度细分,例如 “支付订单金额” ,分析时希望对它进行求和、最大值、最小值、均值等运算,这就要求这个属性值的类型应该是数值型。
以下说明不同数据类型作为细分维度和过滤条件时的使用差异:
### 维度
| 数据类型 | 维度处理方式 | 举例属性 | 查询用户数,按举例维度细分 |
| ---- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 字符串 | 按离散值 | <p>商品类别<br>上报的属性值:<br>3C电器、服装、化妆品……</p> | <p>3C电器:12人<br>服装:12人<br>化妆品:18人</p> |
| 数值型 | <p>按离散值<br>自定义区间分组</p> | <p>商品价格<br>上报的属性:<br>12、20、90、300……</p> | <p>按离散值:<br>12:2人<br>20:3人<br>90:13人<br>300:1人<br>按用户自定义区间的话可能是:<br>(-∞,50):5人<br>[50,200):13人<br>[200,+∞]:1人</p> |
| 布尔值 | 按离散值 | <p>是否使用优惠券<br>上报的属性值:<br>true、false</p> | <p>使用了优惠券的:12人<br>没有使用优惠券的:18人</p> |
| 日期时间 | <p>按分钟、小时、日、周、月、季、年<br>按时段汇总:按分钟、小时、日、周,月</p> | <p>下单时间<br>上报的属性值:<br>2017-03-12 12:12:32、<br>2018-03-15 12:12:32、<br>2018-04-12 12:12:32……</p> | <p>不按时段汇总,按月:<br>2017年3月:23人<br>2018年3月:27人<br>2018年4月:12人<br>按时段汇总,按月:<br>每年3月:50人<br>每年4月:12人</p> |
| 集合 | 按集合字符串 | <p>用户爱好<br>上报的属性值:<br>[网球,摄影]、[户外,摄影]、[户外、壁球]……</p> | <p>[网球,摄影]:34人<br>[户外,摄影]:53人<br>[户外、壁球]:23人</p> |
### 条件
**字符串类型**
| 操作符 | 使用场景 | e.g. |
| ------------ | -------------------------------------------- | ------------------------------- |
| =(等于) | 当输入一个值时,表示等于某个具体确定的属性值;当输入多个时,表示满足其中的一项或多项 | 设备品牌 = 苹果,小米;设备品牌满足苹果、小米中的任意一个 |
| ≠(不等于) | 完全排除输入的某个或多个属性值 | 设备品牌 ≠ 苹果,小米;设备品牌不满足苹果、小米中的任何一个 |
| like(包含) | 查找属性值中包含某些字符的值 | 设备品牌中包含苹果这个词的 |
| notlike(不包含) | 排除属性值中包含某些字符的值 | 设备品牌中不包含苹果这个词的 |
| 有值 | 查找有属性值的数据 | 有设备品牌名称的 |
| 无值 | 查找无属性值的数据 | 无设备品牌名称的 |
| 正则匹配 | 用来检查一个串是否含有某种子串、将匹配的子串替换或者从某个串中取出符合某个条件的子串等 | - |
| 正则不匹配 | 用来检查一个串是否不含有某种子串、将匹配的子串替换或者从某个串中排除符合某个条件的子串等 | - |
**数值型**
| 操作符 | 使用场景 | e.g. |
| ------- | ----------- | ---------------- |
| = (等于) | 等于某个具体数字 | 商品金额 = 100 |
| ≠(不等于) | 不等于某个数字 | 商品金额 ≠ 100 |
| <(小于) | 小于某个数字 | 商品金额 < 100 |
| ≤(小于等于) | 小于等于某个数字 | 商品金额 ≤ 100 |
| >(大于) | 大于某个数字 | 商品金额 > 100 |
| ≥(大于等于) | 大于等于某个数字 | 商品金额 ≥ 100 |
| 介于区间 | 在某个数据区间内的数值 | 100<商品金额 ≤ 500 |
| 有值 | 查找有属性值的数据 | 有商品金额的 |
| 无值 | 查找无属性值的数据 | 无商品金额的 |
**布尔值**
| 操作符 | 使用场景 | e.g. |
| --- | --------- | -------- |
| 为真 | 某个判断为真 | 是否成功 = 是 |
| 为假 | 某个判断为假 | 是否成功 = 否 |
| 有值 | 查找有属性值的数据 | 有值 |
| 无值 | 查找无属性值的数据 | 无值 |
**日期时间**
| 操作符 | 使用场景 | e.g. |
| -------- | ------------- | -------------------------- |
| 绝对时间 | 在某个具体的时间范围 | 在 2018/12/14- 2018/12/17 |
| 相对当前时间点 | 在相对当前的某段时间里 | 在近 30 天内 |
| 相对事件发生时间 | 在相对事件发生的某段时间里 | 登录之前的 5 分钟里 |
| 有值 | 查找有属性值的数据 | 有日期 |
| 无值 | 查找无属性值的数据 | 无日期 |
**字符串集合**
| 操作符 | 使用场景 | e.g. |
| ------------ | ------------ | ----------- |
| like(包含) | 集合中包含某个字符的值 | 用户标签中包含 摄影 |
| notlike(不包含) | 集合中不包含某个字符的值 | 用户标签不包含设计摄影 |
| 有值 | 查找有属性值的数据 | 有用户标签 |
| 无值 | 查找无属性值的数据 | 无用户标签 |
>[info] 以上内容没有解答我的问题?[点击我进入方舟论坛去反馈](https://www.analysysdata.com/forum/index) 🚀
- 产品简介
- 快速上手
- Step 1 安装部署
- Step 2 激活系统创建项目
- Step 3 开启您的分析旅程
- 1. 集成 SDK
- 2. 可视化埋点
- 3. 创建分析模型
- 附:埋点方案设计
- 附:数据分析思路
- 产品更新日志
- V5.5 新增LTV分析功能等
- V5.3 UI 升级、分布分析重构、维度表动态更新、细节优化等
- V5.2 新增归因分析、消息中心、重构埋点方案、优化看数据体验……
- V5.1.0317 体验优化& Bug修复
- V5.1 升级可视化埋点、增强权限控制……
- Part I 产品功能说明
- 名词解释
- 指标说明
- 看板
- 5.3.3 看板 UI 重构
- 分析
- 事件分析
- 渠道分析
- 渠道相关名词解释
- 来源识别规则
- 搜索引擎
- 社交媒体
- 小程序场景值
- Session 分析
- Session 规则
- 实时分析
- 留存分析
- 转化漏斗
- 智能路径
- 归因分析
- 热图分析
- Web/H5 热图
- APP 热图
- 分布分析
- 间隔分析
- 属性分析
- LTV 分析
- 多主体分析
- 自定义查询
- 用户
- 用户分群
- 用户探查
- 用户标签
- 标签体系应用概览
- 标签体系
- 标签生命周期管理
- 标签加工
- 如何自定义SQL创建标签
- 单用户档案
- 运营
- 广告跟踪
- 微信小程序渠道追踪
- 预置广告媒介和渠道
- App 推广监测(Beta版本)
- 电子邮件(即将下线)
- 短信(即将下线)
- 消息通知(即将下线)
- 项目管理
- 项目概览
- 项目角色管理
- 项目成员管理
- 数据接入管理
- 埋点方案
- 可视化埋点
- 集成SDK接入数据
- 数据验证
- 用户数据导入
- 微信小程序全埋点事件定义
- 元数据管理
- 元事件
- 虚拟事件
- 事件属性
- 用户属性
- Session 管理
- 页面组管理
- 维度表
- 服务集成配置
- 监控告警
- 智能监控
- 自定义监控
- 平台管理
- 企业概览
- 项目管理
- 成员管理
- 安全设置
- 企业设置
- 日志管理
- 帐号设置
- Part II 技术文档
- 技术接入准备工作
- 部署环境检测工具
- 数据模型
- 数据格式
- 预置事件和属性
- App预置事件/属性
- JS 预置事件/属性
- 如何准确识别用户
- 如何设计埋点方案
- 分平台上报数据 vs 跨平台打通
- SDK 指南
- Android SDK
- 快速集成
- 全埋点模块
- 消息推送模块
- Android Hybrid模式
- SDK Gradle集成方式
- 多渠道打包
- 易观小工具
- 合规相关
- iOS SDK
- 快速集成
- 全埋点介绍
- iOS Hybrid模式
- 消息推送模块
- JS SDK
- 快速集成
- JS SDK基础版
- JS SDK插件
- uni-app SDK
- 快速集成
- 打包原生APP
- 开启移动端全埋点
- uni-app SDK标准版
- 微信小程序 SDK
- 快速集成
- 微信小程序标准版
- 微信小程序插件版
- 微信小程序通用框架版
- 支付宝小程序 SDK
- 支付宝小程序标准版
- 支付宝小程序通用框架版
- 字节跳动小程序 SDK
- 字节跳动小程序标准版
- 字节跳动小程序通用框架版
- 百度小程序 SDK
- 百度小程序标准版
- 百度小程序通用框架版
- 钉钉小程序 SDK
- 钉钉小程序标准版
- 钉钉小程序通用框架版
- QQ小程序 SDK
- QQ小程序标准版
- QQ小程序通用框架版
- 快应用 SDK
- 华为WeCode小程序
- WeCode SDK 标准版
- WeCode SDK插件
- PhoneGap SDK
- mPaaS SDK
- ReactNative SDK
- Flutter SDK
- Java SDK
- Python SDK
- PHP SDK
- C++ SDK
- C# SDK
- Node JS SDK
- Lua SDK
- Golang SDK
- SDK FAQ
- identify与alias的区别
- 爬虫数据如何识别?
- 页面停留如何获取时间?
- 如果获取SDK及更新日志
- 代码埋点和无埋点有什么区别
- Web页面中发现丢失某一个事件
- 自研 SDK 注意事项
- 页面时长统计功能
- 飞书小程序 SDK
- 飞书小程序标准版
- 飞书小程序通用框架版
- Unreal Engine SDK
- 数据验证
- 客户端埋点验证
- Debug 数据验证
- 数据入库验证
- 数据导入
- 接口导入
- JAVA工具包
- 标准json文件导入
- csv格式导入
- 数据导入FAQ
- 数据导出
- JAVA工具包
- 事件数据导出
- 用户数据导出
- 直接从Kafka中消费数据
- 使用程序访问数据库
- 脚本工具
- API
- 分析API
- 事件分析
- 留存分析
- 自定义查询
- 转化漏斗
- 属性分析
- Session分析
- 渠道分析
- 分布分析
- 用户API
- 分群查询
- 用户档案
- 分群管理
- 管理API
- 权限管理
- 元数据管理
- 埋点方案管理
- 维度表管理
- 运营API
- 广告跟踪
- APP推广监测
- 平台管理API
- 项目管理
- 成员管理
- 第三方登录
- OAuth2.0登录
- LDAP登录
- GDPR 合规
- Part III 常见问题
- License 许可
- 产品试用及采购
- 参与贡献