JavaScript SDK (window.ours_experiments)

After the experiment script loads, it exposes a window.ours_experiments global that gives you programmatic access to initialization, experiment assignments, and event subscriptions from your own JavaScript code.

If you load experimentation through the Ours Web SDK or Tag Manager, initialization is wired up for you with the shared CDP visitor ID. If you load the script manually, you call window.ours_experiments.init({ visitorId }) yourself — see Installation.

If your app owns the DOM in React, Vue, Next.js, or another SPA framework, prefer reading assignments from this SDK and rendering the variant in your own code. DOM-modification experiments are best for pages where the runtime can safely mutate the rendered HTML.

For A/B and multivariate experiments, an impression is tracked only when the visitor is actually assigned to an explicit variant in the experiment. That includes the control variant and any treatment variants. Visitors who are not eligible or who fall outside the experiment's traffic allocation are not assigned and do not get an $experiment_impression event.

SDK Methods

init(options?)

Explicitly initialize the experiments runtime.

window.ours_experiments.init({
  visitorId: window.ours_data?.visitor_id,
});

Pass the shared CDP visitor ID whenever possible. If visitorId is omitted, the runtime will warn and generate a fallback ID, but analytics and attribution will be less reliable than the CDP-backed path.

Call init() before using methods like getAssignments() or getVisitorContext().

getVariant(experimentId)

Get the assigned variant ID for a specific experiment.

Returns null if the visitor is not assigned (not in traffic allocation, not eligible, or the experiment is not on this page). null is not the same as control — control is a real assigned variant.

const variantId = window.ours_experiments.getVariant('exp_abc123');
// => "var_001" | null

getVariantName(experimentId)

Get the human-readable variant name for a specific experiment.

const name = window.ours_experiments.getVariantName('exp_abc123');
// => "Green CTA" | "Control" | null

getAssignments()

Get all current experiment assignments as a plain object. Keys are experiment IDs, values are variant IDs.

const assignments = window.ours_experiments.getAssignments();
// => { "exp_abc123": "var_001", "exp_def456": "var_control" }

Useful for sending all active experiment assignments to an analytics platform:

// Send all active experiments to your analytics on page load
const assignments = window.ours_experiments.getAssignments();
Object.entries(assignments).forEach(([experimentId, variantId]) => {
  analytics.track('Experiment Viewed', { experimentId, variantId });
});

isInExperiment(experimentId)

Check if the visitor is currently assigned to any variant in an experiment (including the control variant).

if (window.ours_experiments.isInExperiment('exp_abc123')) {
  // visitor is in this experiment
}

getExperiment(experimentId)

Get full experiment info including the visitor's current assignment.

const experiment = window.ours_experiments.getExperiment('exp_abc123');
// => {
//   id: "exp_abc123",
//   key: "hero-cta-color",
//   name: "Hero CTA Color",
//   variantId: "var_001",
//   variantName: "Green CTA",
//   isControl: false
// }

Returns null if the experiment is not configured on the current page.

This method also works for personalization. Personalization assignments use the same shape as A/B-test assignments — the same experimentId, variantId, variantName, and isControl fields are returned, so your application code can handle either with one code path. getAssignments() and the 'assigned' event include personalization the same way.

getExperimentByKey(experimentKey)

Get full experiment info using the experiment's stable code-facing key.

const experiment = window.ours_experiments.getExperimentByKey('homepage-hero');
// => {
//   id: "exp_abc123",
//   key: "homepage-hero",
//   name: "Hero CTA Color",
//   variantId: "var_001",
//   variantName: "Green CTA",
//   isControl: false
// }

Use this when your app owns rendering and you want a stable handle that is easier to read and maintain than copying opaque experiment IDs into code.

getExperiments()

Get full experiment info for every experiment currently loaded on the page.

const experiments = window.ours_experiments.getExperiments();
// => [{ id, key, name, variantId, variantName, isControl }, ...]

This is useful when you want to inspect the full active assignment set at once or forward richer metadata to your own analytics or debugging tools.

Conversion Events

Experiments measure against the same ordinary CDP events you already track on your site.

If your experiment metric is signup_completed, keep tracking that event the normal way:

document.querySelector('#signup-form').addEventListener('submit', () => {
  ours('track', 'signup_completed');
});

Or, with the npm SDK:

function onPurchaseComplete() {
  ours.track('purchase_completed');
}

The experiments runtime tracks impressions automatically. Your application continues to emit the conversion events you care about through the standard Web SDK.

on(event, callback)

Subscribe to experiment events. Returns an unsubscribe function.

'assigned' event

Fires when the visitor is assigned to a variant. Includes both new assignments and existing assignments read from the cookie on each page load.

const unsubscribe = window.ours_experiments.on('assigned', (data) => {
  console.log(data);
  // {
  //   experimentId: "exp_abc123",
  //   experimentName: "Hero CTA Color",
  //   variantId: "var_001",
  //   variantName: "Green CTA",
  //   isControl: false
  // }
});

// Clean up when no longer needed
unsubscribe();

Use case: Send experiment assignments to a third-party analytics tool, show/hide custom UI elements based on variant, or log assignments for debugging.

// Forward assignments to Segment
window.ours_experiments.on('assigned', ({ experimentId, variantId, variantName }) => {
  analytics.track('Experiment Viewed', {
    experiment_id: experimentId,
    variant_id: variantId,
    variant_name: variantName,
  });
});

Programmatic rendering pattern

If you want your application code to own rendering, initialize the SDK once, then render based on getExperiment(...) or the 'assigned' event.

window.ours_experiments.init({
  visitorId: window.ours_data?.visitor_id,
});

const heroExperiment = window.ours_experiments.getExperimentByKey('homepage-hero');

if (heroExperiment?.variantId === 'var_enterprise') {
  renderEnterpriseHero();
} else {
  renderDefaultHero();
}

window.ours_experiments.on('assigned', ({ experimentId, variantId }) => {
  if (experimentId === 'exp_homepage_hero' && variantId === 'var_enterprise') {
    renderEnterpriseHero();
  }
});

Use this pattern when:

• your framework re-renders the same DOM subtree frequently
• you want type-safe rendering decisions in app code
• you need the same assignment to control multiple components
• you want personalization and experiments to share the same app-owned UI logic

forceVariant(experimentId, variantId)

Force a specific variant for QA and testing. Overrides the normal hash-based assignment for the given experiment on this page load.

// Force variant B for manual QA
window.ours_experiments.forceVariant('exp_abc123', 'var_001');

Note: Call forceVariant() before window.ours_experiments.init(...) for the override to apply immediately. If called after initialization, the variant will apply on the next page load.

For URL-based preview (no code needed), use the ?ours_preview=<variantId> query parameter instead.

clearForced()

Clear all forced variant overrides.

window.ours_experiments.clearForced();

Preview Mode (URL Parameter)

The fastest way to preview a variant is the Preview button next to each variant on the experiment detail page — it opens your site with the variant forced.

If you need the raw mechanism (e.g. for sharing a link with a teammate), add ?ours_preview=<variantId> to any page where the experiment runs. This applies the variant client-side without tracking an impression.

https://yoursite.com/pricing?ours_preview=var_001

Preview only works once the experiment is running and a new version has been published to your site.

Next Steps

• Headless Experiments: Guide for app-owned A/B test rendering
• Content Experiments: Guide for DOM modification experiments
• Redirect Experiments: Guide for redirect experiments
• Headless Personalization: Code-driven personalization with getVisitorContext()
• Experiment Settings: Targeting, traffic allocation, and consent