Experiments

Prerequisites

Complete the quickstart first. You should be sending pageviews and custom events before running an experiment.

1. Create an experiment

In the console, open your project and go to Experiments → Create experiment. Set:

• Key — identifier used in code (e.g. checkout_test)
• Variants — two names, typically control and treatment
• Allocation % — share of in-rollout visitors assigned to the treatment variant
• Rollout % — share of all visitors entered into the experiment
• Primary conversion event — custom event name that counts as a conversion (e.g. purchase_completed)

Use the experiment key in your code, not the internal document ID shown in dashboard URLs.

2. Verify both variants outside production

Deploy code for both variants. Then, on the experiment you just created, use the Environments layer to force Control and Treatment in development or staging. This checks your integration; it is not a randomized test. See Environments.

3. Get a variant assignment

renderContext.variant returns the variant name, or null when the visitor is outside rollout, the experiment is disabled, or render context times out. In React or Next.js, call it from useEffect, not during render.

const variant = await renderContext.variant("checkout_test");

if (variant === "treatment") {
  renderTreatmentCheckout();
} else if (variant === "control") {
  renderControlCheckout();
} else {
  renderDefaultCheckout(); // not in experiment
}

The first variant() call per experiment per page load automatically records an exposure event.

React

Use the React hook to render from the assigned variant. Install the browser SDK first through your framework setup.

pnpm add @rendercontext/sdk react

import { useVariant } from "@rendercontext/sdk/react";

function Checkout() {
  const variant = useVariant("checkout_test");
  return variant === "treatment" ? <Treatment /> : <Control />;
}

4. Record a conversion

When the visitor completes your goal action, send a custom event with the same name you set as the primary conversion event. No special experiment API is required.

renderContext.event("purchase_completed");

5. View results

Open the experiment in the console and click Results to compare exposures and conversions across variants. Results update as new events arrive.

Manual exposure (optional)

If you need to record an exposure without calling variant() first:

await renderContext.exposure("checkout_test", "treatment");

Related

Feature flags share the same render context. See Feature flags for rollout and targeting without a conversion goal.