事件协议

本文档定义 SDK 上报到 Collector 的事件数据结构，适用于所有平台 SDK（H5、微信小程序及未来平台）。

通用字段

每条事件必须包含以下通用字段：

字段	类型	必填	说明
eventId	string	是	事件唯一标识（UUID）
appKey	string	是	应用唯一标识
platform	string	是	平台：web / miniprogram / flutter
type	string	是	事件类型：error / http / performance / breadcrumb
timestamp	number	是	事件发生时间戳（毫秒）
sessionId	string	是	会话标识
anonymousId	string	是	匿名用户标识
sdkVersion	string	是	SDK 版本号
url	string	否	当前页面 URL（H5）或页面路径（小程序）
userAgent	string	否	用户代理信息
breadcrumbs	array	否	关联的面包屑列表

错误事件（type: error）

{
  "eventId": "evt_xxx",
  "appKey": "web_abc123",
  "platform": "web",
  "type": "error",
  "timestamp": 1716192000000,
  "sessionId": "sess_xxx",
  "anonymousId": "anon_xxx",
  "sdkVersion": "0.1.0",
  "errorType": "js",
  "message": "Cannot read property 'foo' of undefined",
  "stack": "TypeError: ...\n    at foo (app.js:12:3)",
  "fingerprint": "js:abc123",
  "url": "https://example.com/page",
  "breadcrumbs": []
}

error 专用字段

字段	类型	说明
errorType	string	错误类型：js / resource / promise / miniprogram
message	string	错误消息
stack	string	堆栈信息
fingerprint	string	错误指纹，用于聚合相同错误
filename	string	发生错误的文件（如有）
lineno	number	行号（如有）
colno	number	列号（如有）

指纹生成规则

fingerprint 用于将相同错误聚合成一个 Issue：

• JS 错误：js:${hash(errorType + 脱敏后的 message + 脱敏后的 stack 首行)}
• 资源错误：resource:${hash(url)}
• Promise 错误：promise:${hash(message)}

hash 算法建议：取前 16 位 MD5 或 murmur3。

HTTP 事件（type: http）

{
  "eventId": "evt_xxx",
  "appKey": "web_abc123",
  "platform": "web",
  "type": "http",
  "timestamp": 1716192000000,
  "sessionId": "sess_xxx",
  "anonymousId": "anon_xxx",
  "sdkVersion": "0.1.0",
  "method": "POST",
  "url": "https://api.example.com/users",
  "status": 500,
  "duration": 245,
  "success": false,
  "errorMessage": "Internal Server Error"
}

http 专用字段

字段	类型	说明
method	string	HTTP 方法：GET / POST / PUT / DELETE 等
url	string	请求 URL（已脱敏）
status	number	HTTP 状态码
duration	number	请求耗时（毫秒）
success	boolean	是否成功（status < 400）
errorMessage	string	失败原因（超时、网络错误等）

性能事件（type: performance）

{
  "eventId": "evt_xxx",
  "appKey": "web_abc123",
  "platform": "web",
  "type": "performance",
  "timestamp": 1716192000000,
  "sessionId": "sess_xxx",
  "anonymousId": "anon_xxx",
  "sdkVersion": "0.1.0",
  "metricName": "LCP",
  "value": 1200,
  "rating": "good"
}

performance 专用字段

字段	类型	说明
metricName	string	指标名：LCP / FID / CLS / FCP / TTFB / INP
value	number	指标数值
rating	string	评级：good / needs-improvement / poor

面包屑事件（type: breadcrumb）

面包屑通常作为其他事件的附属数据，也可独立上报：

{
  "eventId": "evt_xxx",
  "appKey": "web_abc123",
  "platform": "web",
  "type": "breadcrumb",
  "timestamp": 1716192000000,
  "sessionId": "sess_xxx",
  "anonymousId": "anon_xxx",
  "sdkVersion": "0.1.0",
  "breadcrumbType": "navigation",
  "message": "User navigated to /checkout",
  "data": { "from": "/cart", "to": "/checkout" }
}

breadcrumb 专用字段

字段	类型	说明
breadcrumbType	string	类型：navigation / click / console / custom
message	string	描述信息
data	object	附加数据

批量上报格式

SDK 通过 POST /api/events/batch 批量上报，请求体格式：

{
  "appKey": "web_abc123",
  "events": [
    { /* error event */ },
    { /* http event */ },
    { /* performance event */ }
  ]
}

约束：

• events 数组最少 1 条，最多 50 条
• 建议批量上报间隔 3-5 秒，或达到 10 条时立即上报
• 上报失败时本地队列保留，按指数退避重试

数据脱敏规则

SDK 在上报前必须对以下字段脱敏：

数据位置	规则
URL query	移除 authorization、password、token、secret、cookie 等参数的值
HTTP body	不上报 request body 和 response body
堆栈信息	移除 URL 中的 query 参数
用户信息	使用业务传入的 userId 或匿名 ID，不采集真实身份