Introduction to Analytics.js

Analytics.js is a JavaScript library for measuring how users interact with your website. It is similar to the previous tracking library, ga.js, but offers more flexibility for developers to customize their implementations.

Quick Start

To begin tracking a website using analytics.js, paste the following JavaScript snippet into your website templates so that it appears before the closing </head> tag. The 'UA-XXXX-Y' parameter must be replaced with the Property ID for the Google Analytics Property you wish to track.

<!-- 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','//www.google-analytics.com/analytics.js','ga');

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

</script>
<!-- End Google Analytics -->

When this code runs, it asynchronously loads the analytics.js library onto the page, creates a tracker object for the property you specified via the 'UA-XXXX-Y' parameter, and then sends a pageview hit for the current page to Google Analytics.

How analytics.js works

The JavaScript snippet above works by default for most websites. It will record pageviews for every page on your site containing that code.

To measure more than pageviews (e.g. events, exceptions, social interaction) you will need additional code. The following sections provide a basic understanding of how the analytics.js library works to help you write your own custom implementation(s).

The `ga` function

The ga function provides a single access point for everything in the analytics.js library. Having a single function that does everything allows the JavaScript snippet to be very small, and it minimizes the chances that the analytics.js library will conflict with other code on the page.

The JavaScript snippet above initially defines the ga function as a simple queue. All arguments passed to it are stored in an internal array. Once the analytics.js library is loaded, each call in the queue is executed and the ga function is redefined so all subsequent calls execute immediately. Initializing the ga function as a queue gives developers a consistent API to use regardless of whether the analytics.js library has finished loading.

It's important to note that although all tracking calls are made via the ga function, the ga function is not the tracker object itself. Tracker objects are stored privately and made accessible through the ga function's interface.

Creating a tracker

Tracker objects (also known as "trackers") are objects that can collect data and send that data as a Measurement Protocol hit to a Google Analytics property.

When a new tracker object is created, analytics.js gathers information about the current browsing context and stores that information on the tracker. This includes the client ID (which it reads from the cookie or creates if the cookie doesn't exist), information about the page such as its title and URL, and information about the device such as screen resolution, viewport size, and document encoding. When it's time to send hits to Google Analytics, all of the information currently stored on the tracker gets sent.

To create a tracker, call the create method and pass it the Google Analytics property ID as well as an optional configuration object.

The following code creates a tracker for the property 'UA-XXXX-Y' and passes the 'auto' option to signify automatic cookie domain configuration. Note, the 'auto' option is recommended for most implementations.

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

Sending hits

The last line in the JavaScript snippet invokes the send method and sends a pageview hit to Google Analytics.

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

The data that gets sent is whatever data is currently stored on the tracker object that was created in the previous line of code.

Note: The send method uses the data stored on the current tracker, but it never references that tracker in its call. This works because most websites only create one tracker, so analytics.js optimizes for this case. When using the send method without specifying a tracker name, the default tracker (the first one created) is assumed. For information about using analytics.js with more than one tracker, see the Working with multiple tracking object section of the Advanced configuration guide.

When sending hits, you can also override the data that is sent. The send method accepts an optional object of field/value pairs that will be used for that hit only.

ga('send', 'pageview', {
  page: '/about',
  title: 'About Us'
});

It's important to emphasize that these overrides will only apply to the current hit that's being sent. They will not update the data stored on the tracker object, and they will not be applied to subsequent hits.

For single page applications or other sites that load new content dynamically, it's usually better to update the tracker object itself rather than specify overrides in a send call. Keeping the tracker object as the single source of truth will help ensure all the data you send to Google Analytics is correct.

Updating a tracker

Tracker objects can be updated using the set method.

// Set a single field.
ga('set', 'page', '/about');

// Set multiple fields.
ga('set', {
  page: '/about',
  title: 'About Us'
});

Note: as with the send method, calling set without specifying a tracker name will update the default tracker object.

Once a tracker object has been updated, future calls to send will use the updated data rather than the original data gathered at creation time.