runAbExperiment

Run one A/B experiment: pick a weighted variant, apply it, and label every collector event of this page impression with the assignment. Call it before start() — the variant has to be in effect before htag schedules ads.

For QA, adnz_ab can force a matching variant while still respecting eligible(). The forced run bypasses sticky selection and carries ab_forced: 'true' in telemetry.

Example

window.htag.api('1').runAbExperiment({
  name: 'image_size.v1',
  sticky: true,
  eligible: () => window.top.innerWidth >= 1024,
  attributes: { device: 'desktop' },
  variants: [
    { key: 'control', weight: 1 },
    {
      key: 'large',
      weight: 1,
      apply: () => {
        window.htag.api('1').setLazyLoadingConfig((current) => current.map((config) => ({ ...config, safetyPx: 800 })));
      },
    },
  ],
});

Parameters

• definition (required): The experiment.
  • name: Experiment identifier matching ^[a-z0-9_.-]{1,64}$. Also the sticky storage key and the ab_experiment tag value.
  • variants: At least two variants with unique keys.
    • key: Variant identifier matching ^[a-z0-9_.-]{1,64}$. Becomes the ab_variant tag value.
    • weight: Finite number greater than zero. Weights are relative, so 1 against 3 is a 25/75 split.
    • apply (optional): Called when this variant is selected. Omit it for the control arm.
  • eligible (optional): Enrolment predicate. A falsy result — or a throw — means the visitor is not enrolled and their events stay untagged.
  • attributes (optional): Extra measurement tags, or a function returning them. Keys are strict identifiers, values are strings of 1 to 256 characters.
  • sticky (optional): Remember the variant per visitor in the top window’s localStorage under adnz-ab-experiment-<name>.

Order of Operations

1. Validate the definition. An invalid one is logged and the call does nothing.
2. Single-run guard: if an experiment is already assigned on this page impression, log and stop. The first experiment to apply wins.
3. Eligibility: run eligible(); stop if it is falsy or throws.
4. Resolve attributes and validate them, before anything is applied.
5. Select the variant — the stored sticky bucket if there is a valid one, otherwise a weighted draw.
6. Apply the variant.
7. Record the assignment, and persist the sticky bucket.

Error Behaviour

Every failure is contained; nothing here throws into your RawJS.

• Invalid definition — bad name, fewer than two variants, a duplicate variant key, a non-positive or non-finite weight: logged, nothing runs.
• eligible() throws: treated as not eligible.
• attributes throw, or the bag is invalid: an error is logged and the experiment runs without the extras. It is still tagged with ab_experiment and ab_variant. The bag is dropped as a unit — one malformed key loses all of them.
• apply() throws: logged; no assignment is recorded and no sticky bucket is written, so the page runs untreated and untagged rather than treated-but-unmeasured.

Return Value

Returns the Htag API object, allowing for method chaining.

Related Methods

• runAbExperiments: Run the first eligible experiment of a set and prune stale sticky buckets
• addRawJs: Deliver the experiment declaration with the tag

Related Concepts

For weighting, sticky bucketing, telemetry tagging and the pitfalls to avoid, see the A/B Testing concept documentation.