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. The walkthrough below covers install and setup. For every event name, field, and React helper, open the reference.

Implementation

Install

npm install @embeddables/core @embeddables/analytics

pnpm add @embeddables/core @embeddables/analytics

yarn add @embeddables/core @embeddables/analytics

Analytics needs a publishable key (from em init or the admin app). Add it to your project config when you set up Core, or pass it when you set up Analytics. If Analytics has a key, it can supply one for the rest of your app. Install once, then pick your setup:

React
JavaScript
Server

Follow the example below: wrap your app once, then record events from your components (for example when someone taps a button).

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

function TrackIntro() {
  const { trackEvent } = useTrackEvent()

  return (
    <button
      onClick={() => void trackEvent({ event_name: 'page:viewed', page_key: 'intro' })}
    >
      Continue
    </button>
  )
}

export function App() {
  return (
    <EmbeddablesProvider
      config={{ ...config, publishableKey: 'pk_sandbox_<your-key>' }}
      modules={modules}
    >
      <TrackIntro />
    </EmbeddablesProvider>
  )
}

If you used the CLI, the modules import already turns Analytics on. For event names, fields, and the React helpers (useTrackEvent, and related hooks), see the reference.

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

const embeddables = initEmbeddables({
  ...config,
  publishableKey: 'pk_sandbox_<your-key>',
})

const analytics = initAnalytics({ core: embeddables })
// Or: initAnalytics({ core: embeddables, publishableKey: 'pk_sandbox_<your-key>' }) when Core has no key

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

Analytics always uses the current visitor from Core — if their identity changes later, the next trackEvent picks it up automatically.Any field you set on an event yourself overrides the value Analytics would have detected automatically.

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

const server = initEmbeddablesServer({
  ...config,
  publishableKey: 'pk_sandbox_<your-key>',
  cookies: { get: (key) => request.cookies.get(key) ?? null },
})

const analytics = initAnalyticsServer({ server })
// Or: initAnalyticsServer({ server, publishableKey: 'pk_sandbox_<your-key>' }) when Core has no key

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

Need the full list of events and fields (including what you can send from the server)? See Reference — Events. For React track hooks, see Reference — React.

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, analyticsInstance: analytics })

In React, adding Analytics with the CLI also lets Experiments and Forms send events for you — no extra connection step. See Experiments and Forms for what each one records.

Get Started

SDKs

Overview

Implementation

Install

Wiring Analytics into Experiments or Forms

​Overview

​Implementation

​Install

​Wiring Analytics into Experiments or Forms

Overview

Implementation

Install

Wiring Analytics into Experiments or Forms