Events API

Submit user interaction events for tracking, analysis, and AI-powered optimization.

Endpoint

POST/api/v1/events

Request Body

Events are submitted in batches for efficiency:

json

Event Fields

PropTypeDefaultDescription
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.
zoneIdstring-Zone identifier if the event occurred within a zone.
timestamp*number-Unix timestamp in milliseconds.
viewport{ width: number, height: number }-Browser viewport dimensions.
scrollDepthnumber-Scroll depth percentage (0-100) for scroll events.
metadataRecord<string, unknown>-Additional event-specific data.

Event Types

click

User clicked on a component. Include x/y coordinates in metadata.

view

Component became visible in the viewport. Tracked via Intersection Observer.

hover

Significant hover interaction (typically 1s+). Include timeSpent in metadata.

scroll

User scrolled to a certain depth. Include scrollDepth percentage.

submit

Form or action was submitted. Include form data in metadata (excluding PII).

error

An error occurred. Include errorMessage in metadata.

session_start

New session started.

session_end

Session 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.