Event Protocol

This document defines the event data structure reported from SDK to Collector. It applies to all platform SDKs (H5, WeChat Mini Program, and future platforms).

Common Fields

Every event must include the following common fields:

Field	Type	Required	Description
eventId	string	Yes	Unique event identifier (UUID)
appKey	string	Yes	Unique app identifier
platform	string	Yes	Platform: web / miniprogram / flutter
type	string	Yes	Event type: error / http / performance / breadcrumb
timestamp	number	Yes	Event timestamp in milliseconds
sessionId	string	Yes	Session identifier
anonymousId	string	Yes	Anonymous user identifier
sdkVersion	string	Yes	SDK version
url	string	No	Current page URL (H5) or path (mini program)
userAgent	string	No	User agent string
breadcrumbs	array	No	Associated breadcrumb list

Error Event (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-specific Fields

Field	Type	Description
errorType	string	Error type: js / resource / promise / miniprogram
message	string	Error message
stack	string	Stack trace
fingerprint	string	Error fingerprint for grouping identical errors
filename	string	Error file (if available)
lineno	number	Line number (if available)
colno	number	Column number (if available)

Fingerprint Rules

fingerprint is used to aggregate identical errors into a single Issue:

• JS errors: js:${hash(errorType + sanitized message + sanitized first stack line)}
• Resource errors: resource:${hash(url)}
• Promise errors: promise:${hash(message)}

Recommended hash: first 16 chars of MD5 or murmur3.

HTTP Event (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-specific Fields

Field	Type	Description
method	string	HTTP method: GET / POST / PUT / DELETE etc.
url	string	Request URL (sanitized)
status	number	HTTP status code
duration	number	Request duration in milliseconds
success	boolean	Whether successful (status < 400)
errorMessage	string	Failure reason (timeout, network error, etc.)

Performance Event (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-specific Fields

Field	Type	Description
metricName	string	Metric name: LCP / FID / CLS / FCP / TTFB / INP
value	number	Metric value
rating	string	Rating: good / needs-improvement / poor

Breadcrumb Event (type: breadcrumb)

Breadcrumbs are usually attached to other events but can also be reported independently:

{
  "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-specific Fields

Field	Type	Description
breadcrumbType	string	Type: navigation / click / console / custom
message	string	Description
data	object	Additional data

Batch Ingestion Format

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

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

Constraints:

• events array must contain 1–50 items
• Recommended batch interval: 3–5 seconds, or flush immediately at 10 items
• On failure, keep events in local queue and retry with exponential backoff

Sanitization Rules

SDKs must sanitize the following before reporting:

Data Location	Rule
URL query	Remove values for authorization, password, token, secret, cookie
HTTP body	Do not report request body or response body
Stack trace	Remove query parameters from URLs in frames
User info	Use business-provided userId or anonymous ID; do not collect real identity