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, conversion tracking, and event subscriptions from your own JavaScript code.

Important: The runtime does not auto-start. Call window.ours_experiments.init({ visitorId }) after the script loads. In production, this is expected to come from the Ours Web SDK or Tag Manager so experiments use the shared CDP visitor ID.

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",
//   name: "Hero CTA Color",
//   variantId: "var_001",
//   variantName: "Green CTA",
//   isControl: false
// }

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

trackConversion(experimentId?, value?)

Track a custom conversion event for an experiment. Fires a $experiment_conversion event via the Ours CDP SDK, which flows into your analytics pipeline alongside impression data.

// Track a conversion for a specific experiment
window.ours_experiments.trackConversion('exp_abc123');

// Track a conversion with a numeric value (e.g. revenue in cents)
window.ours_experiments.trackConversion('exp_abc123', 4999);

// Track a conversion for ALL active experiments at once
window.ours_experiments.trackConversion();

When to call this: Call trackConversion() when the visitor completes the goal you are measuring — a button click, form submission, page visit, or purchase.

// Example: track on form submit
document.querySelector('#signup-form').addEventListener('submit', () => {
  window.ours_experiments.trackConversion('exp_abc123');
});

// Example: track on purchase with revenue
function onPurchaseComplete(orderTotal) {
  window.ours_experiments.trackConversion('cta-experiment', orderTotal * 100);
}

Note: Impression events ($experiment_impression) are tracked automatically by the runtime on each page load. You only need to call trackConversion() for conversion events.

For A/B and multivariate experiments, those automatic impression events are emitted for all assigned variants, including control. They are not emitted for visitors outside traffic allocation.

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,
  });
});

'converted' event

Fires when trackConversion() is called. Useful for logging or forwarding conversion data to third-party tools.

window.ours_experiments.on('converted', (data) => {
  console.log(data);
  // {
  //   experimentId: "exp_abc123",
  //   experimentName: "Hero CTA Color",
  //   variantId: "var_001",
  //   variantName: "Green CTA",
  //   value: 4999  // if a value was passed
  // }
});

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)

To preview a specific variant without writing any code, add ?ours_preview=<variantId> to the URL. This applies the variant client-side without tracking an impression.

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

The variant ID can be found in the experiment's variant list in the dashboard.

Next Steps

• Content A/B Tests: Guide for DOM modification experiments
• Redirect Tests: Guide for redirect experiments
• Personalization: Always-on audience targeting rules