Event Protocol

All HealthGuard SDKs follow a unified event protocol. Event schemas are defined in @health-guard/core and validated with Zod.

Batch Ingestion

SDKs report events in batches via POST /api/events/batch.

Request Body

{
  "appKey": "web_abc123",
  "events": [
    { /* event 1 */ },
    { /* event 2 */ }
  ]
}

Fields

Field	Type	Required	Description
appKey	string	Yes	Unique app identifier; must match every event's appKey
events	array	Yes	Event array; minimum 1, maximum 50 items

Base Event Fields

All event types share the following common fields:

Field	Type	Required	Description
eventId	string	Yes	Unique event ID
appKey	string	Yes	Unique app identifier
platform	string	Yes	Platform type; see enum below
timestamp	number	Yes	Event timestamp in milliseconds
sessionId	string	Yes	Session ID
anonymousId	string	Yes	Anonymous user ID
sdkVersion	string	Yes	SDK version
release	string	No	App version
environment	string	No	development / test / production
userId	string	No	Business user identifier
pageUrl	string	No	Current page URL
deviceInfo	object	No	Device information

Platform Enum

• web
• wechat-miniprogram
• alipay-miniprogram
• flutter
• uniapp-h5
• uniapp-wechat
• uniapp-alipay
• uniapp-douyin
• uniapp-app
• uniapp

Environment Enum

• development
• test
• production

Event Types

error

Error events report JS errors, promise rejections, resource failures, and request failures.

Field	Type	Required	Description
type	string	Yes	Always error
errorType	string	Yes	js / promise / resource / request / native
message	string	Yes	Error summary
stack	string	No	Error stack trace
filename	string	No	Failing file (browser)
lineno	number	No	Line number
colno	number	No	Column number
fingerprint	string	Yes	Issue aggregation fingerprint
breadcrumbs	array	Yes	Breadcrumb array
context	object	No	Custom context; max 20 keys
page	string	No	Page path
scene	string	No	Business scene

http

HTTP events report request duration, status code, and failure reason.

Field	Type	Required	Description
type	string	Yes	Always http
method	string	Yes	HTTP method
url	string	Yes	Request URL (sanitized)
status	number	No	HTTP status code
duration	number	Yes	Request duration in milliseconds
success	boolean	Yes	Whether the request succeeded
errorMessage	string	No	Error description
fingerprint	string	No	Issue aggregation fingerprint
context	object	No	Custom context; max 20 keys
requestData	object	No	Request data; max 20 keys
page	string	No	Page path
scene	string	No	Business scene

performance

Performance events report custom metrics or Web Vitals-like data.

Field	Type	Required	Description
type	string	Yes	Always performance
name	string	Yes	Metric name
value	number	Yes	Metric value
rating	string	No	good / needs-improvement / poor

breadcrumb

Breadcrumb events explicitly record user actions or state changes.

Field	Type	Required	Description
type	string	Yes	Always breadcrumb
breadcrumb.type	string	Yes	navigation / click / http / manual
breadcrumb.message	string	Yes	Breadcrumb description
breadcrumb.timestamp	number	Yes	Timestamp
breadcrumb.data	object	No	Additional data

Fingerprinting

• Error fingerprint: Based on errorType, message, the first two lines of the stack, and context fields url / method / scene / page.
• HTTP fingerprint: Based on method, URL pathname, status, and platform.

Fingerprints are used by the Collector to group similar events into Issues.

Sanitization & Limits

• Sensitive URL query keys are replaced with [Filtered]: authorization, auth, cookie, password, secret, token, access_token, refresh_token.
• context and requestData are limited to 20 keys each.
• Request and response bodies are not collected by default.

Related Docs

• Collector API
• H5 SDK
• WeChat Mini Program SDK
• uni-app SDK

Network diagnostics (unreleased source)

Source completed on 2026-10-14 adds network evidence and replay. See Network diagnostics for configuration, release status and unavailable fields, and Flutter SDK for Flutter integration.

Original Flutter evidence and HTTP issue fingerprints (unreleased)

HTTP context.originalError retains original Dio types. context.requestTrace can contain source=original_request, requestId, startedAt, timeouts, connectionAcquisition, responseHeaders and explicitly unavailable dns/tcp/tls. SDK privacy allowlists restrict this evidence; arbitrary business payloads are excluded. This is distinct from independent context.networkDiagnostics.probes samples.

For new HTTP failures the Collector generates http:v2:<hash> from method, target origin, path, status, platform, environment and failure phase. Request IDs, durations, queries and client-supplied fingerprints do not determine groups. Historical stored fingerprints remain compatible without automatically changing repair links.