Experiments | Analytics for Web (analytics.js)

This guide describes how to use content experiments with analytics.js.

Overview

The Google Analytics Content Experiments Framework enables you to test almost any change or variation to a property to see how it performs in optimizing a specific goal. For example, increasing goal completions or decreasing bounce rates. This allows you to identify changes worth implementing based on the direct impact they have on the performance of your website.

This document is intended for users with advanced requirements and developers that want to integrate Google Analytics experiments into their service as described in the Experiments Feature Reference.

Standard Implementation

If you're just getting started with Content Experiments then you should consider using the standard implementation for your website. Most of the implementation steps can be completed with the Google Analytics web interface and it will provide the necessary JavaScript code that will work with the analytics.js library.

This implementation uses client-side redirects to show users the variation chosen for them. Visit the Google Analytics help center to learn about the benefits of experiments and how to implement experiments on your website. To learn more read:

Benefits of Experiments (Help Center) — an overview of content experiments and what you can do with them.
Run an Experiment (Help Center) — learn how to prepare, configure, and track the progress of experiments.

Browser-only Implementation

For implementations where variation choices are made client-side in the browser, the Content Experiments JavaScript API can be used to perform most of the work associated with selecting a variation and storing experiment values for a user when using the analytics.js library.

This type of implementation is often used when you are testing changes by altering the DOM/CSS of a page using JavaScript. In other words, all variation decisions and changes per user are made client-side in the browser. For example, you might run an experiment to test variations of:

Images on the page.
Button colors.
Font size.
Page content.

To choose a variation for a user, the following steps need to be executed each time a user is exposed to an experiment:

Load the Content Experiments JavaScript API client using the experiment query parameter to specify the ID of the experiment running on the page
Call the chooseVariation method.
Evaluate the return value from the chooseVariation method and take the appropriate action. (e.g. change the image, button color, etc.)
Load the analytics.js library and send at least one hit to Google Analytics (e.g. pageview, event, etc.).

Example

The following is a simple example that will choose a variation for each user and show the corresponding image.

<html>
<head>
<!-- 1. Load the Content Experiments JavaScript Client -->
<script src="//www.google-analytics.com/cx/api.js?experiment=YByMKfprRCStcMvK8zh1yw"></script>

<script>
  var image_variations = [
      'original.png',
      'variation1.png',
      'variation2.png'
  ]

  // 2. Choose the Variation for the User
  var variation = cxApi.chooseVariation();

  window.onload = function(){
    // 3. Evaluate the result and update the image
    exp_image = document.getElementById('hero_image');
    exp_image.src = image_variations[variation];
  }
</script>

<!-- 4. Load analytics.js and send a hit to Google Analytics -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXXX-Y', 'auto');
  ga('send', 'pageview');

</script>
</head>
<body>
  <h1>Welcome</h1>
  <img id="hero_image"/>
  <p>Welcome to my experiment!</p>
</body>
</html>

Server-side Implementation

This type of implementation is often used to:

Run experiments for websites with dynamic content.
Test non-UI changes that still have an affect on your objective. For example, a database query result set that is returned to a user.
Integrate Google Analytics experiments with your service (e.g. Content Management provider).
Manage experiments using your own optimization platform.

In this case the variation choice is performed on the server, but the browser is ultimately where the variation is displayed to the user, and this is also from where the analytics.js library sends data to Google Analytics. So coordination is required between server and client to properly send experiment data to Google Analytics for users that are exposed to an experiment.

The values to send to Google Analytics are:

Experiment ID — the ID of the experiment the user has been exposed to.
Chosen Variation — The index of the variation shown to the user.

You can use the analytics.js set method to report to Google Analytics which variation was shown to the user.

To set the experiment values, the following steps need to be executed each time a user is exposed to an experiment and shown a variation:

Load the analytics.js library.
Set the Experiment ID expId.
Set the Experiment Variant expVar to the chosen variation.
Send at least one hit to Google Analytics (e.g. pageview, event, etc.).

You should use server logic to dynamically write the required JavaScript to set the experiment ID and variation number to the final page shown to the user. This will ensure that when the variation page is rendered in the user's browser, the experiment values for the user are set and then sent to Google Analytics with the hit from analytics.js.

Example

Typically for each user you would determine on the server if there is an experiment running on the page and if so which variation to show the user. However, in the PHP example below, the experiment id and variation number are defined at the start of the page for simplicity.

<?php
// The Id of the experiment running on the page
$experimentId = 'YByMKfprRCStcMvK8zh1yw';

// The variation chosen for the user
$chosenVariation= 2;
?>

With the experiment ID and variation chosen for the user, the next step is to include some logic to dynamically write the experiment data into the JavaScript string required to set experiment values:

<html>
<head>
<script>
  // 1. Load analytics.js -->
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXXX-Y', 'auto');

  // 2. Set the chosen variation for the User (Dynamically in this case) -->
<?php
<<<HTML
  ga('set', 'expId', '$experimentId');     // The id of the experiment the user has been exposed to.
  ga('set', 'expVar', '$chosenVariation'); // The index of the variation shown to the user.
HTML;
?>

  // 3. Send a pageview hit to Google Analytics.
  ga('send', 'pageview');

</script>
</head>
<!-- Begin body -->

Once the PHP script is done executing, the experiment values will be printed to the page. Once the JavaScript on the page is rendered in the browser, all the experiment values will be set and then sent with the pageview hit from the analytics.js library.

Content Experiments JavaScript API Reference

The Content Experiments JavaScript API can be used to:

Choose a variation for a user — For client-side implementations, this API provides an easy way to select an experiment variation for a new user or get the variation for which the user has already been exposed.
Set the chosen variation for a user — This is useful when handling experiment choices server-side and you want to report the chosen variation to Google Analytics from the client.
Get the chosen variation for a user — Retrieve a previously stored chosen variation for a user.

Loading the API Client

To load the Content Experiments JavaScript API client on an experiment page, you add a snippet of JavaScript to the page:

<script src="//www.google-analytics.com/cx/api.js"></script>

or you can use an experiment query parameter to specify an experiment ID and load information for that experiment.

<script src="//www.google-analytics.com/cx/api.js?experiment=YByMKfprRCStcMvK8zh1yw"></script>

You should specify the experiment id when loading the client if you plan to use the chooseVariation method. If you choose variations server-side and do not plan to use the chooseVariation method, then you should load the client without specifying an experiment ID to take advantage of the performance gain due to browser caching of the script.

The client loads synchronously and creates a global object named cxApi. Developers use the cxApi object to choose variations, and set and get experiment values.

cxApi Object Constants

There are three constants used to define common variations:

cxApi.ORIGINAL_VARIATION – To indicate the original content of an experiment.
cxApi.NO_CHOSEN_VARIATION – To indicate that no variation has been chosen for the user.
cxApi.NOT_PARTICIPATING – To indicate the user is not participating in the experiment.

cxApi Object Methods

chooseVariation

Chooses a variation for the user.

If the user is already part of the experiment, chooseVariation will return the variation number to which the user has already been exposed (unless the experiment is over or that variation is disabled, in which case, it'll return cxApi.ORIGINAL_VARIATION, specifying the original). If the user is new to the experiment, it will determine whether to include the user in the experiment based on the configured participation rate. If the user is included then it'll use the experiment weights to randomly select a variation for the user and write the value to a cookie.

chooseVariation simplifies the process of determining which variation to show a user. It will always return a variation even if the user isn't included in the experiment, in which case it will return cxApi.ORIGINAL_VARIATION. In comparison, the getChosenVariation tells you which variation was previously chosen for a user, including whether no variation has been chosen for the user or if the user is excluded from the experiment

Note: To use the chooseVariation method requires that you specify the ID of the experiment when loading the client.

cxApi.chooseVariation();

Returns

Integer – The index of the chosen variation.

Examples

Choose the variation to show the user:

variationNumber = cxApi.chooseVariation();

setChosenVariation

Sets the variation that has been chosen for the user exposed to an experiment and writes the values to a cookie.

cxApi.setChosenVariation(chosenVariation, opt_experimentId);

Parameters

Integer chosenVariation – The index of the variation shown to the user, or cxApi.NOT_PARTICIPATING.
String opt_experimentId – The experiment id for which to set the chosen variation. If not provided, uses the first experiment specified when loading the client.

Examples

Set the chosen variation for the user:

cxApi.setChosenVariation(2, ‘YByMKfprRCStcMvK8zh1yw’);

Set the chosen variation for the user when the experiment ID is specified during client load:

cxApi.setChosenVariation(2);

getChosenVariation

If it is available, gets the previously chosen variation for the user.

cxApi.getChosenVariation(opt_experimentId);

Parameters

String opt_experimentId – The experiment id for which to get the chosen variation. If not provided, uses the first experiment specified when loading the client.

Returns

Integer – The index of the chosen variation for the user. If cxApi.NO_CHOSEN_VARIATION is returned, this indicates that the user is new to the new experiment and you will need to determine what to do with the user (e.g. choose a variation). If cxApi.NOT_PARTICIPATING is returned, this indicates a returning user that was not chosen to be included in the experiment.

Examples

Get the chosen variation for the user:

variationNumber = cxApi.getChosenVariation(‘YByMKfprRCStcMvK8zh1yw’);

Get the chosen variation for the user when the experiment ID is specified during client load:

variationNumber = cxApi.getChosenVariation();

Experiment Cookies

The API includes some optional calls that customize how the cookie is saved.

setDomainName

Sets the domain name to be used when writing experiment cookies. This should be set to the same value specified for the analytics.js tracking code.

cxApi.setDomainName(domainName);

Parameters

String domainName – The domain name to use.

setCookiePath

Sets the cookie path to use when writing the experiments cookie. This should be set to the same value specified for the analytics.js tracking code.

cxApi.setCookiePath(cookiePath);

Parameters

String cookiePath – The cookie path to use.

setAllowHash

Sets the cookie domain hash setting to use when writing the experiments cookie. This should be set to the same value specified for the analytics.js tracking code.

cxApi.setAllowHash(allowHash);

Parameters

Boolean allowHash – Whether to allow domain hashing.