window.abtest

The storefront JavaScript API that lets your theme code check which variant a visitor is in and render the matching experience.

When the AB Test app embed is enabled, the storefront runtime attaches a small global object, window.abtest, to every page. Its main use is JavaScript API tests, where your own code renders variant B instead of the app redirecting the browser. This page documents the public members precisely as the runtime implements them.

Methods at a glance

setAnalyticsConsent is covered on its own page — see Data & consent. The rest of this page covers the two members you use to drive variant rendering.

isHypothesisActive(hypothesisId)

Resolves to whether the current visitor is assigned to a specific variant. Use it to decide whether to render your variant experience.

Parameters

Return value

A Promise<boolean> that resolves once the visitor's assignments are known:

• true — the visitor is enrolled in the experiment that owns hypothesisId and was assigned to that exact variant.
• false — the visitor was assigned a different variant of that experiment, or is not enrolled in an experiment that includes hypothesisId at all.

Because the runtime fails open, a network error while loading assignments resolves to false (the visitor sees your default/control experience) rather than rejecting.

getVisitorData()

Returns the current visitor id and the visitor's known assignments, synchronously.

{
  visitorId: "…",       // the anonymous _ab_vid for this visitor
  assignments: [
    { experimentId: "…", variantId: "…" }
    // one entry per experiment the visitor is enrolled in
  ]
}

Usage example

A typical JavaScript API test renders variant B only for visitors assigned to it, and leaves everyone else on the control markup. Await isHypothesisActive with the variant id from the test setup screen:

// Variant id copied from the JS API test in the AB Test admin.
const VARIANT_B = "var_9f3c…";

async function renderExperiment() {
  if (await window.abtest.isHypothesisActive(VARIANT_B)) {
    // Visitor is in variant B — render your alternate experience.
    document.querySelector("#cta").textContent = "Start free trial";
  }
  // Otherwise leave the control markup untouched.
}

renderExperiment();

Reading the visitor id (for example, to tag your own analytics event) is synchronous:

const { visitorId, assignments } = window.abtest.getVisitorData();
console.log(visitorId, assignments);

See the JS test workflow for how to structure a full test, including anti-flicker handling.

How assignments load

The runtime resolves each visitor's assignments before it fulfils isHypothesisActive:

1. On page load the runtime reads or creates the anonymous _ab_vid.
2. It uses a cached assignment cookie when one is present for that visitor; otherwise it calls the assign endpoint.
3. An internal promise resolves as soon as assignments are known — from cache or network — and every pending isHypothesisActive call resolves against them.

Because of this, you can call isHypothesisActive as early as you like; it will not resolve before assignments are available.

Requirements and scope

• App embed must be enabled. window.abtest only exists when the AB Test app embed (theme app extension) is turned on under Online Store → Themes → Customize → App embeds. Guard your code (if (window.abtest) …) if it might run on pages where the embed could be off.
• Enrolled experiments only. Both methods reflect only experiments the visitor is actually enrolled in, after any audience targeting rules are applied. A visitor filtered out of an experiment will never test true for its variants.
• Fails open. If assignments cannot be fetched, checks resolve to false and the visitor sees your control experience.
• Configuration. Endpoint and other runtime settings come from the injected config — see Runtime config.

Related

• JS test workflow — end-to-end structure of a JavaScript API test.
• Assign endpoint — the request the runtime makes to fetch assignments.
• Data & consent — setAnalyticsConsent and how consent is honored.
• JavaScript API tests — the merchant-facing guide.