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:

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:

Caution: Choosing a variation does
not actually send any data to Google Analytics. You will need to ensure that
after choosing a variation, at least one hit is sent to Google
Analytics, such as a pageview, event, etc.

Example

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

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.

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:

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.

Note: Setting the experiment values does
not actually send any data to Google Analytics. You will need to ensure that
after setting the experiment values, at least one hit is sent to Google
Analytics, such as a pageview, event, etc.

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.

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