Skip to main content

Event model

Nexly events have a consistent shape across web, mobile, and backend SDKs. Understanding the event model helps when you inspect the Events page, design custom events, or use API data.

Event type​

event_type describes the broad kind of event.

Common types include:

  • pageview for web routes and mobile screenviews.
  • engagement for interaction and active-time signals.
  • custom for product events you define.
  • navigation for route movement when captured separately.

Event name​

event_name is the specific name inside a type.

For custom events, this is the name you send with customEvent(...), such as checkout_completed or invite_sent.

Context​

context describes where and how the event happened: route or screen path, standard marketing attribution, and visitor/session identifiers.

Browser SDKs attach visitor_id and session_id to every event automatically. Backend events from @nexly/node only carry those fields when you pass them in context — for example after your browser code forwards getVisitorId() to your server. See Link browser and backend events.

Context is not a free-form bag. Besides the identifier and path fields above, it accepts a fixed set of attribution keys: utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, gad_source, gad_campaignid, fbclid, msclkid, ttclid, li_fat_id, yclid, mc_cid, and ref.

:::warning Unknown context keys are dropped silently

Any key outside this list is not stored and does not surface under Discovered. Standard attribution belongs in context; your own product parameters — including internal campaign, promo, or affiliate codes — belong in custom data (cdata), where they are stored as custom properties.

:::

Built-in data​

data is reserved for SDK-generated metrics and event details. Examples include scroll depth, click metadata, active seconds, or lifecycle information.

Do not use built-in data for product-specific custom properties.

Custom data​

cdata is the custom-data slot for your product properties on custom events.

Example:

client.customEvent('checkout_completed', {
  plan_id: 'startup',
  amount_cents: 4900,
  currency: 'USD',
})

Custom data must be flat scalar values: strings, numbers, or booleans.

Client source​

Each SDK sets a client source that identifies the runtime, such as web, React, Next.js, React Native, or Node.js. Application code does not need to set this field manually.

The Technology widget uses client source to show where traffic came from.

Sensitive data​

Avoid sending emails, tokens, passwords, precise addresses, or user identifiers in paths, event names, custom property keys, or custom property values.

Use stable route-style paths such as /pricing or /account/billing, and put only analytics-safe product metadata in custom data.