事件协议
HealthGuard 的所有 SDK 都遵循统一的事件协议，事件定义在 @health-guard/core 中，使用 Zod Schema 进行校验。
批量上报
SDK 通过 POST /api/events/batch 批量上报事件。
请求体
json
{
"appKey": "web_abc123",
"events": [
{ /* event 1 */ },
{ /* event 2 */ }
]
}字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
appKey | string | 是 | 应用唯一标识，必须与每个事件的 appKey 一致 |
events | array | 是 | 事件数组，最少 1 条，最多 50 条 |
基础事件字段
所有事件类型都包含以下公共字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
eventId | string | 是 | 事件唯一 ID |
appKey | string | 是 | 应用唯一标识 |
platform | string | 是 | 平台类型，见下方枚举 |
timestamp | number | 是 | 事件发生时间戳（毫秒） |
sessionId | string | 是 | 会话 ID |
anonymousId | string | 是 | 匿名用户 ID |
sdkVersion | string | 是 | SDK 版本号 |
release | string | 否 | 应用版本号 |
environment | string | 否 | development / test / production |
userId | string | 否 | 业务用户标识 |
pageUrl | string | 否 | 当前页面 URL |
deviceInfo | object | 否 | 设备信息 |
platform 枚举
webwechat-miniprogramalipay-miniprogramflutteruniapp-h5uniapp-wechatuniapp-alipayuniapp-douyinuniapp-appuniapp
environment 枚举
developmenttestproduction
事件类型
error
错误事件用于上报 JS 错误、Promise rejection、资源加载失败、请求失败等。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 固定为 error |
errorType | string | 是 | js / promise / resource / request / native |
message | string | 是 | 错误摘要 |
stack | string | 否 | 错误堆栈 |
filename | string | 否 | 出错文件（浏览器环境） |
lineno | number | 否 | 行号 |
colno | number | 否 | 列号 |
fingerprint | string | 是 | Issue 聚合指纹 |
breadcrumbs | array | 是 | 面包屑数组 |
context | object | 否 | 自定义上下文，最多 20 个键 |
page | string | 否 | 页面路径 |
scene | string | 否 | 业务场景 |
http
HTTP 事件用于上报请求耗时、状态码和失败原因。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 固定为 http |
method | string | 是 | HTTP 方法 |
url | string | 是 | 请求 URL（已脱敏） |
status | number | 否 | HTTP 状态码 |
duration | number | 是 | 请求耗时（毫秒） |
success | boolean | 是 | 是否成功 |
errorMessage | string | 否 | 错误描述 |
fingerprint | string | 否 | Issue 聚合指纹 |
context | object | 否 | 自定义上下文，最多 20 个键 |
requestData | object | 否 | 请求数据，最多 20 个键 |
page | string | 否 | 页面路径 |
scene | string | 否 | 业务场景 |
performance
性能事件用于上报自定义性能指标或 Web Vitals 等数据。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 固定为 performance |
name | string | 是 | 指标名称 |
value | number | 是 | 指标数值 |
rating | string | 否 | good / needs-improvement / poor |
breadcrumb
面包屑事件用于显式记录用户操作或状态变更轨迹。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 固定为 breadcrumb |
breadcrumb.type | string | 是 | navigation / click / http / manual |
breadcrumb.message | string | 是 | 面包屑描述 |
breadcrumb.timestamp | number | 是 | 时间戳 |
breadcrumb.data | object | 否 | 附加数据 |
指纹生成
- 错误指纹：基于
errorType、message、堆栈前 two 行、以及context中的url/method/scene/page生成。 - HTTP 指纹：基于
method、URL pathname、status和platform生成。
指纹用于在 Collector 端将相似事件聚合为 Issue。
脱敏与限制
- URL Query 中的敏感键会被替换为
[Filtered]，敏感键包括：authorization、auth、cookie、password、secret、token、access_token、refresh_token。 context与requestData每层最多 20 个键。- request body 和 response body 默认不上报。