Events, fields & React hooks

Install, init, and walkthrough examples live in Overview & setup. This page is the reference for trackEvent, every event_name, and React hooks.

Tracking events

trackEvent sends one event or up to 50 in a single call. Which fields you can include depends on event_name.

const result = await analytics.trackEvent(input)
// input: one event or a list of events

event | list of events

required

A single event, or a list of up to 50 events in one call. An empty list returns immediately with accepted: 0 and does not contact the API.

Shared fields

Optional on every event below — you do not repeat them in each accordion. Use them when a screen or milestone should appear as a funnel step in reporting.

boolean

When true, marks this event as a funnel step. Omit or leave false for ordinary page views or minor events.

string

Human-readable step name in dashboards (max 128 characters). Meaningful when is_funnel_step is true — e.g. "Shipping" or "Payment".

Events

Expand an event for an example and field details. React is the analytics() module factory and the track hooks. JavaScript lists every event you can send from initAnalytics. Server lists events you can send from initAnalyticsServer — shared event names are documented in both tabs.

React
JavaScript
Server

analytics()

Module factory for EmbeddablesProvider — not a hook

import { EmbeddablesProvider } from '@embeddables/core/react'
import { analytics } from '@embeddables/analytics/react'

<EmbeddablesProvider config={config} modules={[analytics({ publishableKey })]}>
  {children}
</EmbeddablesProvider>

Registers Analytics on the provider’s modules prop. core comes from the provider — do not pass it here. The generated CLI setup wires this for you.

string

Optional. Overrides publishableKey on Core config when Analytics must own the key.

useTrackEvent()

Track any event from React

function

Same inputs as trackEvent above. Does nothing without error if Analytics is not ready yet.

boolean

true while a send is in progress — not while Analytics is still loading.

boolean

true when the latest track call failed.

unknown

Details from the failed send, when isError is true.

useTrackClickEvent()

Wrapper for button:clicked

string

required

Passed through as button_key — see button:clicked under JavaScript.

function

Optional. Runs only after a successful track.

Returns an object with trackClickEvent, isPending, isError, and error. Calling trackClickEvent with key and optional callback returns an onClick handler.

useTrackCustomEvent()

Wrapper for custom_event:triggered

Returns trackCustomEvent, isPending, isError, and error. Optional properties follow custom_event:triggered under JavaScript or Server.

page:viewed

A screen or route was shown

await analytics.trackEvent({
  event_name: 'page:viewed',
  page_key: 'checkout',
  is_funnel_step: true,
  funnel_step_label: 'Checkout',
})

string

required

Identifier for the page or step in your project (1–128 characters). Not the same as a form id.

Optional browser context — added automatically when you leave these fields out. Analytics reads them once when you call initAnalytics (from the page URL and browser); values you set on the event override what was saved at setup.

Field	Type	Where it comes from
`utm_source`	string	`utm_source` URL parameter
`utm_medium`	string	`utm_medium` URL parameter
`utm_campaign`	string	`utm_campaign` URL parameter
`utm_content`	string	`utm_content` URL parameter
`utm_term`	string	`utm_term` URL parameter
`utm_id`	string	`utm_id` URL parameter
`device`	string	Device type (`mobile`, `tablet`, or `desktop`)
`country`	string	Country guess from the browser; the API may also infer country from the visit

button:clicked

A button or CTA was pressed

await analytics.trackEvent({
  event_name: 'button:clicked',
  button_key: 'buy_now',
})

string

required

A stable name for this button in analytics (1–128 characters) — use the same key as in trackClickEvent({ key: … }) or in trackEvent({ event_name: 'button:clicked', button_key: … }).

form:submitted

A form was submitted

await analytics.trackEvent({
  event_name: 'form:submitted',
  form_key: 'intake',
})

Answers are sent as separate data:updated / field:updated events, not on this event.

string

required

Identifier for the form (1–128 characters), matching the form id from your Embeddables setup (same as in Forms).

payment:completed

A purchase or payment finished

await analytics.trackEvent({
  event_name: 'payment:completed',
  payment_value: 49,
  is_funnel_step: true,
  funnel_step_label: 'Purchase',
})

number

required

Numeric amount for the completed payment.

custom_event:triggered

Custom moment with optional properties

await analytics.trackEvent({
  event_name: 'custom_event:triggered',
  properties: { promo: 'summer_sale' },
})

object

Optional extra details — labels and values you choose. Each key may be up to 128 characters.

field:updated

One form field value changed

await analytics.trackEvent({
  event_name: 'field:updated',
  field_key: 'email',
  field_type: 'email',
  field_value: '[email protected]',
})

Sent automatically by Forms only when Analytics is wired to Forms — otherwise call trackEvent yourself.

string

required

Identifier for the form field (1–128 characters), matching the field id in your Forms setup.

string

required

Kind of field: text, email, number, boolean, select, multiselect, or json.

string | number | boolean | object | array

Optional answer — text, number, yes/no, list of choices (multiselect), or structured data (json).

string

Optional. Advanced: id when the field is linked to the Field Registry.

string

Optional. Advanced: id when the field is tied to a protocol form question.

data:updated

Several form answers changed at once

await analytics.trackEvent({
  event_name: 'data:updated',
  data: {
    plan: { value: 'pro', label: 'Pro plan' },
  },
})

Only the fields that changed — not the entire form. Sent automatically by Forms only when Analytics is wired to Forms — otherwise call trackEvent yourself.

object

required

Each key is a field id; each value has value (answer text, max 1024 characters) and label (display name, max 256 characters).

experiment:assigned

Visitor assigned to an A/B test variant

await analytics.trackEvent({
  event_name: 'experiment:assigned',
  experiment_key: 'hero_test',
  variant: 'control',
})

Sent automatically by Experiments only when Analytics is wired to Experiments and a new assignment is made — otherwise call trackEvent yourself.

string

required

Experiment identifier (1–128 characters).

string

required

Assigned variant name (1–128 characters).

custom_event:triggered

Custom moment with optional properties

await analytics.trackEvent({
  event_name: 'custom_event:triggered',
  properties: { promo: 'summer_sale' },
})

object

Optional extra details — labels and values you choose. Each key may be up to 128 characters.

field:updated

One form field value changed

await analytics.trackEvent({
  event_name: 'field:updated',
  field_key: 'email',
  field_type: 'email',
  field_value: '[email protected]',
})

Sent automatically by Forms only when Analytics is wired to Forms — otherwise call trackEvent yourself.

string

required

Identifier for the form field (1–128 characters), matching the field id in your Forms setup.

string

required

Kind of field: text, email, number, boolean, select, multiselect, or json.

string | number | boolean | object | array

Optional answer — text, number, yes/no, list of choices (multiselect), or structured data (json).

string

Optional. Advanced: id when the field is linked to the Field Registry.

string

Optional. Advanced: id when the field is tied to a protocol form question.

data:updated

Several form answers changed at once

await analytics.trackEvent({
  event_name: 'data:updated',
  data: {
    plan: { value: 'pro', label: 'Pro plan' },
  },
})

Only the fields that changed — not the entire form. Sent automatically by Forms only when Analytics is wired to Forms — otherwise call trackEvent yourself.

object

required

Each key is a field id; each value has value (answer text, max 1024 characters) and label (display name, max 256 characters).

experiment:assigned

Visitor assigned to an A/B test variant

await analytics.trackEvent({
  event_name: 'experiment:assigned',
  experiment_key: 'hero_test',
  variant: 'control',
})

Sent automatically by Experiments only when Analytics is wired to Experiments and a new assignment is made — otherwise call trackEvent yourself.

string

required

Experiment identifier (1–128 characters).

string

required

Assigned variant name (1–128 characters).

React hooks do not send events during server-side page rendering — use initAnalyticsServer in Overview & setup instead. For visitor or project id in React, use Core’s useAppUserId and useEmbeddablesProjectId.

Returns

string

required

Visitor id for this call. Created by the API the first time if Core did not have one yet; save it in Core for later events.

number

required

How many events in the call were accepted (0–50).

boolean

required

Whether the events were passed on to reporting storage. Can be false even when the call succeeds if reporting is not set up or temporarily unavailable.

{
  "app_user_id": "usr_abc123",
  "accepted": 1,
  "forwarded": true
}

Get Started

SDKs

Tracking events

Shared fields

Events

Returns

​Tracking events

​Shared fields

​Events

​Returns

Tracking events

Shared fields

Events

Returns