Implement Web Experiment

Amplitude Academy

Getting Started with Amplitude Web Experimentation

Learn how to use Web Experimentation to fuel conversion rates in your web experiences and single-page apps.

Web Experiment requires a standalone script that you add to your website. Paste the script into the <head> element of your site, as high as possible to avoid flickering.

The script tracks impression events with the Browser SDK already installed on your site, or a third-party analytics SDK.

Add the experiment script

Replace API_KEY with your project's API key in one of the synchronous scripts below for your region.

html

<script src="https://cdn.amplitude.com/script/API_KEY.experiment.js"></script>

Security headers

Your site may need the following security header adjustments to work with Web Experiment.

If your site defines the script-src content policy directive, add *.amplitude.com and unsafe-inline to the policy values. These changes enable loading the Web Experiment script and visual editor on your site.

text

Content-Security-Policy: script-src *.amplitude.com unsafe-inline;

Async script with anti-flicker snippet

The synchronous script above provides the best experience for your users. To load the script asynchronously, include the following anti-flicker snippet. The snippet masks elements on the page until Amplitude applies all changes. Replace API_KEY with your project's API key and set the timeout to control when the anti-flicker mask clears.

html

<script>
  (function (d, h) {
    // TODO: Replace API_KEY with your API key.
    var apiKey = "API_KEY";
    // TODO: Set a timeout in milliseconds for the anti-flicker.
    var timeout = 1000;
    // Hides the page and loads the script. Shows page if script fails to load,
    // otherwise the script shows the page.
    var id = "amp-exp-css";
    try {
      if (!d.getElementById(id)) {
        var st = d.createElement("style");
        st.id = id;
        st.innerText =
          "* { visibility: hidden !important; background-image: none !important; }";
        h.appendChild(st);
        window.setTimeout(function () {
          st.remove();
        }, timeout);
        var sc = d.createElement("script");
        sc.src =
          "https://cdn.amplitude.com/script/" + apiKey + ".experiment.js";
        sc.async = true;
        sc.onerror = function () {
          st.remove();
        };
        h.insertBefore(sc, d.currentScript || h.lastChild);
      }
    } catch (e) {
      console.error(e);
    }
  })(document, document.head);
</script>

Integrate with a third-party customer data platform

If you use a customer data platform (CDP) other than Amplitude to send events, set up an integration to provide user identity information and track events. Without an integration, the script assumes Amplitude Browser SDK is installed on the same site.

The Web Experiment script supports common CDP integrations through an integration query parameter in the script URL.

Segment integration

Web experimentation supports Segment by default. Add integration=segment as a query parameter to the script URL. For example, in Amplitude's US region:

html

<!-- Replace API_KEY with your project's API key -->
<script src="https://cdn.amplitude.com/script/API_KEY.experiment.js?integration=segment"></script>

Tealium integration

If you send events through Tealium using Tealium iQ or Tealium AudienceStream & Universal Data Hub, you don't need to set up an integration. Tealium loads the Amplitude Analytics SDK onto the site, which integrates directly with the Web Experiment script.

Custom integrations

Implement the IntegrationPlugin interface and set the experimentIntegration window variable to add a custom integration. Place the plugin script before the Web Experiment script tag.

getUser(): object: Return the experiment user object.
track(): boolean: Track the event through a third party. Return true if tracking succeeded. Returning false causes Amplitude to persist the event and retry at an interval.
setup(): Promise<void>: (Optional) Set up the integration asynchronously. Returns a promise that resolves when the integration can return user information from getUser().

html

<script>
  window.experimentIntegration = {
    getUser: () => {
      // TODO: Return user
      return {
        user_id: "user",
        device_id: "device",
      };
    },
    track: (e) => {
      // TODO: Track event
      analytics.track(e.eventType, e.eventProperties);
      return true;
    },
  };
</script>
// TODO: Add the Web Experiment script tag

Contact support for help with a custom integration for your CDP.

Content management systems

Amplitude Web Experiment supports any content management system (CMS) that supports custom scripts. Amplitude provides plugins for Wordpress and Shopify.

Wordpress

Amplitude's Wordpress plugin enables Amplitude Analytics, Experiment, and Session Replay.

Shopify

Amplitude's Shopify App enables Amplitude Analytics, Experiment, and Session Replay on your Shopify site.

Shopify and flickering

The method Shopify uses to load Amplitude's Shopify app causes flickering. To avoid flickering, add the asynchronous web script with the anti-flicker snippet to your theme.liquid file.

Tag managers

Tag managers, such as Google Tag Manager, load scripts asynchronously, which causes flickering. Tag managers can help you start using the visual editor to create variants while you work on adding the Web Experiment script directly to the page. Amplitude recommends against using tag managers in production.

Google Tag Manager (GTM)

Causes flicker

Implementing Web Experiment with a tag manager causes flicker. Use a tag manager only when getting started, if adding the script to the site isn't possible.

Use a custom HTML tag to add the script through GTM.

Was this helpful?