Experiments SDK - Embeddables Docs

Overview

Experiments puts each visitor into a variant of an A/B test and keeps it stable — the same visitor always sees the same variant on later visits, without asking the server again. The walkthrough below covers install and setup. For every option, hook, and the experiment:assigned event, open the reference.

Implementation

Install

npm install @embeddables/core @embeddables/experiments

pnpm add @embeddables/core @embeddables/experiments

yarn add @embeddables/core @embeddables/experiments

Your experiment setup lives on Core (it comes from your generated config), so you never pass a separate experiments option to initExperiments. Install once, then pick your setup:

React
JavaScript
Server

Follow the example below: wrap your app once, then read each visitor’s test variant with useExperiment.

import { EmbeddablesProvider } from '@embeddables/core/react'
import { useExperiment } from '@embeddables/experiments/react'
import { config } from './embeddables/_dist'
import { modules } from './embeddables/_dist/modules'

function Hero() {
  // Pass the experiment id — no type arguments needed.
  const { assignedVariantKey, assignedVariantTitle, status } = useExperiment({
    experimentId: 'exp-hero',
  })

  if (status === 'pending') return <p>Loading…</p>

  return <h1>{assignedVariantTitle ?? assignedVariantKey}</h1>
}

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

If you used the CLI, the modules import in the example already turns Experiments on — you rarely need extra setup. For optional React details, see experiments() in the reference; for useExperiment and useAssignExperiment, see hooks.

If Experiments is missing from your setup, useExperiment will error. Add the SDK with the CLI so it is included in the generated modules file.

Assign on demand

useExperiment assigns the variant as soon as it renders. To assign at a specific moment instead, use useAssignExperiment:

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

function StartTrial() {
  const { assignExperiment, isPending } = useAssignExperiment()

  return (
    <button
      disabled={isPending}
      onClick={() => {
        void assignExperiment({ experimentId: 'exp-hero' }).then((assigned) => {
          if (assigned) console.log(assigned.variantKey, assigned.variantTitle)
        })
      }}
    >
      Start
    </button>
  )
}

A later useExperiment({ experimentId: 'exp-hero' }) reads that same assignment back without another request. assignExperiment returns undefined if Experiments isn’t set up, and rejects if the request fails.

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

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

const experiments = initExperiments({ core: embeddables })

// `experimentId` must match an experiment in your config
const hero = experiments.initExperiment({ experimentId: 'exp-hero' })
const variantKey = await hero.getAssignedVariantKey()
const variantTitle = await hero.getAssignedVariantTitle()

The first time a visitor hits an experiment, it asks the Embeddables API, saves the result, and returns the variant. After that it reuses the saved value with no extra request. getAssignedVariantKey() is typed, so an invalid variant key is caught while you write code, not at runtime.Assignment requests send the project ID and experiment key — never the visitor’s identity.Pass your initialized Core instance to initExperiments. Optional serverAssignments and Analytics wiring are listed in the reference.

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

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()

On the server, Experiments reads assignment cookies on the request; anything it fetches stays in memory for that request only (it does not set response cookies). To keep the same variant on the next load, set cookies yourself, use a custom cookieStorage, or pass serverAssignments in the browser — see the reference.

Analytics

Experiments never imports Analytics. In non-React code, create an Analytics client yourself and pass it in:

import { initAnalytics } from '@embeddables/analytics'

const analytics = initAnalytics({ core: embeddables })

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

In React, adding both SDKs with the CLI connects Analytics to Experiments for you — no extra steps. When Analytics is on, each new assignment fires one experiment:assigned event — a variant already saved from before doesn’t fire again. If that event fails to send, the assignment is unaffected; it was already saved first.

​Overview

​Implementation

​Install

​Assign on demand

​Analytics

Overview

Implementation

Install

Assign on demand

Analytics