TapCub 正式上线:统计、分析、客服一个平台免费用
术语表

事件结构(Event Schema):定义、示例与校验

事件结构是一个分析事件的书面合同:事件名、属性、类型、哪些必填,在发数据之前写下来,并在数据进来时校验。本文给出字段表、JSON 示例和一道能复算的属性完整度算例。

卢卡斯·海斯 审核人 陈屿 又称 事件定义 最后更新 2026 年 11 月 16 日 术语表

一句话回答

事件结构(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 才可执行。四条规则能挡住大部分损害:

  1. 定一种模式——对象_动作——和一种大小写。order_completed、signup_started、search_submitted。评审时,读起来不是"名词 + 过去式动词"的名字就打回。同一个动作混用 OrderCompleted、order-completed 和 purchase,会造出三个任何漏斗都拼不起来的事件。更大范围的命名和分组决策属于数据分类体系。
  2. 每个属性只留一种规范拼写。value、revenue、amount 三选一——在字典里定一次——然后所有 schema 都用它。iOS 发 order_value、web 发 value,聚合就会悄悄裂成两半。
  3. 不要把可变的值编进事件名。用 order_completed 加一个 plan 属性,而不是 order_completed_pro 和 order_completed_enterprise。名字里出现套餐、国家、实验编号,这些内容就该放进属性。
  4. 类型是名字含义的一部分。value 永远是数字,不能是格式化字符串。某个平台的 SDK 把价格序列化成字符串,就在埋码时转换——不要"到报表里再修"。

算例:必填属性完整度

下面用数字说明:合同里"进来时校验"这一半不做,代价是什么。示例数据:一家网店从 web 和 iOS 发送 order_completed,上面的 schema 要求 order_id、value、currency 三个必填属性。一天到达 15,000 条事件:

平台到达数实际发来的是什么符合 schema 的到达数
Web12,000符合 schema,只有 1,125 条缺 currency12,000 − 1,125 = 10,875
iOS3,000旧版 SDK:发的是 orderId 而不是 order_id,value 是字符串("40.00"),完全没有 currency0

必填属性完整度 = 符合 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 的漂移当天就能看到。

  1. 上线前先写合同。 在 全端分析 › 数据管理 › 埋点方案 里登记 order_completed:显示名、分类、平台(web、ios)、触发时机、负责人、状态。每个属性填名称、类型、是否必填、说明和示例,order_id(字符串,必填)、value(数值,必填)、currency(字符串,必填)和上面的字段表一一对应。SDK 还没发事件时,方案里就可以先有这一条;工程师开发期间把状态设为「开发中」。
  2. 事件一到就看完整度。 打开「实时验证(近 24 h)」,这一行会显示 15,000 次命中,必填属性完整度明显偏低,也就是算例里 72.5% 的那一天。追查期间把状态改成「验收中」;完整度低只是提示,本身不会拦下事件。
  3. 找出是哪个发送端坏的。 全端分析 › 数据管理 › 属性字典 每天扫描,列出每个属性键的类型、样例和最后出现时间,order_id 旁边冒出一个新的 orderId,矛头直接指向旧版 iOS。再给 value 加一条校验规则(期望类型:数值),处置选「仅告警」,每个字符串 "40.00" 都会在 全端分析 › 数据管理 › 数据质量 记一条告警,而不是在收入里留下一个无声的缺口。
  4. 审核野事件名,别让它把数据劈开。 有人发了 OrderCompleted,它会以「未规划」出现在 全端分析 › 数据管理 › 事件收件箱。它照常入库,所以收件箱是一个审核队列:要么改代码,要么把这个定义设为「已拦截」,从此不再入库。

边界:TapCub 能告警、删除属性、拦截整条事件或放进隔离区,但不能把 orderId 改成 order_id,也不能把 "40.00" 变成 40。修好载荷是你团队的事;TapCub 负责在一天之内告诉你合同坏了、坏在哪里。这就是核心观点的落地:在发数据之前写好结构,每条到达的数据都按它验证。

另见:什么是数据校验?检查类型、在哪一步做和一个算例。

另见:什么是数据模型?分层、类型和事件模型示例。

资料来源

这个解释清楚吗?

我们会根据反馈修改和补充这篇内容。

卢卡斯·海斯

数据工程师

聚焦事件设计、数据质量与采集流程,分享可验证的实施方法,帮助团队建立可靠的分析基础。

常见问题

常见追问

大家看完定义后最常问的几个问题。

还有其他问题?

直接和 TapCub 团队聊聊——工作日通常几小时内回复。

事件结构和埋点方案有什么区别?

事件结构定义一个事件:事件名、属性、类型、哪些必填。埋点方案是所有事件结构的集合,再加上分类、负责人、平台、生命周期状态这些组织信息。可以理解为:事件结构是一行,埋点方案是整张表。

事件不符合 schema 时会发生什么?

取决于有没有校验。没有校验时,事件照样入库,悄悄污染报表:必填属性缺失、类型不对、名字重复。有校验时,不符合的事件会被标记、隔离或拒收,问题在还能修的阶段就暴露出来。

事件结构应该多久更新一次?

产品改变了事件的含义或携带内容时就更新,不按固定周期。加一个可选属性是不破坏兼容的小改动;删掉必填属性或改类型是破坏性变更,需要新版本、迁移说明和一段废弃过渡期。

事件结构能自动校验吗?

能。结构化的 schema 可以驱动运行时校验:逐条检查到达事件的事件名、属性是否齐、类型对不对,并按事件输出完整度。例如 Amplitude 的 schema 设置可以对违反方案的计划外事件、属性和属性值做标记或拒收。

在你自己的网站上看这个数字

加一行脚本就能开始,网站和 App 都能接,几分钟内就能看到第一批报表。

看清数据,找到增长。

每一次点击,都有数据依据。装好一行代码,1 分钟看到第一批数据。

无需信用卡 · 统计与客服都有免费版 · 统计无 Cookie