dan1978@gmx.net | My favorites ▼ | English ▼ | Sign out
Skip to page content Skip to main navigation
e.g. "adwords" or "open source"

# Asynchronous Tracking Usage Guide

The asynchronous snippet allows browsers to continue rendering the page while `ga.js` loads in the background. Since the browser might encounter tracking API calls before `ga.js` has finished loaded, a different syntax must be used for customizing your snippet. This document covers how to make tracking API calls using the asynchronous syntax. See the Migration Examples page for a side-by-side comparison of the traditional and asynchronous syntaxes.

## The Asynchronous Syntax

The `_gaq` object is what makes the asynchronous syntax possible. It acts as a queue, which is a first-in,first-out data structure that collects API calls until `ga.js` is ready to execute them. To add something to the queue, use the `_gaq.push` method.

To push an API call onto the queue, you must convert it from the traditional JavaScript syntax into a command array. Command arrays are simply JavaScript arrays that conform to a certain format. The first element in a command array is the name of the tracker object method you want to call. It must be a string. The rest of the elements are the arguments you want to pass to the tracker object method. These can be any JavaScript value.

The following code calls `_trackPageview()` using the traditional syntax:

    var pageTracker = _gat._getTracker('UA-XXXXX-X');
    pageTracker._trackPageview();

The equivalent code in the asynchronous syntax requires two calls to `_gaq.push`.

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

In the asynchronous syntax, the creation of the tracker object is implied, but we still need a way to set the web property ID for the tracker. The `_setAccount` method has been added to provide this capability. All the other tracker object methods are the same in both asynchronous and traditional tracking. Only the syntax is different.

For more information on the asynchronous syntax, see the Tracking Reference for the `_gaq.push` method.

Back to Top

## HTML Event Handlers

The asynchronous tracking syntax should also be used from within DOM event handlers. For example, the following button generates an event when it is clicked.

    <button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"/><button>

Even if this button is clicked before the browser has finished loading `ga.js`, the event will be captured and eventually executed. Using traditional tracking, the browser might throw an exception in this situation.

Back to Top

## Pushing Functions

In addition to command arrays, you can also push function objects onto the `_gaq` queue. The functions can contain any arbitrary JavaScript and like command arrays, they are executed in the order in which they are pushed onto `_gaq`. This technique is useful for calling the tracking APIs that return values. For example, the following code builds a linker URL and sets the `href` property for a link with the result.

    _gaq.push(function() {
      var pageTracker = _gat._getTracker('UA-XXXXX-X');
      var link = document.getElementById('my-link-id');
      link.href = pageTracker._getLinkerUrl('http://example.com/');
    });

The example above uses `_gat` to create a tracker object, but because it is assigned to a local variable, code outside of the function cannot use it. While this is acceptable, you can use the `_gat._createTracker` method to create a permanent, globally accessible object. The following code demonstrates how this would work.

    _gaq.push(function() {
      var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
      var link = document.getElementById('my-link-id');
      link.href = pageTracker._getLinkerUrl('http://example.com/');
    });

    _gaq.push(['myTracker._trackPageview']);

The example above creates an asynchronous tracker inside the function and then references it later by name in the command array.

The opposite use case is also possible. For example, if you need to use an asynchronous tracker object created via a previously pushed command array, use the `_gat._getTrackerByName` method. The following code demonstrates how it works.

    _gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

    _gaq.push(function() {
      var pageTracker = _gat._getTrackerByName('myTracker');
      var link = document.getElementById('my-link-id');
      link.href = pageTracker._getLinkerUrl('http://example.com/');
    });

Back to Top

## One Push, Multiple Commands

Instead of typing `_gaq.push(...)` for each call, you can push all of your commands at once. The following code demonstrates this technique.

    _gaq.push(
      ['_setAccount', 'UA-XXXXX-X'],
      ['_setDomainName', 'example.com'],
      ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
      ['_trackPageview']
    );

This works because the `_gaq.push` method imitates the `Array.push` method, which allows pushing multiple items with one invocation.

Pushing commands to multiple trackers also works.

    _gaq.push(
      ['_setAccount', 'UA-XXXXX-1'],
      ['_trackPageview'],
      ['b._setAccount', 'UA-XXXXX-2'],
      ['b._trackPageview']
    );

Back to Top

## Split Snippet

If you prefer to put the Analytics snippet at the bottom of the page, you should know that you don't have to put the whole snippet at the bottom. You can still keep most of the benefits of asynchronous loading by splitting the snippet in half—keep the first half at the top of the page and move the rest to the bottom. Because the first part of the tracking snippet has little to no afect on page rendering, you can leave that part at the top and put the part of the snippet that inserts `ga.js` at the bottom.

A page with the asynchronous snippet split in half might look like this:

    <html>

    <head>
      <script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', 'UA-XXXXX-X']);
        _gaq.push(['_trackPageview']);
      </script>
    </head>

    <body>
      <p>Page Content</p>

      <script src="some_random_script.js"></script>

      <p>Page Content</p>

      <script type="text/javascript">  (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>
    </body>
    </html>

Both pieces of code need to be wrapped in their own script tags, but only the last six lines of the original asynchronous snippet need to be moved to the bottom. All the lines that push methods onto `_gaq` can stay at the top.

Back to Top

## Common Pitfalls

When using either the asynchronous or traditional syntax, keep in mind the following:

- Method names are case-sensitive.
  If you use a method name without the proper casing, your method calls will not work. Examples:

      _gaq.push(['_trackpageview']);   // bad
      _gaq.push(['_trackPageview']);   // good

- Use the correct method names.
  If your tracking is not working correctly, check to make sure you are using the correct name for the method. Examples:

      _gaq.push(['_setDomain', 'example.com']);       // bad
      _gaq.push(['_setDomainName', 'example.com']);   // good

- Only strings should be passed in with quotes. All other types should be left unquoted.
  Any value that is not a string, such as a booleans, object literals, functions or arrays, should be passed in without quotation marks. Use only quotation marks when you are passing in something that is meant to be interpreted as a string. If you are migrating from the traditional syntax, any function parameter that was passed in without quotation marks should remain unquoted in the asynchronous syntax. Examples:

      _gaq.push(['_setAllowLinker', 'false']);    // bad
      _gaq.push(['_setAllowLinker', false]);      // good

- Make sure that strings do not contain leading or trailing whitespace.
  Examples:

      _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
      _gaq.push(['_setAccount', 'UA-65432-1']);     // good

Back to Top

Suggestions