A/B Testing API: Endpoints and Implementation

React Hooks @pack/hydrogen

These hooks tell your storefront which tests and variants a visitor is in. Use them to send test data to your analytics platform, or to render different code for each variant.

They read Pack's data from your root loader, so it must spread ...context.pack.getPackContextData() into its return value.

useAbTest()

Returns the test the visitor is in, or null if they are not in it.

useAbTest(testHandle?: string): Test | null

  interface Test {
    id: string;
    handle: string;
    testVariant: {
      id: string;
      handle: string;
    };
  }
  • With a test handle (4.0 and later): that test, or null if the visitor is not in it.
  • Without one: the visitor's oldest test.

A test is returned wherever the visitor is, including pages its targeting does not cover, where its content is not being shown.

Example

  import {useAbTest} from '@pack/hydrogen';
  ...

  export function Hero() {
    const heroTest = useAbTest('homepage-hero');

    return heroTest?.testVariant.handle === 'variant-b' ? (
      <p>I am variant B</p>
    ) : (
      <p>I am the control</p>
    );
  }

useAbTests()

Available from @pack/hydrogen 4.0. Returns every test the visitor is in, oldest first, including tests whose targeting does not cover the current page. It also includes any personalizations the visitor matches on the current request. The Test type has no field that marks a personalization, so tell them apart by handle. Returns an empty array when the visitor is in no tests.

useAbTests(): Test[]

import {useAbTests} from '@pack/hydrogen';
...

export function TestTracker() {
    const tests = useAbTests();
    // e.g. send tests.map((test) => test.handle) to your analytics
    return null;
}

useAbTestId()

Returns the id of the test the visitor is in. Takes the same optional test handle as useAbTest.

useAbTestId(testHandle?: string): string | undefined

import {useAbTestId} from '@pack/hydrogen';
...

export function Hero() {
    const testId = useAbTestId('homepage-hero');
    return (
      <div>
        My test ID is: {testId}
      </div>
    );
}

useAbTestHandle()

Returns the handle of the test the visitor is in. Takes the same optional test handle as useAbTest, so it is mostly useful without one, to read the visitor's oldest test.

useAbTestHandle(testHandle?: string): string | undefined

import {useAbTestHandle} from '@pack/hydrogen';
...

export function Hero() {
    const testHandle = useAbTestHandle();
    return (
      <div>
        My oldest test handle is: {testHandle}
      </div>
    );
}

useAbTestVariantId()

Returns the id of the variant the visitor is in. Takes the same optional test handle as useAbTest.

useAbTestVariantId(testHandle?: string): string | undefined

import {useAbTestVariantId} from '@pack/hydrogen';
...

export function Hero() {
    const testVariantId = useAbTestVariantId('homepage-hero');
    return (
      <div>
        My current variant ID is: {testVariantId}
      </div>
    );
}

useAbTestVariantHandle()

Returns the handle of the variant the visitor is in. Takes the same optional test handle as useAbTest.

Always pass the test handle. New tests name their variants control and variant-b, so without one you can read another test's variant-b while the visitor is in control of the test you are branching on.

useAbTestVariantHandle(testHandle?: string): string | undefined

import {useAbTestVariantHandle} from '@pack/hydrogen';
...

export function Hero() {
    const testVariantHandle = useAbTestVariantHandle('homepage-hero');
    return (
      <div>
        My current variant handle is: {testVariantHandle}
      </div>
    );
}

Warnings in development

In development, Pack logs a console warning when:

  • a hook is called without a test handle while the visitor is in more than one test, and
  • a hook is given a test handle but the root loader does not expose Pack's test list. It returns null, so your storefront falls back to its default content.

If the root loader does not spread getPackContextData() at all, useAbTest and the hooks built on it (useAbTestId, useAbTestHandle, useAbTestVariantId, useAbTestVariantHandle) throw ERR_HY_MISSING_AB_TEST_CONTEXT, and useAbTestSessionId throws ERR_HY_MISSING_SESSION_ID. useAbTests returns an empty list instead.

Debugging in the browser

@pack/react adds window.packDebug in the browser:

  • window.packDebug.getTestInfos() lists every A/B test the visitor is in, oldest first (@pack/react 4.6.0 and later).
  • window.packDebug.getTestInfo() returns a single test, as in earlier versions. Prefer getTestInfos().

Manually bucketing yourself into a test

To check a test is working, you can put yourself into a specific test and variant with URL query parameters.

  • Name
    test_handle
    Type
    string
    Description

    The handle of the test.

  • Name
    test_id
    Type
    string
    Description

    The id of the test. Use this or test_handle.

  • Name
    test_variant_handle
    Type
    string
    Description

    The handle of the variant to show, such as control or variant-b.

  • Name
    test_variant_id
    Type
    string
    Description

    The id of the variant to show. Use this or test_variant_handle.

Each parameter also works in camelCase (testId, testVariantHandle) or kebab-case (test-id, test-variant-handle). When these parameters are present, the test's status is ignored, so you can preview a test that is not running yet.

Include one test parameter and one variant parameter, in any combination:

  • ?test_handle=ZZZ&test_variant_handle=YYY
  • ?test_id=ZZZ&test_variant_id=YYY
  • ?test_handle=ZZZ&test_variant_id=YYY
  • ?test_id=ZZZ&test_variant_handle=YYY

Pack also accepts the camelCase and hyphenated spellings, such as testHandle and test-handle.

Selecting a test variant with headers

Underneath the hooks and URL parameters, the Pack GraphQL API picks a test variant from request headers. Use them to check a variant's content against the API directly, for example with curl or from a test suite. Authenticate as in the Content Management API.

  • Name
    X-Pack-Test-Handle
    Type
    string
    Description

    The handle of the test.

  • Name
    X-Pack-Test-Id
    Type
    string
    Description

    The id of the test. Use this or X-Pack-Test-Handle.

  • Name
    X-Pack-Test-Variant-Handle
    Type
    string
    Description

    The handle of the variant, such as control or variant-b.

  • Name
    X-Pack-Test-Variant-Id
    Type
    string
    Description

    The id of the variant. Use this or X-Pack-Test-Variant-Handle. When both are sent, the id is used.

  • Name
    X-Pack-Test-Ignore-Test-Status
    Type
    'true'
    Description

    Serve the variant even if its test isn't running, as the test URL parameters do. Responses with this header are never served from the edge cache.

Send one test header and one variant header, in any combination. How Pack answers:

  • A running test's variant: the content with that variant applied.
  • control: the base content.
  • A test that isn't running, without X-Pack-Test-Ignore-Test-Status: the base content. The request doesn't fail, so check the test's status in Pack when a variant doesn't appear.
  • A test or variant that doesn't exist in the store and content environment: the base content.

The test and variant headers are part of the edge cache key, so each variant is cached separately.

Example

curl https://apicdn.packdigital.com/graphql \
  -H "Authorization: Bearer $PACK_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Pack-Test-Handle: about-us-hero" \
  -H "X-Pack-Test-Variant-Handle: variant-b" \
  -d '{"query": "{ pageByHandle(handle: \"about-us\") { isTestVariant sections(first: 25) { nodes { id data } } } }"}'

isTestVariant on a page, product page, collection page, template or site settings is true when a test variant was applied to it, which tells a non-running test's base content apart from a variant.

Was this page helpful?