Events API
Submit user interaction events for tracking, analysis, and AI-powered optimization.
Endpoint
POST
/api/v1/eventsRequest Body
Events are submitted in batches for efficiency:
json
Event Fields
| Prop | Type | Default | Description |
|---|---|---|---|
eventId* | string | - | Unique identifier for this event (UUID recommended). |
appId* | string | - | Your m0rphic application ID. |
userId* | string | - | Identifier for the user who triggered the event. |
sessionId* | string | - | Session identifier for grouping related events. |
type* | EventType | - | Event type: "click", "view", "hover", "scroll", "submit", "error". |
componentId* | string | - | Identifier for the component that triggered the event. |
pageId* | string | - | Identifier for the page where the event occurred. |
zoneId | string | - | Zone identifier if the event occurred within a zone. |
timestamp* | number | - | Unix timestamp in milliseconds. |
viewport | { width: number, height: number } | - | Browser viewport dimensions. |
scrollDepth | number | - | Scroll depth percentage (0-100) for scroll events. |
metadata | Record<string, unknown> | - | Additional event-specific data. |
Event Types
clickUser clicked on a component. Include x/y coordinates in metadata.
viewComponent became visible in the viewport. Tracked via Intersection Observer.
hoverSignificant hover interaction (typically 1s+). Include timeSpent in metadata.
scrollUser scrolled to a certain depth. Include scrollDepth percentage.
submitForm or action was submitted. Include form data in metadata (excluding PII).
errorAn error occurred. Include errorMessage in metadata.
session_startNew session started.
session_endSession ended (page unload or timeout).
Response
Success (200)
json
Error (400)
json
Example Request
bash
Best Practices
Batch Events
The SDK automatically batches events (default: 10 events or 5 seconds). For server-side integration, batch events to reduce HTTP overhead.
Idempotency
Events are deduplicated by eventId. If you retry a failed request, use the same eventId to prevent duplicate events.
Privacy
Do not include PII (emails, names, addresses) in event metadata. Use hashed or anonymous identifiers.