一句话回答
事件结构(event schema)是一个分析事件的书面合同:事件名、携带的属性、每个属性的类型、哪些必填——在发出任何数据之前写下来,并在数据进来时校验。
公式: 必填属性完整度 = 符合 schema 的到达数 ÷ 总到达数(按事件、按时间窗口)
什么是事件结构(event schema)?
事件结构(event schema)是一个分析事件的书面合同:事件名、携带的属性、每个属性的数据类型、哪些属性必填。这份合同在发出任何数据之前就要谈好,之后每条到达的事件都要按它检查。比如结账事件约定必须带 order_id(字符串,必填)和 value(数字,必填),那么一条没带 order_id、或者把 value 发成 "40.00" 字符串的事件,就是违约——不只是"数据有点乱"。
"schema"这个词来自数据库设计:表结构在插入数据之前就固定了列和类型。而分析事件是灵活的 JSON 载荷,开发者随时可以加属性、改名、改类型,没有任何机制拦着。事件结构的作用就是把数据库式的保证补回来:一个固定、可评审的结构,发数据的人和查数据的人都以它为准。Amplitude 的埋点方案文档描述的是同一件事——事件和属性在埋码之前先定义好,带说明、类型、规则和必填标记。
事件结构里要写哪些字段?
一份 schema 至少要有:事件名、触发时机、带类型和必填标记的属性列表。要能驱动校验、能找到负责人,还需要再多几个字段:
| 字段 | 记录什么 | 示例 |
|---|---|---|
| 事件名 | 载荷里发送的精确字符串 | order_completed |
| 显示名 | 报表里给人看的名称 | 订单完成 |
| 说明 / 触发时机 | 什么时候发、按什么去重 | 每笔支付成功的订单发一次,在支付确认之后 |
| 分类 | 浏览方案时的分组 | 电商 |
| 平台 | 哪些 SDK 会发它 | web、ios、android |
| 属性:名称 | 精确的属性键名 | value |
| 属性:类型 | 数据类型,取自 JSON 类型集合 | number |
| 属性:是否必填 | 每条到达都必须带吗? | 是 |
| 属性:说明 + 示例 | 含义和一个样例值 | 订单金额(美元);40.00 |
| 负责人 | 这个事件有问题找谁 | 支付团队 |
| 状态 | 生命周期阶段 | 待评审 → 开发中 → 验收中 → 已上线 → 已废弃 |
| 版本 | 用于追踪变更的 schema 版本号 | 2 |
类型字段不是摆设。多数校验工具基于 JSON Schema 规范,它定义了一小组封闭的基本类型(string、number、boolean、object、array、null),并用 required 关键字列出必须出现的属性键。按这套词汇写的 schema 可以被机器检查;写成"value:价格"的 schema 不能。
把开头那段合同写成机器可校验的示例(示例数据):
{
"event": "order_completed",
"version": 2,
"trigger": "once per paid order, after payment confirmation",
"platforms": ["web", "ios", "android"],
"owner": "payments-team",
"status": "live",
"properties": {
"order_id": { "type": "string", "required": true, "example": "ord_8841" },
"value": { "type": "number", "required": true, "example": 40.00 },
"currency": { "type": "string", "required": true, "enum": ["USD", "EUR"] },
"coupon": { "type": "string", "required": false, "example": "FALL10" }
}
}
三个必填属性、一个可选属性。这个文件里的每个字段都为了同一个目的:让校验器——或者一位新工程师——不用去问原作者,就能回答"这条到达对不对"。
事件结构、埋点方案、数据字典的区别
这三个词经常被混着用,团队于是对着错误的文档争论。它们在不同层级:
| 产物 | 范围 | 粒度 | 通常由谁维护 |
|---|---|---|---|
| 事件结构 | 一个事件 | 事件名、属性、类型、必填标记、触发时机 | 拥有这个事件的团队 |
| 埋点方案 | 产品里的全部事件 | 所有 schema 的集合 + 分类、负责人、平台、状态 | 分析或数据治理负责人 |
| 数据字典 | 共享词汇 | 跨事件复用的属性和指标的规范定义 | 分析团队 + 各业务负责人 |
实用的判断规则:两个事件都带 currency 时,字典规定 currency 指 ISO 4217 货币代码;每个事件的 schema 决定该事件是否必填它;方案记录这两个事件都存在、各归谁管。本文只讲 schema 这一层——方案本身怎么建,见创建埋点方案。
让 schema 稳定下来的命名规范
名字可预测,schema 才可执行。四条规则能挡住大部分损害:
- 定一种模式——对象_动作——和一种大小写。
order_completed、signup_started、search_submitted。评审时,读起来不是"名词 + 过去式动词"的名字就打回。同一个动作混用OrderCompleted、order-completed和purchase,会造出三个任何漏斗都拼不起来的事件。更大范围的命名和分组决策属于数据分类体系。 - 每个属性只留一种规范拼写。
value、revenue、amount三选一——在字典里定一次——然后所有 schema 都用它。iOS 发order_value、web 发value,聚合就会悄悄裂成两半。 - 不要把可变的值编进事件名。用
order_completed加一个plan属性,而不是order_completed_pro和order_completed_enterprise。名字里出现套餐、国家、实验编号,这些内容就该放进属性。 - 类型是名字含义的一部分。
value永远是数字,不能是格式化字符串。某个平台的 SDK 把价格序列化成字符串,就在埋码时转换——不要"到报表里再修"。
算例:必填属性完整度
下面用数字说明:合同里"进来时校验"这一半不做,代价是什么。示例数据:一家网店从 web 和 iOS 发送 order_completed,上面的 schema 要求 order_id、value、currency 三个必填属性。一天到达 15,000 条事件:
| 平台 | 到达数 | 实际发来的是什么 | 符合 schema 的到达数 |
|---|---|---|---|
| Web | 12,000 | 符合 schema,只有 1,125 条缺 currency | 12,000 − 1,125 = 10,875 |
| iOS | 3,000 | 旧版 SDK:发的是 orderId 而不是 order_id,value 是字符串("40.00"),完全没有 currency | 0 |
必填属性完整度 = 符合 schema 的到达数 ÷ 总到达数:
- Web:10,875 ÷ 12,000 = 90.6%(90.625%,四舍五入到一位小数)
- iOS:0 ÷ 3,000 = 0%
- 整体:(10,875 + 0) ÷ 15,000 = 72.5%
没有任何报错。看板照样显示 15,000 笔"订单"——但所有基于必填属性的报表都在悄悄丢掉不合格的那部分。设平均客单价 40 美元,按符合 schema 的事件算收入是 10,875 × $40 = $435,000,而不是 15,000 × $40 = $600,000。差额是 15,000 − 10,875 = 4,125 条(iOS 的 3,000 条全部违约,加上 web 缺 currency 的 1,125 条):4,125 × $40 = 每天 $165,000 的收入被隐形吞掉。而 web 和 iOS 的转化对比也失去意义——其中一个平台的事件根本不达标。
现在把合同执行到位:先写 schema,到达校验标出 iOS 旧包,修复 SDK,补上 web 缺失的 currency。次日同样到达 15,000 条:
- Web:11,960 条合格(仍有 40 条缺
currency,被校验抓到)→ 99.7% - iOS:2,950 条合格(50 条来自还没升级的旧包设备)→ 98.3%
- 整体:(11,960 + 2,950) ÷ 15,000 = 14,910 ÷ 15,000 = 99.4%
完整度从 72.5% 升到 99.4%,回升 26.9 个百分点——没有多采集一条新事件。数据一直都在;是合同让它变得可用。这就是"发数据之前写下 schema、数据进来时校验"的全部理由:同一套埋点,产出可信数字还是误导性数字,只取决于合同有没有被执行。
改 schema 而不弄坏报表:版本管理
产品变,schema 就得变。目标是让每个变更在上线前就能被归类:
| 变更 | 破坏兼容? | 版本号 | 该怎么做 |
|---|---|---|---|
加一个可选属性(coupon) | 否 | 小版本:2 → 2.1 | 直接上,在变更记录里写一笔 |
| 加一个必填属性 | 是——旧 SDK 包过不了校验 | 大版本:2 → 3 | 先按可选发布,等旧包流量消退后再改必填 |
改属性类型(value 字符串 → 数字) | 是 | 大版本 | 新版本 + 切换前修好所有发送端 |
属性改名(orderId → order_id) | 是 | 大版本 | 过渡期内两个键都发,之后再删旧键 |
| 下线或废弃事件 | 是 | 大版本 / 状态变更 | 标记已废弃,保留可查直到报表迁移完 |
让这张表落地靠两条规则。其一:如果一个变更会让昨天的到达按今天的 schema 判为不合格,它就是破坏性的——"只是改个名"也不例外。其二:破坏性变更的过渡期要按更新最慢的平台来定——web 的发布你自己控制,但移动用户可能在旧 SDK 包上停留几个月,上面算例里的 iOS 漂移正是这么来的。
事件结构的常见误区
- 把 schema 当成上线后补的文档。检验方法:校验器能读你的 schema 并拒收坏载荷吗?如果它躺在幻灯片里,那是愿望,不是合同。
- 让每个平台自己发明拼写。检验方法:对同一个事件,比对 web 和 iOS 实际到达的属性键。任何差异都是未来的少计——上面的算例正是因此每天丢 3,000 笔 iOS 订单。
- 不标必填。全部可选,完整度就无法定义,校验也无从查起。定下所有报表都依赖的那两三个属性,标成必填。
- 改含义不改版本。
value开始含税,所有历史对比就悄悄失真。升大版本,并标注变更日期,让分析师能把序列切开。 - 上线时校验一次,之后不管。漂移是跟着下一个 SDK 版本来的,不是上线时来的。完整度需要按天或滚动窗口的例行检查,不是一次性审计。这类持续检查属于数据质量工作;与 schema 设计相互影响的数据粒度选择,见数据粒度。
在 TapCub 里校验事件结构
把算例里那家网店放进 TapCub:合同写在一个地方,事件进来时就对照检查,iOS 的漂移当天就能看到。
- 上线前先写合同。 在 全端分析 › 数据管理 › 埋点方案 里登记
order_completed:显示名、分类、平台(web、ios)、触发时机、负责人、状态。每个属性填名称、类型、是否必填、说明和示例,order_id(字符串,必填)、value(数值,必填)、currency(字符串,必填)和上面的字段表一一对应。SDK 还没发事件时,方案里就可以先有这一条;工程师开发期间把状态设为「开发中」。 - 事件一到就看完整度。 打开「实时验证(近 24 h)」,这一行会显示 15,000 次命中,必填属性完整度明显偏低,也就是算例里 72.5% 的那一天。追查期间把状态改成「验收中」;完整度低只是提示,本身不会拦下事件。
- 找出是哪个发送端坏的。 全端分析 › 数据管理 › 属性字典 每天扫描,列出每个属性键的类型、样例和最后出现时间,
order_id旁边冒出一个新的orderId,矛头直接指向旧版 iOS。再给value加一条校验规则(期望类型:数值),处置选「仅告警」,每个字符串"40.00"都会在 全端分析 › 数据管理 › 数据质量 记一条告警,而不是在收入里留下一个无声的缺口。 - 审核野事件名,别让它把数据劈开。 有人发了
OrderCompleted,它会以「未规划」出现在 全端分析 › 数据管理 › 事件收件箱。它照常入库,所以收件箱是一个审核队列:要么改代码,要么把这个定义设为「已拦截」,从此不再入库。
边界:TapCub 能告警、删除属性、拦截整条事件或放进隔离区,但不能把 orderId 改成 order_id,也不能把 "40.00" 变成 40。修好载荷是你团队的事;TapCub 负责在一天之内告诉你合同坏了、坏在哪里。这就是核心观点的落地:在发数据之前写好结构,每条到达的数据都按它验证。
资料来源
- Amplitude 文档,Create a tracking plan——事件与属性的元数据、必填标记、类型和规则。
- Amplitude 文档,Protect your schema from unexpected data——对计划外事件、属性和属性值做标记或拒收。
- JSON Schema,object——
required关键字与属性定义。 - JSON Schema,Type-specific keywords——JSON 基本类型集合。
这个解释清楚吗?
我们会根据反馈修改和补充这篇内容。
提交没有成功,请稍后再试。
谢谢你的反馈,我们会据此改进这篇内容。你已经反馈过这篇了,谢谢。
