事件架构
事件架构描述项目应接收哪些事件以及它们带有哪些属性:order_completed 必须带有数字类型的金额,currency 只能是 EUR 或 USD。OneTrace.pro 会将每个事件与架构比对并显示违规:事件名称拼写错误、金额以字符串传入、缺少属性。网站或集成的埋点错误能立即被发现,而不是等到分群或报表已经算错之后。
违反架构的事件仍会被接收并写入档案:即使是架构本身有误,数据也不会丢失。事件架构从“增长版”套餐起提供。
如何描述事件
打开数据目录的事件架构选项卡。具有“管理事件目录”权限的角色(“经理”及以上)可以修改架构,其他角色可以查看架构和违规。
- 点击添加现有事件,目录中的所有事件会连同其属性和识别出的类型一起加入架构。也可以用添加事件按钮逐个添加。
- 检查每个事件的属性:
| 列 | 设置内容 |
|---|---|
| 属性 | 网站或服务器发送的属性键,例如 amount |
| 类型 | 文本、数字、是/否、日期时间、列表或对象。日期时间值也符合文本类型的属性 |
| 必填 | 事件缺少该属性或其值为空即为违规 |
| 允许值 | 用逗号分隔,仅适用于文本和数字。不在列表中的值即为违规;区分大小写:eur 和 EUR 是不同的值 |
| 描述 | 供开发人员参考:该属性的含义 |
- 删除不应再出现的事件和属性:如果它们再次传入,会产生“未描述的事件”或“未描述的属性”违规。
- 点击保存架构,并开启按架构校验事件。
更改会先累积在页面上,然后一起保存。保存后违规计数会重新开始:之前的计数属于旧架构。在事件选项卡中,架构里尚未收到过的事件标记为“尚未收到”,架构中的事件带有“已在架构中”标记。

平台系统事件($identify、$page、$message_sent 等)以及 identify、页面浏览和应用屏幕浏览不做校验:它们的架构由平台定义。
违规
| 违规 | 示例 |
|---|---|
| 未描述的事件 | 传入的是 product_viewd,而不是 product_viewed |
| 未描述的属性 | order_completed 带有架构中没有的属性 coupon |
| 缺少必填属性 | add_to_cart 没有 quantity |
| 类型错误 | 金额以字符串 "1250" 传入,而不是数字 1250 |
| 不允许的值 | currency = eur,而架构中为 EUR 和 USD |
近 7 天的违规显示在架构事件列表上方:次数、最近一次的时间,以及示例——值的类型或不允许的值本身。没有查看个人数据的权限时,示例会被脱敏。如果事件未描述是架构的疏漏而不是埋点错误,请点击加入架构,该事件会连同目录中的属性一起加入草稿。
同样的违规以及 24 小时内违规事件的图表也显示在诊断中。

导入、导出和 API
导出 JSON 会下载已保存的架构,导入 JSON 会将文件加载到草稿中,请检查后保存。这样可以在项目之间迁移同一份架构,例如应用到连锁店的所有门店,或从测试项目迁移到正式项目。
通过公开 API 可以读取架构(GET /api/v1/event-schema)和整体替换架构(PUT /api/v1/event-schema,需要密钥权限“修改事件架构”),用 GET /api/v1/event-schema/violations 请求可获取近一周的违规。文件和 API 使用相同的格式:
{
"enabled": true,
"events": [
{
"name": "order_completed",
"label": "已下单",
"properties": [
{ "key": "amount", "type": "number", "required": true },
{ "key": "currency", "type": "string", "required": true, "values": ["EUR", "USD"] }
]
}
]
}
文档中没有的事件会退出架构,但仍保留在数据目录中,其显示名称和统计数据不变。不含 events 的文档只会开启或关闭校验。