Google Analytics

Experiments - Web Tracking (ga.js)

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

  1. Overview
  2.  
  3. Standard Implementation
  4. Browser-only Implementation
  5. Server-side Implementation
  1. Content Experiments JavaScript API Reference
    1. Loading the API Client
    2. cxApi Object Constants
    3. cxApi Object Methods
    4. Experiment Cookies
More

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 ga.js library.

This implementation uses client-side redirects to show visitors 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 visitor when using the ga.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 visitor 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 visitor, the following steps need to be executed each time a visitor is exposed to an experiment:

  1. Load the Content Experiments JavaScript API client using the experiment query parameter to specify the ID of the experiment running on the page
  2. Call the chooseVariation method.
  3. Evaluate the return value from the chooseVariation method and take the appropriate action. (e.g. change the image, button color, etc.)
  4. Load the ga.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 visitor 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 Visitor
  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 ga.js and send a hit to Google Analytics -->
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

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

Server-side Implementation

For implementations where variation choices are made on the server, the Content Experiments JavaScript API can be used to report to Google Analytics which variation was shown to the visitor.

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 visitor, and this is also from where the ga.js library sends data to Google Analytics. So coordination is required between server and client to properly send experiment data to Google Analytics for visitors that are exposed to an experiment.

The values to send to Google Analytics are:

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

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

  1. Load the Content Experiments JavaScript API client and
  2. call the setChosenVariation method with the experiment id and chosen variation.
  3. Load the ga.js library and 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 visitor. This will ensure that when the variation page is rendered in the visitor's browser, the experiment values for the visitor are set and then sent to Google Analytics with the next hit from ga.js.

Example

Typically for each visitor you would determine on the server if there is an experiment running on the page and if so which variation to show the visitor. 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 visitor
$chosenVariation= 2;
?>

With the experiment ID and variation chosen for the visitor, 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>

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

<!-- 2. Set the chosen variation for the Visitor (Dynamically in this case) -->
<script>
<?php
<<<HTML
  cxApi.setChosenVariation(
    $chosenVariation,             // The index of the variation shown to the visitor
    $experimentId                 // The id of the experiment the user has been exposed to
  );
HTML;
?>
</script>
<!-- End Set Experiment Values -->

<!-- 3. Load ga.js and send a hit to Google Analytics -->
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

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

Once the PHP script is done executing, the experiment values required for the setChosenVariation method 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 next hit from the ga.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>

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

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 ga.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 be set to the same value specified for the ga.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 be set to the same value specified for the ga.js tracking code.

cxApi.setAllowHash(allowHash);

Parameters

  • Boolean allowHash – Whether to allow domain hashing.






Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.