增长分析 DataFinder
增长分析 DataFinder
- 文档首页
增长分析 DataFinder开发者指南重要基础知识（必读）支持的数据格式与事件/属性分类
文档反馈
问问助手增长分析支持多种语言的SDK，这些SDK接口上报的数据，在底层数据模型中需要使用统一的数据格式，系统为您提供的预置事件/属性已遵循此统一的数据格式，如果您需要自定义事件/属性，或者此前使用过其他埋点上报工具需要改用DataFinder，需严格按照支持的数据格式来定义自定义事件/属性的数据格式。本文为您介绍详细的数据格式要求。
使用各类型SDK采集上报数据时：
- 需要先在各端中集成对应的SDK。
- 后续SDK会将采集的数据通过JSON格式进行上报。
- 收到上报数据后，系统会对JSON数据进行处理并落库，落库后的数据类型与上报的JSON中的数据类型有对应关系。
其中：
- 各端集成SDK时，部分系统预置事件/属性支持在代码中配置是否需要采集上报，也支持定义自定义事件/属性。
- 支持采集上报的JSON数据类型，以及与落库后的数据库数据类型的对应关系详情请参见下文的属性数据类型章节；上报的JSON示例可参见下文的日志结构章节。
- 数据采集上报后，系统对上报数据进行处理落库时，不同类型的数据可进行计算生成不同的指标数据，便于后续的分析使用，支持的计算应用详情请参见下文的不同数据类型应用章节。
- 数据采集上报时，采集上报的限制条件详情请参见下文的上报数据的限制章节。
根据增长分析的业务数据分析场景，Finder为您将事件和属性进行了以下业务层面的定义分类，后续您在SDK集成与埋点配置时，可根据业务需要配置对应的事件/属性。
事件/属性分类 | 业务含义说明 | |
|---|---|---|
系统预置 | 预置事件公共属性 | 系统预置的每一个事件都会上报的通用属性。比如Finder SDK上报的设备信息类字段。 |
预置事件及事件属性 | 系统预置的埋点事件以及事件属性。 | |
预置用户属性 | 系统预置的用于描述用户自身状态的属性。 | |
自定义 | 自定义事件公共属性 | 客户在预置事件公共属性以外自定义的事件公共属性。 |
自定义事件及事件属性 | 客户在预置事件及事件属性以外自定义的事件及事件属性。 | |
自定义用户属性 | 客户在预置用户属性以外自定义的用户属性。 | |
注意事项
- 自定义事件/属性时，取值不要包含转义字符。
创建自定义事件或属性时，需保障对应事件及属性的格式符合本文的格式要求，且自定义属性的取值不要包含例如转义字符类的特殊字符，例如“\n”。如果包含这类特殊字符，可能会导致后续数据能上报成功，但是查询分析时会导致查询结果不正确，您需要删除其中的特殊字符或使用虚拟属性，详情请参见显微镜功能中的常见问题。 - 一个属性的数据类型由首次落库时的数据类型决定。
例如，您在控制台界面新增了一个事件属性，此事件属性的数据类型为string。新建完成后此属性即已落库，后续在进行数据上报时，如果上报的属性数据类型又变为number，则不影响已落库的属性数据类型，只会导致上报的属性数据类型与已落库的属性数据类型不一致而导致可能出现上报错误等问题。
您可以控制台界面的应用管理>数据管理中，可查看现有环境中属性的数据类型。
属性数据类型对应关系
属性数据类型有以下几种：
采集数据类型-中文名 | 采集数据类型-JSON | 数据库类型 | 额外说明 | 示例数据 |
|---|---|---|---|---|
整数 | number | int64 | 取值范围：[-9223372036854775808, 9223372036854775807] | 1024 |
浮点数 | number | float64 | 8字节，最大精度16位 | 10.24 |
字符串 | string | string | utf-8编码，长度不超过：
| "1024" |
数组 | array | list | 最多支持500个元素，元素数据类型支持 string，一个数组中所有元素类型需保持一致。 注意 数据落库时，会对 list 的元素进行去重，例如 [5,5,5] ，变成[5] ； [5,5,6] ，变成[5,6] ； [5,6,5] ，变成[5,6] 。 | ["10", "24"] |
日期时间 | string | datetime | 上报格式：
日期的取值范围：[1970, 2099] 说明 如果是形如 "2020-07-07 01:22:33" 的 datetime 上报，默认按应用级的时区； | "2020-10-24 23:47:12" |
版本 | string | string | 版本类数据的上报格式为：
系统发现上报数据的取值的格式匹配时，会自动将数据类型设置为版本类型。版本类型可按数值排序规则进行排序，也可进行大于及小于的运算符进行筛选。 注意 版本类型的数据在入库存储时，数据格式为string，在后续查询分析时会进一步处理为version类的数据，查询时支持的过滤条件为version类型数据支持的过滤条件。 | "10.2" |
其他类型 | object/boolean | string | 支持上报 object 和 boolean （bool：是/否）数据类型的数据，但会被转化成 string 进行存储。 | -- |
说明
当前DataFinder不支持直接采集上报嵌套JSON结构的数据，此场景下，当前建议通过转义的方式把JSON数据转成String后再上报。例如：
不同属性数据类型，可计算的指标
类别
分析功能
数据类型
计算方法
事件
事件分析
-（全部）
总次数
总人数
人均次数事件
分布分析
-（全部）
总次数
天数
小时数事件属性
通用
int
float按……求和
按……求平均值
按……求人均值
按……求分位数事件属性
通用
Int
float
string
list
datetime按……求去重数
按……和用户去重不同属性数据类型，作为筛选条件可用的操作符
类型
为空
不为空
=
≠
大于
小于
大于等于
小于等于
包含
不包含
正则匹配
字符串
✓
✓
✓
✓
✓
✓
✓
整型
✓
✓
✓
✓
✓
✓
✓
✓
浮点型
✓
✓
✓
✓
✓
✓
✓
✓
数组
✓
✓
✓
✓
日期时间
✓
✓
版本
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
✓
- 字符串类型可以选择“为空”和“不为空”用于匹配 null 或非 null。
- 日期类型属性有一个单独的筛选规则（如下表）：
操作符名称
说明
固定范围
所选属性的时间在一个固定的时间范围内，可以是过去365天到未来365天内的任何一天或多天。
在当前时间
所选属性的时间位于查询发起的时刻到用户所设定的相对时段之间。
可选条件：- 过去 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0）
- 未来 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
在今天和
所选属性的时间位于查询发起的当天（自然天）到用户所设定的相对天数（自然天）范围之间。
可选条件：- 过去 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0）
- 未来 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
在事件发生
所选属性的时间位于相对当前事件的发生时间的一段时间内。由于用到了事件的发生时间，所以仅当作为事件的过滤条件时才会出现这种操作符。
可选条件：- 当天、当周和当月：事件发生时所在的自然天、周或月
- 之前 {N} {天,秒,分,小时,周} 内（此时的天、周计算时不是自然天、自然周，而是相对事件发生时刻推算出的时刻）
- 之后 {N} {天 , 秒,分,小时,周} 内（同前）
N 的取值范围：
- 天：1 <= N <= 365（当前都按天级的限制执行）
- 秒：1 <= N <= 365
- 分：1 <= N <= 365
- 小时：1 <= N <= 168
- 周：1 <= N <= 52
说明
选择不同数据格式注意事项：
- 需要求和、平均值、按照区间范围筛选的必须要用int、float数值类型。
- 需要时间筛选条件的必须定义数据类型为datetime格式。
3.1 一般限制
- 单个应用的上报的事件数总量不限制；
- 单个应用支持元事件种类不超过1000个（不同应用之间互不影响，不含虚拟事件）；
- 单个事件的属性数量推荐300个以内，最多不超过500个（不同事件之间互不影响）；
- 用户属性的属性数量最多不超过 500个；
- 单个应用自定义事件公共属性数量不超过100个；
- 事件名建议不超过64个字符，最长不超过255个字符；
- 事件属性名和用户属性名称最长不超过64个字符；
- 属性值长度建议不超过255字符，特殊情况（如url等）SaaS-云原生最大支持2048字符、SaaS-非云原生最大支持1024字符；
- 事件属性名称禁止命名为user_unique_id、ssid、event_id；
- 属性名不允许和预置属性名称相同；预置属性文档可查看预置属性总表。
说明
超过上述限制时，超过的事件、属性数据可能会被系统自动丢弃。更多请查看数据入库明细（原数据质量）。
3.2 事件时间限制
使用客户端 SDK （iOS、Android）导入的数据，服务端默认只接收事件发生时间在接收时间向前 7 天内和向后24小时内数据。
3.3 命名限制
- events表中，同一个属性名，不允许存在多个属性类型，只有一种属性类型。
- users表中，同一个属性名，不允许存在多个属性类型，只有一种属性类型。
- 同一个属性名，如果在events和users表中同时存在，在两表中数据类型可以相同，也可以不同。
3.4 属性长度和范围的限制
中文名 | 数据库类型 | 额外说明 |
|---|---|---|
整数 | int64 | 取值范围：[-9223372036854775808, 9223372036854775807] |
浮点数 | float64 | 8字节，最大精度16位 |
字符串 | string |
|
版本(字符串) | version(string) | 格式：1. 2段~6段 2. 英文句点分隔 3. 每段最长5位 |
数组 | list | 最多支持500个元素，元素数据类型支持 string，一个数组中所有元素类型需保持一致。 |
日期时间 | datetime | 日期取值范围：[1970, 2099] |
DataFinder事件数据分为行为数据、用户属性数据、Item（业务对象）属性数据。数据处理主流程如下图所示，数据经过采集上报、内部数据分发、数据加工并最终数据落库，此外通过旁路的数据输出能力提供离线/实时的数据对接能力。
- 通过数据接入SDK或OpenAPI将数据采集上报的过程中，采集上报的数据格式详情可参见下文的数据采集上报格式章节。
- 私有化场景下，采集上报的埋点数据进入DataFinder并进行内部分发后支持通过Kafka进行订阅，Kafka订阅时的数据格式详情请参见下文的Kafka订阅数据格式章节。
- DataFinder会对采集上报的数据进行处理并落库存储，落库后的数据格式请参见下文的数据入库格式章节。
- DataFinder为您提供了数据输出功能，支持将采集到的数据进行输出，对外输出的数据格式请参见下文的数据对外输出格式章节。
数据采集上报格式
上报数据格式以一个JsonObject为基本单位，包含三个核心部分：
上报数据组成部分
详细说明
header
全局公共属性，和事件是一对多关系，一批上报的事件会对应同一份 header 公共属性。header 内容是以上报时的值为准，不以事件发生时的值为准，所以变化频繁和事件产生时强绑定的不建议在 header 中设置。
events
包含本次上报的所有事件list，events 为所有类型数据上报的主要信息载体，一般每个事件包含：
- event：事件名，部分场景做上报特殊数据的类型名
- params：数据内容，内容为json字符串或Json转义字符串(SaaS-非云原生只支持转义字符串)。parmas的键值在各上报事件中有所区别，在行为事件上报中为事件属性、预置属性和其对应的值。
（在iOS/安卓端，事件上报字段为event_v3，与events等价）
user
用户标识，内容为Json字符串，部分场景做特有类型上报标识
（部分SDK/客户端/Http OpenApi会使用user_unique_id 键值对的形式直接上报，字段位置也可能放入Header中）特殊说明
- 除了以上三部分外，各端/SDK在时间上报上会增加自己特有的key，详见各端/SDK的文档。
- 部分数据上报不遵循通用格式，使用API特定格式上报/更新数据，如非云原生的用户属性、Item属性更新。
上报数据示例：行为数据
Web JS SDK上报事件示例安卓端上报示例iOS端上报示例{ "events": [ { "event": "report-core", "params": "{"timePoints":8041,"pageChanged":false,"url":"https://datarangers-onpremise.volces.com/datafinder/project/1/overview","index":6,"event_index":1723194789910}", "local_time_ms": 1723194773504, "is_bav": 1, "session_id": "dc3b61d7-de7d-4f8d-b5bd-2f70******" }, { "event": "report-core", "params": "{"timePoints":7963,"pageChanged":false,"url":"https://e168-2-169.datarangers-onpremise.volces.com/datafinder/project/1/overview","index":3,"event_index":1723194789909}", "local_time_ms": 1723194773426, "is_bav": 1, "session_id": "dc3b61d7-de7d-4f8d-b5bd-2f707*******" } ], "user": { "user_unique_id": "1", "web_id": "73742566315817*****" }, "header": { "app_id": 666***, "os_name": "mac", "os_version": "10_15_7", "device_model": "Macintosh", "language": "zh-CN", "platform": "web", "sdk_version": "5.1.25", "sdk_lib": "js", "timezone": 8, "tz_offset": -28800, "resolution": "2304x1296", "browser": "Chrome", "browser_version": "126.0.0.0", "referrer": "", "referrer_host": "", "width": 2304, "height": 1296, "screen_width": 2304, "screen_height": 1296, "tracer_data": "{"$utm_from_url":1}", "custom": "{"product_name":"DataFinder","op_project_id":1,"op_project_name":"Q2套件联动项目","org_id":1,"org_name":"默认集团","overview_org_id":1,"custom_module_name":"overview"}" }, "local_time": 1723194773 } ```结合以上示例可见：
- header部分包含了应用所在操作系统、设备等应用视角全局公共属性；在web侧还包括应用标识app_id，安卓侧该信息包含在认证信息中，会在后续的数据流处理中填充。
- user部分，在安卓端，user信息以user_unique_id键值对方式放置到了header中；Web端包含两种用户标识：user_unique_id和web_id，用于在上报后生成/匹配Finder的用户唯一标识。
- events/event_v3 以list格式包含了多个行为事件，在每个事件中，event为行为名称， params里为事件的非全局详细属性，是多个键值对的Json字符串或Json转义字符串。
header、user、events/event_v3中部分信息为部分端/SDK上报自有属性，此部分上报时自动生成。
上报数据示例：用户属性数据
以下以SaaS-云原生和私有化场景下的用户属性数据上报示例为例：{ "user": { "user_unique_id": "74481585297" //用户唯一标示 }, "header": { "ab_sdk_version": "91223,83097", //AB实验vid "app_channel": "App Store", //App渠道 "app_name": "news_article", //App名称 "app_package": "com.ss.android.article.news", //App包名 "app_version": "5.1.3", //App版本 "client_ip": "10.100.1.1", //客户端ip地址 "device_model": "SM-G9250", //设备型号 "os_name": "Android", //操作系统 "os_version": "6.0.1", //操作系统版本 "traffic_type": "app" }, "events": [ { "event": "__profile_set", //操作名 "params": "{\"age\": 10}", //设置属性 "local_time_ms": 1489573628001 //事件发生的时间戳 }， { "event": "__profile_unset", //操作名 "params": "{\"name\":\"tom\"}", //设置属性 "local_time_ms": 1489573628001 //事件发生的时间戳 } ] }在此示例中，上报数据遵循了user、header、和events三段。
- events部分，第一个和第二个event 值代表了特定操作的名称而不是事件名，如__profile_set 表明是一个用户属性设置操作；
- params 为操作的数据内容。SaaS-云原生、私有化的上报具体见5.1 上报用户属性；SaaS-非云原生的上报请参见User Profile API（SaaS-非云原生）。
上报数据示例：Item属性数据
以下以SaaS-云原生和私有化场景下的用户属性数据上报示例为例：Item 属性上报示例Item事件关联上报示例{ "user": { "user_unique_id": "__rangers" // 业务对象上报，固定为__rangers }, "header": { "app_name": "8ca70e31ea744de18a1407a750c4e281" //app_name值，与app_id一一对应 }, "events": [ { "event": "__item_set", "params": "{"item_name":"Mobile_No","item_id":"item_test_002","device_model":"thinkphone"}", "local_time_ms": 1721735668446 } ] }在此示例中，上报数据遵循了user、header、和events三段：
- Item属性上报中，user_unique_id 不是用户标识含义，而是通过__rangers标识用户属性上报；
- 通过event的值__item_set表示为特定的数据操作，
- params中的值为一条Item的具体数据。Item 关联关系上报中，在params字段使用__items 表示此部分数据为配置事件video_play和Item的关联关系。 其余键值为普通行为事件属性上报。
Item属性数据上报详见业务维度（item）数据接入（SaaS-非云原生版），SaaS云原生版本和私有化版本接入请参考HTTP API文档中的6. 上报业务对象属性模块。
kafka订阅数据格式
此部分详见Kafka订阅埋点数据（私有化）。
数据入库格式
入库后可看到的数据格式分别如下：
私有化
{ "time": 1606301031, "server_time": 1606249381, "local_time_ms": 1606301031000, "device_id": "6912716898461553676", "os": "ios", "params": { "package": "package", "app_version": "1.0.6", "device_model": "iphone 6s plus", "timezone": "8.0", "os_version": "10.3.2", "session_depth_range": "5", "session_id": "762891435873043", "network_carrier": "TELCEL", "language": "zh", "exit_page": "http://datarangers.com.cn/pages/index/3", "product_name": "default_to_b", "resolution": "375x667", "platform": "ios", "loc_country_id": "1814991", "app_channel": "线下扫码下载", "device_brand": "苹果", "browser": "chrome", "os_name": "ios", "loc_province_id": "1280239", "session_duration_range": "100-200", "client_ip": "118.213.201.135", "loc_city_id": "1279540", "browser_version": "68.0.3440", "network_type": "mobile", "duration": 117, "session_depth": 5, "screen_width": 375, "localtime_ms": 1606301031000, "screen_height": 667, "session_duration": 117, "is_login": 1 } }SaaS
{ "user": { "ssid": "", // SSID "user_unique_id": "", // user_unique_id，存储于 string_profiles{'uuid'} "web_id": 0, // 网页端的匿名ID，存储于 string_profiles{'web_id'} "device_id": 0, // 移动端,小程序端的匿名ID "user_register_time": "" // 用户首次事件触发时间 }, "params": { "language": "zh-CN", "region": "", "app_version": "unknown", "app_region": "", "app_channel": "", "app_language": "", "os_version": "10", "os_name": "10", "device_model": "Windows NT 10.0", "device_brand": "", "network_type": "", "network_carrier": "" }, "items":{ "sku": [{ "id": "", "property_1": "", // 当前item定义的属性1 "property_1": "", // 当前item定义的属性2 }] }, "event_name": "predefine_pageview", "app_id": "2174", // string, rangers 中的应用id "app_name": "数据发现者", // string, rangers 中的应用名 "server_time": 1606783082, // int(timestamp), 服务端收到事件的时间, 精确到 ms "time": 1606783080, // int(timestamp), time = local_time_ms/1000，单位为秒。 "event_date": 1606783080 // date, 基于 time 计算，但只精确到天 }
数据对外输出格式
已经入库的数据，您可以在DataFinder上直接查询分析，也支持将数据输出到其他分析平台，例如将数据输出到您的数仓中。将数据输出时的数据格式请参见数据输出：SaaS-非云原生中的数据格式章节。
Q1：事件属性数据类型传输错误，需要修改怎么办？
描述：在业务迭代过程中，属性含义出现变化，或者上报过程中出现错误，需要修改怎么办？
A1 ：
第一步：管理员在产品前端界面修改，选择应用管理-数据管理。
第二步：找到对应属性名称。
图中预置属性（增长分析SDK默认采集的属性，无需手动上报）数据类型为灰色，表示不可修改。只有代码埋点过程中手动上报的属性，才可以修改属性类型。第三步：选择修改的属性类型。
系统会根据修改的数据类型进行提示，其中转换数据规则如下。仅针对事件属性，不适用于用户属性。原数据类型
原数据示例
新数据类型
新数据示例
历史数据
新数据
其他说明
值为数值类string
"1"
int
1
不丢失
按新数据类型上报，入库正常
允许修改，且历史数据不丢失，可以查询。
值为数值类string
"0.1"
float
0.1
不丢失
按新数据类型上报，入库正常
值为非数值类 string
"abc"
int
0
有损
按新数据类型上报，入库正常
float
0.1，0.61.1，1.7
int
向下取整（取小数点之前的整数），0.1，0.6会变成0；1.1和1.7会变成1。
不丢失
按新数据类型上报，入库正常
int
1
string
丢失
丢失
按新数据类型上报，入库正常
允许修改，但历史数据不再能查询，再变更回原类型，依然可用。比如string->int->string。
int
1
float
丢失
丢失
按新数据类型上报，入库正常
float
0.1
string
丢失
丢失
按新数据类型上报，入库正常
除上述表中，其他情况的转换，例如string-datetime，历史数据会丢失，按新数据类型上报，入库正常，并且不可转换为原类型，操作不可逆，请谨慎操作。
第四步：需要研发代码层面，按照新的数据格式进行上报。
注意
修改前端数据类型后，请及时修改代码，否则会有入库失败或者数据丢失。
Q2： 各端数据类型传输不一致，系统如何处理？如何修改？
描述：例如IOS端先传入A属性的格式为数值类型，安卓端后传入A属性的格式为字符串类型，此时系统如何处理，结果会如何？
A2：一个属性的类型由首次导入的数据类型决定，如果后续传入不同数据类型的数据，系统会尝试做转换，如果转换成功，则入库。如果转换失败，则属性信息值为‘0’入库，相当于属性信息丢失，但事件正常上报。
具体转换成功信息如下表：
原数据类型 | 新数据类型 | 是否转换成功 | 其他说明 |
|---|---|---|---|
int、float、datetime、list | string | 是 | |
数值型string，例如‘1’，‘0.1’ | int、float | 是 | 原数据类型虽为string，但是值为数字123456 |
float | int | 是 | 但是会丢失小数点后面的数据。 |
int | float | 是 | |
其余数据类型均转换失败。 |
注意
需要在数据校验侧规避这一问题，如果发生，请错误端及时调整数据格式，否则会引发数据丢失。
Q3： 是否接受时间戳string的上报，会自动解析成datetime格式吗？
A3：时间戳不支持，只支持日期时间的格式。
Q4：datetime是否接受按天级别格式的数据，"yyyy-MM-dd"
A4：不支持。支持的datetime上报格式为"yyyy-MM-dd HH:mm:ss"。
Q5： 埋点 设计时，如何选择正确的数据类型？
中文名 | 数据库类型 | 应用场景 |
|---|---|---|
整数 | int64 | 需要数值求和，平均值等计算，并且不会出现小数的情况。例如：年龄，整数金额。 |
浮点数 | float64 | 需要数值求和，平均值等计算，并且会出现小数的情况。例如：折扣金额，时长。 |
字符串 | string | 常用的文本类属性，例如：页面标题，按钮名称，商品分类。不需要计算的ID类型，例如：内容ID，商品ID。 |
数组 | list | 集合，一个属性有多个值，但筛选又需要按单个筛选的。例如：一篇娱乐新闻属于多个内容标签,{‘热门’，‘娱乐’，‘新闻’}例如：一个商品属于多个商品标签{'折扣'，‘秋季’，‘女性’} |
日期时间 | datetime | 需要按照日期范围筛选的 |
版本 | string | 需要对版本进行排序时 |
Q6：为什么会有版本相关字段取值为“xx”这种一段的取值格式，而不是“xx.xx”这类至少两段的取值格式？
默认情况下，系统在遇到被“.”切割为至少两段的数据时（例如 2.0），会自动判断其为版本类型。而对于已知的版本类型的字段，DataFinder会将这个限制放开，允许版本字段取值中没有”.“，例如：2 这样的值上报。
此类场景放开这个限制是因为在一些情况下，真实的版本号只有一段。当然对于这种情况，您也可以选择将版本号作为 int 类型上报。