Init, methods and hooks - Embeddables Docs

Install, init, and walkthrough examples live in Overview & setup. This page is the reference for initEmbeddables / initEmbeddablesServer and methods and hooks.

Set up & use Core

In JavaScript, call initEmbeddables; on the server, call initEmbeddablesServer. Both take your generated project config spread in, plus a publishableKey, and return an EmbeddablesInstance.

JavaScript
Server

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

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

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

const embeddables = initEmbeddablesServer({
  ...config,
  publishableKey: 'pk_sandbox_<your-key>',
  cookies: { get: (key) => readCookie(key) },
})

Use this during a server page load (SSR). Identity comes from the cookies adapter — there is no localStorage. Pass the resolved app user id to the client as serverAppUserId on initEmbeddables or EmbeddablesProvider.

{ get(key: string): string | null }

Cookie reader for the incoming request. Core calls get with its identity cookie key and expects the raw value or null. A throwing get surfaces as a StorageError.

EmbeddablesConfig

required

The config object the Embeddables CLI generates, spread in as-is, plus your publishableKey. Treat the generated config as opaque — don’t assemble or edit it by hand.

On the server, identity comes from the cookies you pass; in the browser it comes from localStorage. The browser does not read the identity cookie at init, so a Set-Cookie on your response won’t hand the id off to the first render — it only helps later server requests. If the server mints a new id and you don’t pass it into the browser as serverAppUserId, the browser makes its own id and one visitor is counted as two.

Methods and hooks

React covers EmbeddablesProvider and the hooks. JavaScript & Server lists the shared instance methods on the object from initEmbeddables or initEmbeddablesServer, plus getCookie (server only).

React
JavaScript & Server

EmbeddablesProvider

Root wrapper — not a hook

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

<EmbeddablesProvider
  config={{ ...config, publishableKey: 'pk_sandbox_<your-key>' }}
  modules={modules}
  serverAppUserId={appUserIdFromSSR}
>
  {children}
</EmbeddablesProvider>

Initializes Core in an effect after mount, runs each modules entry, then publishes the ready state so hooks see every registered product client. Children can render once before Core is ready — handle that loading state. config, modules, and serverAppUserId are captured on the first render only — remount with a key to change them.

EmbeddablesConfig

required

Generated project config spread in, plus publishableKey.

readonly EmbeddablesReactModule[]

Optional product SDK modules (analytics(), experiments(), forms(), …) from each SDK’s React entry point. Order matters — keep analytics before Experiments and Forms when all three are present.

string

App user id from initEmbeddablesServer during SSR so the browser does not mint a second id on first load.

useEmbeddables()

The enriched Core instance, or null before ready

const embeddables = useEmbeddables()
if (embeddables === null) return <p>Loading…</p>
if (embeddables.isError) return <p>Could not initialize.</p>
embeddables.getAppUserId()

EmbeddablesReactValue | null

null before init; otherwise { appUserId, isError, error } plus getAppUserId, getProjectId, getPublishableKey, and getExperiments. On failure, isError is true and appUserId is null.

useAppUserId()

Just the visitor id

const appUserId = useAppUserId() // string | null

string | null

The current visitor’s id, or null before Core is ready.

useEmbeddablesProjectId()

Just the project UUID

const projectId = useEmbeddablesProjectId() // string | null

string | null

The project UUID, or null before init or on error.

useRegisterPageView()

Record page views from React

const { registerPageView, getLastPageView, isPending, isError, error } = useRegisterPageView()
await registerPageView({ pageKey: 'checkout', isFunnelStep: true })

Never throws — an invalid page key or a failing store surfaces as isError.

function

Same input as registerPageView(). Returns undefined (without error) before Core is ready or when the call failed.

function

Returns the last recorded page key, or null when none is stored or Core is not ready.

boolean

true while a page view is being recorded.

boolean

true when the latest call failed.

unknown

Details from the failed call, when isError is true.

useEmbeddablesModule({ key })

Read a registered product client (advanced)

const analytics = useEmbeddablesModule<AnalyticsClient>({ key: 'analytics' })

The one place product SDKs read back the client their module registered. Most apps use each SDK’s own hook instead of calling this directly.

string

required

The module key to look up.

TClient | null

The registered client, or null before Core is ready or when no module claimed the key.

initEmbeddables()

JavaScript entry point — reads identity from localStorage

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

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

Resolves the visitor’s app user id from localStorage, creating and persisting a new one the first time.

string

An app user id produced by initEmbeddablesServer during SSR. When provided, the browser adopts it instead of minting a new one on first load.

getAppUserId()

The current visitor's id

embeddables.getAppUserId() // "usr_abc123"

string

required

The resolved anonymous visitor id. Never null on an instance — resolution happens at init.

getProjectId()

The project UUID

embeddables.getProjectId() // "8f2b…"

string

required

The validated project UUID passed at init.

getPublishableKey()

The resolved publishable key, if any

embeddables.getPublishableKey() // "pk_sandbox_…" | undefined

string | undefined

The key from config or the EMBEDDABLES_PUBLISHABLE_KEY environment variable, or undefined when neither supplied one.

getExperiments()

The validated experiments array

embeddables.getExperiments() // readonly unknown[]

readonly unknown[]

The experiment list from config, as validated at init. Shape is not specified here — consume it through Experiments.

getFormIds()

Registered form ids, in config order

embeddables.getFormIds() // ["intake", "checkout"]

readonly string[]

The keys of the forms map, in insertion order.

getFormSchema(formId)

One form's schema, or undefined

embeddables.getFormSchema('intake') // CoreFormSchema | undefined

string

required

Id of a form registered in config.

CoreFormSchema | undefined

The schema (id, optional name, and a fields array of { key, label, type, … }), or undefined when no form matches.

registerPageView(input)

Record a page view and optionally emit page:viewed

await embeddables.registerPageView({
  pageKey: 'checkout',
  isFunnelStep: true,
  funnelStepLabel: 'Checkout',
})

Always writes the last page view to storage; only emits an analytics page:viewed event when an Analytics client is registered on the same instance. In React, prefer useRegisterPageView.

string

required

Identifier for the page or step (1–128 characters).

boolean

Mark this view as a funnel step. Omitted from the event rather than sent empty.

string

Human-readable step name (1–128 characters), meaningful when isFunnelStep is true.

Promise<RegisterPageViewResult>

required

Resolves with { ok: true }. If the view is persisted but the analytics page:viewed event fails to send, the result also carries trackError: unknown — the emit never throws. An invalid pageKey or funnelStepLabel rejects the promise instead.

getLastPageView()

The last recorded page key

embeddables.getLastPageView() // "checkout" | null

string | null

The most recent page key — from in-memory storage in the browser, or from the identity cookie on the server instance — or null when none is stored.

getCookie(key)

Server only — read a request cookie through the adapter

embeddables.getCookie('EMBEDDABLES--…--APP-USER-ID') // string | null

Server only. Available on instances from initEmbeddablesServer; on a browser instance from initEmbeddables it always returns null.

string

required

Cookie name to read through the cookies adapter passed to initEmbeddablesServer.

string | null

The cookie value, or null when no adapter was provided or the cookie is missing.

setAnalyticsInstance and getAnalyticsInstance also exist on the instance but are composition wiring — the Analytics module registers its client through them so registerPageView can emit events. You do not call them directly.

Returns

initEmbeddables and initEmbeddablesServer return an EmbeddablesInstance — the object every other SDK’s core option expects.

object

required

Exposes the read methods documented under Methods and hooks: getAppUserId, getProjectId, getPublishableKey, getExperiments, getFormIds, getFormSchema, getCookie (server), registerPageView, and getLastPageView.

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

embeddables.getAppUserId() // "usr_abc123"
embeddables.getProjectId() // "8f2b…"
embeddables.getPublishableKey() // "pk_sandbox_…" | undefined
embeddables.getExperiments() // readonly unknown[]

​Set up & use Core

​Methods and hooks

​Returns

Set up & use Core

Methods and hooks

Returns