Experiment assignment, hooks & events

Install, init, and walkthrough examples live in Overview & setup. This page is the reference for initExperiments / initExperimentsServer, the assignment handle they return, methods and hooks, and the experiment:assigned event Experiments emits.

Set up & use experiments

In JavaScript, call initExperiments; on the server, call initExperimentsServer. Each reads your experiment list from Core once, then lets you open an assignment handle with initExperiment({ experimentId }).

JavaScript
Server

import { initExperiments } from '@embeddables/experiments'

const experiments = initExperiments(options)
const hero = experiments.initExperiment({ experimentId: 'exp-hero' })

import { initEmbeddablesServer } from '@embeddables/core/server'
import { initExperimentsServer } from '@embeddables/experiments/server'

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

const experiments = initExperimentsServer({ server })
const hero = experiments.initExperiment({ experimentId: 'exp-hero' })
const variantKey = await hero.getAssignedVariantKey()

Use this when Experiments runs during a server page load (SSR). You open experiments the same way with initExperiment, but assignments are read from request cookies — Experiments never writes cookies back. Pass resolved variants to the client as serverAssignments. Returns the same client shape as initExperiments; assignment methods are in JavaScript & Server.

EmbeddablesInstance

required

An initialized @embeddables/core/server instance exposing the cookie / getProjectId / getExperiments contract. Throws ConfigError without a projectId.

ExperimentsAnalytics

Optional analytics client — same behavior as the client option.

Optional override for reading/writing assignments. The default adapter only reads request cookies via server.getCookie(); write is a no-op so SSR must set response cookies itself when you need cross-request stickiness.

object

required

Init options — a Core instance plus optional SSR seed and analytics wiring. See Options below.

string

required

Passed to initExperiment. Must be the id of an experiment in your Core config. Typed against the registered list — an unknown id is caught while you write code and throws ConfigError at runtime.

Options

core

Required initialized Core instance

import { initEmbeddables } from '@embeddables/core'
import { initExperiments } from '@embeddables/experiments'

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

EmbeddablesInstance

required

An initialized @embeddables/core instance. Experiments reads the configured experiment list from its getExperiments() and the visitor/project ids from it — it never passes a separate experiments option. Throws ConfigError if the instance is missing the required Core methods or has no projectId.

serverAssignments

SSR pre-seed of already-resolved variants

const experiments = initExperiments({
  core: embeddables,
  serverAssignments: { 'exp-hero': 'control' },
})

Record<string, string>

Map of experimentId → variantKey the server already resolved, so the first client render is synchronous and does not flash variants. Entries for unknown experiment ids or unconfigured variant keys are dropped. Client-only — it is not a server option.

analytics

Optional analytics client for experiment:assigned

import { initAnalytics } from '@embeddables/analytics'

const analytics = initAnalytics({ core: embeddables })
const experiments = initExperiments({ core: embeddables, analytics })

ExperimentsAnalytics

Optional analytics client. When present, each new assignment emits one experiment:assigned event. Experiments never imports Analytics itself and never sends identity on the assignment request — the injected client owns identity. A failed trackEvent never fails assignment; the variant is persisted first.

Methods and hooks

React covers the experiments() module factory and the hooks — register the factory on EmbeddablesProvider before calling hooks. JavaScript & Server lists assignment methods on the ExperimentsClient from initExperiments or initExperimentsServer — the same API on both entry points. useExperiment throws if Experiments was not registered on EmbeddablesProvider once Core is ready; useAssignExperiment does not throw — assignExperiment() returns undefined when the module is missing.

React
JavaScript & Server

experiments()

Module factory for EmbeddablesProvider — not a hook

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

<EmbeddablesProvider config={config} modules={[experiments({ serverAssignments, analytics })]}>
  {children}
</EmbeddablesProvider>

Returns an EmbeddablesReactModule for the provider’s modules prop. The generated CLI setup wires this for you; pass options only to override. core is supplied by the provider — do not pass it here.

Record<string, string>

Same SSR pre-seed as the client option. Pass the same map the server used so hydration does not flash variants.

ExperimentsAnalytics

Optional analytics client — enables the experiment:assigned event. The generated React setup wires Analytics automatically when both SDKs are installed.

useExperiment()

Assign and read a variant on render

import { useExperiment } from '@embeddables/experiments/react'

const { assignedVariantKey, assignedVariantTitle, status, error } = useExperiment({
  experimentId: 'exp-hero',
})

Assigns as soon as it renders. If a matching serverAssignments seed was passed to experiments(), the first render is ready synchronously. Throws if Core is ready and Experiments was not registered on EmbeddablesProvider’s modules.

string

required

The id of a configured experiment. Inferred against the registered experiment list — no type arguments needed. Throws ConfigError for an unknown id.

string | null

required

Assigned variant key, or null while status is pending / error.

string | null

required

Assigned variant title, or null while status is pending / error.

'pending' | 'ready' | 'error'

required

pending until the assignment resolves, ready when the variant is usable, error when the assignment request failed.

Error | null

required

The failure when status is error, otherwise null.

useAssignExperiment()

Assign a variant on demand instead of on render

import { useAssignExperiment } from '@embeddables/experiments/react'

const { assignExperiment, isPending, isError, error } = useAssignExperiment()

const assigned = await assignExperiment({ experimentId: 'exp-hero' })
if (assigned) console.log(assigned.variantKey, assigned.variantTitle)

Leaves the assignment call to you — fire it when the visitor actually reaches the experiment, rather than booking an exposure for everyone who loads the page. A later useExperiment for the same id reads the assignment back without another request. The hook itself does not throw when Experiments is missing — only assignExperiment() returns undefined.

string

required

Passed to assignExperiment. Must be the id of an experiment in your Core config. Throws ConfigError for an unknown id when the module is registered.

(params: { experimentId: string }) => Promise<{ variantKey: string; variantTitle: string } | undefined>

required

Assigns and resolves the variant. Returns undefined when the Experiments module is not registered; rejects (after setting error) when the request fails.

boolean

required

true while at least one assignment is in flight.

boolean

required

true when the latest assignment failed.

unknown

required

Details from the failed assignment, when isError is true.

Call these on the client returned from initExperiments or initExperimentsServer.

experiments.initExperiment()

Get a handle for one configured experiment

const hero = experiments.initExperiment({ experimentId: 'exp-hero' })

string

required

The id of an experiment in your Core config. Typed against the registered experiment list, so an unknown id is caught while you write code. Throws ConfigError at runtime if the id is not configured.

Returns an ExperimentHandle with getAssignedVariantKey, getAssignedVariantTitle, and getExperimentId.

handle.getAssignedVariantKey()

Resolve the sticky variant key

const variantKey = await hero.getAssignedVariantKey()

Browser (initExperiments): the first call asks the Embeddables API, persists the result to localStorage and assignment cookies, and returns the variant key. Later calls reuse the stored value with no request.Server (initExperimentsServer): reads request cookies or fetches once; by default new assignments live only in request memory (cookie write is a no-op). Cross-request stickiness needs assignment cookies, a persisting cookieStorage, or serverAssignments on browser initExperiments.

string

required

The assigned variant key — typed to the configured variants of this experiment.

handle.getAssignedVariantTitle()

Resolve the human-readable variant title

const variantTitle = await hero.getAssignedVariantTitle()

Resolves the same sticky assignment as getAssignedVariantKey, then maps it to the variant’s title (falling back to its key when no title is configured).

string

required

Display title for the assigned variant.

handle.getExperimentId()

Read back the experiment id for this handle

const id = hero.getExperimentId() // 'exp-hero'

string

required

The experiment id this handle was created for. Synchronous — no assignment is triggered.

Analytics events

When an analytics client is wired, each new assignment auto-emits one experiment:assigned event — a variant already in storage never re-emits. See the Analytics reference for the full event catalog.

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

string

required

The experiment key (not the id) resolved by the assignment.

string

required

The assigned variant key.

Returns

initExperiments and initExperimentsServer return an ExperimentsClient; initExperiment returns an ExperimentHandle.

object

required

Exposes initExperiment — documented under Methods and hooks.

object

required

Exposes getAssignedVariantKey, getAssignedVariantTitle, and getExperimentId — documented under Methods and hooks.

(options: { experimentId: string }) => ExperimentHandle

required

Builds a handle for one configured experiment.

() => Promise<string>

required

Resolves the sticky variant key for the handle’s experiment.

() => Promise<string>

required

Resolves the display title for the assigned variant.

() => string

required

Returns the experiment id the handle was created for.

{
  "experimentId": "exp-hero",
  "variantKey": "control",
  "variantTitle": "Control"
}

​Set up & use experiments

​Options

​Methods and hooks

​Analytics events

​Returns

Set up & use experiments

Options

Methods and hooks

Analytics events

Returns