This guide describes how to measure periods of time using analytics.js.
Overview
Studies have shown that reducing page load time improves the overall user experience of a site. Google Analytics has a number of powerful reports that automatically measure and report on page load times. However, it is also possible to track custom timing information to measure performance information specific to your site. For example to measure the time it takes for a particular JavaScript library to load.
User Timings allow developers to measure periods of time using the analytics.js library. This is particularly useful for developers to measure the latency, or time spent, making AJAX requests and loading web resources.
User timings are measured using the following four fields::
| Value | Type | Required | Description |
|---|---|---|---|
| timingCategory | String |
Yes | A string for categorizing all user timing variables into logical groups (e.g jQuery). |
| timingVar | String |
Yes | A string to identify the variable being recorded. (e.g. JavaScript Load). |
| timingValue | Number |
Yes | The number of milliseconds in elapsed time to report to Google Analytics. (e.g. 20) |
| timingLabel | String |
No | A string that can be used to add flexibility in visualizing user timings in the reports. (e.g. Google CDN) |
Implementation
To send user timing data, you pass the ga function
the send command with the timing hit type
ga('send', 'timing', 'jQuery', 'Load Library', 20, 'Google CDN');
Where:
jQueryis thetimingCategoryLoad Libraryis thetimingVar20is thetimingValueGoogle CDNis thetimingLabel
As the timingLabel is optional, it can be omitted from the
send command:
ga('send', 'timing', 'timingCategory', 'timingVar', timingValue);
The send command also accepts an optional field object
as the last parameter for any of these commands. The field object is
a standard JavaScript object, but defines specific field names
and values accepted by analytics.js.
For example, you might want to set the page field
for a particular user timing. You do this using:
ga('send', 'timing', 'timingCategory', 'timingVar', timingValue, 'timingLabel', {'page': '/my-new-page'});
Finally, all the parameters of the send command have
their own field names. So you can send a user timing by passing only
a field object to the send command:
ga('send', {
'hitType': 'timing',
'timingCategory': 'jQuery',
'timingVar': 'Load Library',
'timingValue': 20,
'timingLabel': 'Google CDN',
'page': '/my-new-page'
});
Read the Field Reference document for a complete list of all the fields that can be used in the configuration field object.
Example
When sending user timing data, you specify the amount of milliseconds
spent in the timingValue parameter. It’s up to you,
the developer, to write code to capture this period of time.
The easiest way to do this is to create a timestamp at the beginning
of a period of time and create another timestamp at the end of the
period. Then you can take the difference between both timestamps to
get time spent.
Here’s a great example:
Today, many sites include 3rd party JavaScript libraries or request data through JSON objects. While your site might load these resources quickly at home, the same resources might load very slowly for users in other countries. These slow loading resources can degrade the site experience for international users.
The site speed user timing feature can help you collect and report how long these resources take to load.
Here’s a simple example demonstrating how to track the time spent of a function that asynchronously loads JavaScript resources:
var startTime;
function loadJs(url, callback) {
var js = document.createElement('script');
js.async = true;
js.src = url;
var s = document.getElementsByTagName('script')[0];
js.onload = callback;
startTime = new Date().getTime();
s.parentNode.insertBefore(js, s);
}
function trackTimingCallback(event) {
var endTime = new Date().getTime();
var timeSpent = endTime - startTime;
ga('send', 'timing', 'jQuery', 'Load Library', timeSpent, 'Google CDN');
// Library has loaded. Now you can use it.
};
In this example, loadJs is a utility function
that loads JavaScript resources by dynamically creating a
script element and attaching it to the browser’s DOM. The function
accepts two parameters: a URL as a string, and a callback function
named trackTimingCallback that will be executed once
the script has loaded.
Inside loadJs, a beginning timestamp is stored in
startTime. Once the resource has been loaded,
the callback function is executed. In the callback function,
the end timestamp is retrieved and used to calculate the time
it took to load the JavaScript resource. Finally, the time spent
is sent to Google Analytics using the send command.
So by calling:
loadJs('//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js', trackTimingCallback);
You will asynchronously load the jQuery library from the Google Content Delivery network, and once complete, execute the callback function, that in turns sends the load time of the resource to Google Analytics.