Shared OptimizelyX Fragment for AS24 Pages

AS24<->OptimizelyX integration helper fragment

• Shared OptimizelyX Fragment for AS24 Pages
  • What do we use OptimizelyX for?
  • What does this fragment do?
  • How to use OptimizelyX?
    • Installing type-definitions
    • ⚠️ Caution
    • The variation map a.k.a. the test bucket in which the user has landed
    • Getting and using the variationMap
    • Tracking events
  • Tracking events with a custom element
  • Add the fragment to your page
  • Convenience helpers
    • Campaign decided helper
  • Publishing new version

What do we use OptimizelyX for?

We use Optimizely for conducting multivariant tests (A/B tests).

What does this fragment do?

This fragment loads the OptimizelyX JS (client side) API in an optimized way: asynchronously but still very fast.

Our main Project "AS24 CXP" is hardcoded in the currently only fragment. Other projects are welcome to join.

Optimizely Full Stack is out of scope of this project.

How to use OptimizelyX?

For detailed API reference please check out the official Optimizely docs

Installing type-definitions

This package kindly provides TypeScript declarations for OptimizelyX (WIP) and the custom-element integration. You can benefit from these by installing

yarn add -D as24-optimizely-fragment

and importing the declarations somewhere in your app

import 'as24-optimizely-fragment';

The definitions will make the window object aware of the different optimizely methods and response types, plus patch the JSX namespace to support the as24-optimizely-fragment custom element. They will also make sure you check the existance of window.optimizely and window.optimizelyReady since they might not be present in the page depending on script order or fragment inclusion.

⚠️ Caution

There is no guarantee that window.optimizely is defined (e.g. fragment is not included, ad blocker blocks optimizely, etc.) or library hasn't loaded yet. Therefore, either

a) make sure optimizely is initialized (this happens automatically if you use the optimizelyReady promise) b) or include this line in your codebase before interacting with the Optimizely API (push-functionality only).

window.optimizely = window.optimizely || [];

TypeScript users: to prevent runtime errors, you'll need to check for window.optimizely existance and methods besides push .

The variation map a.k.a. the test bucket in which the user has landed

{
    '6661191859': {
        //experiment ID
        id: '6670551924', // variation ID
        name: 'Variation #1',
        index: '1' // variation index
    }
}

Getting and using the variationMap

const onOptimizelyReady = () => {
    const experimentID = '6661191859';

    const state = window.optimizely.get('state');
    const variationMap = state.getVariationMap();
    const experiment = variationMap[experimentID];
    const defaultVariationIndex = 0;

    // showVariation is defined by the developer
    // This function shows the variant which the users was bucketed to or the default if user is not in the experiment.
    showVariation(experiment ? experiment.index : defaultVariationIndex);
};

window.optimizely = window.optimizely || [];

if (!window.optimizely.initialized) {
    window.optimizely.push({
        type: 'addListener',
        filter: {
            type: 'lifecycle',
            name: 'initialized'
        },
        handler: onOptimizelyReady
    });
} else {
    // Optimizely has already been initialized. Our code is only executed after Optimizely initialization.
    onOptimizelyReady();
}

Tracking events

window.optimizely = window.optimizely || [];
window.optimizely.push({
    type: 'event',
    eventName: 'watchedVideo',
    tags: {
        // Additional metadata for targeting (optional)
        title: 'Funny Cats',
        duration: 30
    }
});

Tracking events with a custom element

<as24-optimizely
    action="push"
    payload='
    {
        "type": "event",
        "eventName": "watchedVideo",
        "tags": {
            "title": "Funny Cats",
            "duration": 30
        }
    }
'
></as24-optimizely>

Add the fragment to your page

<!-- #include virtual="/fragment/optimizely/as24-cxp/" -->

Convenience helpers

This fragment defines a promise in the head of the document which resolves after the Optimizely snippet has been loaded and executed.

The promise resolves with an object which already has some useful objects, e.g. variationMap. This could also be extended.

const { optimizely, state, variationMap } = await window.optimizelyReady;

Campaign decided helper

Getting the correct status for an experiment can be cumbersome. In particular when the traffic allocation for the experiment is less than 100% it's possible that the user is assigned a variation but that variation is in holdback. This means that the user is actually not part of the experiment audience. In order to do so we need to hook into the campaignDecided callback doc.

In order to simplify this, window.optimizelyHelper is available. Using optimizelyHelper.get(experimentId) returns a promise that always resolves. If the user is not part of the experiment it will resolve with a { error: string } object, otherwise it will resolve with a CampaignEventData object.

Publishing new version

The types are exported to the public npm registry for easy consumption. You can simply run from your local machine

yarn publish --patch --message 'YOUR COMMIT MESSAGE HERE'

the first time yarn will ask for a username: autoscout24 and email #[email protected]. Ask in slack's engagement or acquisition channels for the password.

(where you can use --patch, --minor or --major depending on the version bump you want)

Only the files listed in the "files" section of package.json are included