JavaScript SDK (window.ours_experiments)

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

Note: Most experiment interactions — variant assignment, DOM modifications, impression tracking — happen automatically. You only need the SDK for custom integrations, analytics attribution, or QA overrides.

SDK Methods

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

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.

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 the experiment runtime initializes (i.e., in a script before the experiment script tag) 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