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>
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, orcxApi.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. IfcxApi.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). IfcxApi.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.