Analytics SDK

Overview

Analytics records visitor activity — page views, clicks, purchases, and custom events — tagged with the current project and visitor identity from Core. Once tracked, that data is available for reporting and analysis in Embeddables.

What gets tracked

Event	What it means
`page:viewed`	A screen or step was shown
`button:clicked`	A button or call-to-action was pressed
`field:updated`	A single form answer changed (usually sent automatically by Forms)
`data:updated`	A batch of form answers changed (usually sent automatically by Forms)
`form:submitted`	A form was submitted (usually sent automatically by Forms)
`payment:completed`	A purchase completed
`custom_event:triggered`	Any other moment worth recording, with custom properties
`experiment:assigned`	A visitor was assigned to an A/B test version (usually sent automatically by Experiments)

In browsers, page:viewed events are automatically enriched with available marketing (UTM) parameters, device type, and a country guess.

Implementation

Requires a publishableKey on your Core config (or passed directly to initAnalytics). Everything else in Core works without one, but Analytics authenticates every request with it.

Install

npm install @embeddables/analytics @embeddables/core

pnpm add @embeddables/analytics @embeddables/core

yarn add @embeddables/analytics @embeddables/core

React apps also need React 18 or newer.

Client

import { initEmbeddables } from '@embeddables/core'
import { initAnalytics } from '@embeddables/analytics'

const embeddables = initEmbeddables({
  projectId: '<your-project-id>',
  publishableKey: 'pk_sandbox_<your-key>',
  forms: [],
  experiments: [],
})

const analytics = initAnalytics({ core: embeddables })

await analytics.trackEvent({ event_name: 'page:viewed', page_key: 'intro' })
await analytics.trackEvent({ event_name: 'payment:completed', payment_value: 49 })

Analytics always reads the current visitor off the Core instance — if the user’s identity changes after initAnalytics, the next trackEvent picks that up automatically. Any field you set explicitly on an event overrides the value Analytics would have detected automatically.

`initAnalytics` options

Option	Default	Purpose
`core`	—	Required. An initialized Core instance
`publishableKey`	Core’s key	Override the publishable key just for Analytics

initAnalytics throws if no valid pk_(sandbox\|live)_* key is available from either the option or core.getPublishableKey(). Set one before calling it.

React

Register Analytics through EmbeddablesProvider’s modules prop — the CLI generates the module list in embeddables/_dist/modules — then read the track hooks anywhere underneath. They share one client per Core instance.

import { EmbeddablesProvider } from '@embeddables/core/react'
import {
  useTrackClickEvent,
  useTrackCustomEvent,
  useTrackEvent,
} from '@embeddables/analytics/react'
import { config } from './embeddables/_dist'
import { modules } from './embeddables/_dist/modules'

function App({ children }) {
  return (
    <EmbeddablesProvider config={config} modules={modules}>
      {children}
    </EmbeddablesProvider>
  )
}

function Checkout() {
  const { trackEvent, isPending: isTrackingEvent, isError, error } = useTrackEvent()
  const { trackClickEvent, isPending: isTrackingClick } = useTrackClickEvent()
  const { trackCustomEvent, isPending: isTrackingCustom } = useTrackCustomEvent()

  const goToCheckout = () => {
    // navigate after the click is tracked
  }

  return (
    <>
      <button
        onClick={trackClickEvent({ key: 'buy', callback: goToCheckout })}
        disabled={isTrackingClick}
      >
        Buy
      </button>
      <button
        disabled={isTrackingEvent}
        onClick={() => void trackEvent({ event_name: 'page:viewed', page_key: 'checkout' })}
      >
        Track page view
      </button>
      <button
        disabled={isTrackingCustom}
        onClick={() => void trackCustomEvent({ properties: { key: 'promo_shown' } })}
      >
        Track custom event
      </button>
      {isError && error instanceof Error ? <p>{error.message}</p> : null}
    </>
  )
}

Hook / factory	Behavior
`analytics(options?)`	Module factory for the provider’s `modules` prop; its `init(core)` creates the client and calls `core.setAnalyticsInstance`
`useTrackEvent()`	`{ trackEvent, isPending, isError, error }` — track any event
`useTrackClickEvent()`	`{ trackClickEvent, isPending, isError, error }`; `trackClickEvent({ key, callback })` returns an `onClick` that sends `button:clicked`, then runs `callback` after a successful track
`useTrackCustomEvent()`	`{ trackCustomEvent, isPending, isError, error }` — send `custom_event:triggered` with `properties`

isPending reflects an in-flight track call, not initialization. Before Core and the Analytics module are ready, track calls are no-ops — they never throw or queue.

For project and visitor identity in React, use the Core hooks (useAppUserId, useEmbeddablesProjectId) — Analytics React bindings don’t duplicate Core getters. React hooks never track during server rendering; track from server code through the server entry point below.

Server

import { initEmbeddablesServer } from '@embeddables/core/server'
import { initAnalyticsServer } from '@embeddables/analytics/server'

const server = initEmbeddablesServer({
  projectId: '<your-project-id>',
  publishableKey: 'pk_sandbox_<your-key>',
  forms: [],
  experiments: [],
  cookies: { get: (key) => request.cookies.get(key) ?? null },
})

const analytics = initAnalyticsServer({ server })

await analytics.trackEvent({
  event_name: 'custom_event:triggered',
  properties: { key: 'signup' },
})

The server client doesn’t add browser context (no UTM/device/country) and only accepts custom_event:triggered and experiment:assigned — everything else is tracked from the browser. Timestamps are assigned automatically — you never set one yourself. Each event_name only accepts its own matching fields, so TypeScript flags a payment_value on a page:viewed event before it ever ships.

Wiring Analytics into Experiments or Forms

Analytics never depends on Experiments or Forms, and they never depend on it — the connection is optional. In non-React code, pass the client you already created as the analytics / analyticsInstance option:

const analytics = initAnalytics({ core: embeddables })

const experiments = initExperiments({ core: embeddables, analytics })
const forms = initForms({ core: embeddables, schemas, analyticsInstance: analytics })

In React, the CLI-generated modules are ordered analytics → experiments → forms, so Experiments and Forms read the client back off Core automatically — you don’t wire it yourself. See Experiments and Forms for what each one emits.

Foundation

SDKs

Overview

What gets tracked

Implementation

Install

Client

`initAnalytics` options

React

Server

Wiring Analytics into Experiments or Forms

​Overview

​What gets tracked

​Implementation

​Install

​Client

​initAnalytics options

​React

​Server

​Wiring Analytics into Experiments or Forms

Overview

What gets tracked

Implementation

Install

Client

`initAnalytics` options

React

Server

Wiring Analytics into Experiments or Forms