事件协议
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 默认不上报。
相关文档
网络诊断（未发布源码）
2026-10-14 源码新增诊断与补传能力，配置方式、发布状态和不可用字段见 网络诊断。Flutter 接入见 Flutter SDK。
Flutter 原请求证据与 HTTP Issue 指纹（未发布）
HTTP 事件可在 context.originalError 保留原始 Dio 类型，在 context.requestTrace 保留 source: original_request、requestId、startedAt、timeouts、connectionAcquisition、responseHeaders 及明确不可用的 dns/tcp/tls。该字段由 SDK 白名单脱敏，不能用于任意业务载荷。它与 context.networkDiagnostics.probes 中的独立探测不同。
Collector 为新 HTTP 失败生成 http:v2:<hash>，依据方法、目标 origin、路径、状态、平台、环境与故障阶段，忽略请求编号、耗时、查询参数和客户端自定义指纹。历史已存指纹保留兼容，不自动改变修复关联。