Skip and go to main content

Design & Technology November 17, 2011

How to use Dept's jQuery Unobtrusive Google Analytics Event Tracking Plugin

Image

What Google Analytics Plugin? It’s a jQuery plugin I wrote to try to standardise and simplify the way event tracking is implemented on a website. It makes use of HTML5 data attributes and jQuery to try and minimise the effort and cross cutting concerns that tracking often puts into a project.

Note: A number of updates have been made to the plugin since this post, please see https://github.com/rsleggett/Quick-Event-Tracking for updated documentation.

A Google Analytics Event is, basically, a way to track a user interaction that is not a page view which you wish to report on. For example: logging in successfully; downloading a file; interacting with an accordion control or plays of a video. This allows you to not only better label reports. For example, instead of looking at how many people hit the “register-thanks” page and comparing that to how many people hit the “register” page to get the number of completed registration, you can create a “Registration” event category with a “New” action and a “Started” action, giving a much clearer report.

The plugin aims to simplify implementation cost required to track these events across any project, in a back-end agnostic manner.

We’ve released the plugin as open source on the MIT Licence. You can get the plugin from GitHub: https://github.com/rsleggett/Quick-Event-Tracking

Note that this post is written from an ASP.NET point of view but the plugin could be used on any web project.

What does it do?

It enables websites to travel in time. Seriously. Oh alright then, it makes tracking Google Analytics Events a bit easier so you don’t have to litter your server side code with JavaScript and makes tracking a bit easier from JavaScript too.

Basically using the Google Analytics Asynchronous event tracking code, tracking is a single line call to this function.

[code]
_gaq.push([‘_trackEvent’, category, action, label, value]);
[/code]

This may seem simple at first and you may be asking, “why am I wrapping it up in more code?” Well there’s lots of problems with getting this wired up in a nice way which doesn’t invade all of your code and you’ll often find that you have to do this a different way for every situation.

The first issue is how do you call this when an action happens that involves a post back. We would need to inject the JavaScript code into the page after the post back and so the tracking code starts to leak into our application code. My solution to this was to place a span with attributes describing the event into a user control and then make that control visible/invisible when you want to track it. This encapsulates how we are tracking away from the application code while giving us a level of control.

Another issue is how to track certain links that offer downloads of specific file types? I’ll show how to achieve this with the plugin in the next section.

The final issue is that we’d have to litter our JavaScript code with these calls. Which may not seem too bad now, but what if you wanted to change the name of a category? You’d have to go searching through all the JavaScript and server side code to find where you used it.

This plugin is an attempt to alleviate some of these issues and adds some extra functionality that (I think) makes it quite flexible.

Show me the code

There are 3 ways to use the plugin. Not all of these will fit every situation.

Method 1 – Simple Unobtrusive Tracking

Unobtrusive in combination with server side or just HTML. You output a span or any other element to the page and include a class of “track-me” for example:

[code]

[/code]

Then in your JavaScript initialisation code, you just call the plugin thusly:

[code]
$(‘.track-me’).gaTrackEventUnobtrusive();
[/code]

In one ASP.NET project, I have encapsulated the span inside a user control that can be hidden and shown at will and also has a setting to only track an event once for a user e.g. Registering. via the use of cookies (I may move this functionality into the plugin soon).

Method 2 – Unobtrusively Tracking An User Interaction

Many of the events that we would like to track are things which do not trigger a post to the server. In this case we need to call the event on a user interaction. For example if we want to track removing of bookmarks from a list and this is an ajax request.

Say we had a widget that stored bookmarks and this widget was AJAX enabled. An anchor tag might be used to trigger the removal of a bookmark in our page like so:

[code]
Remove
[/code]

Notice we’ve given it a class of “track-click”. We need to call the plugin in our JavaScript initialisation code like so:

[code]
$(‘.track-click’).gaTrackEventUnobtrusive({
useEvent:true,
useLabel:true,
event: click
});
[/code]

This will look for any element with the class of “track-click” and track clicks on it based on whatever data was attached via the data attributes. We can control the event here for example we could change “click” to hover or any other event.

Method 3 – Tracking An User Interaction Without The Data Attributes.

Sometimes for some reason you might not want to use data attributes directly on the element in your user controls or html, so the plugin provides a way to add the attributes from JavaScript . This is good for adding events to an existing code base, you could hook onto existing classes

[code]
//Set up for downloads
$(‘.track-download-pdf’).gaTrackEvent({
category: ‘Download’,
action: ‘PDF’,
labelAttribute: “href”,
useEvent: true,
event: ‘click’
});
[/code]

So what this will do is look for any element with the class “track-download-pdf” and add the data attributes for tracking. Notice it also uses the href of the element as the label attribute rather than the default “data-ga-category”.

Available options

There are many options to make the plugin a bit more flexible. Including callback hook functions to evaluate whether to perform tracking and what to do after tracking.

These are the default options, you can override any of these by passing them to the plugin.

[code]
var defaultOptions = {

//The category attribute
categoryAttribute: ‘data-ga-category’,

//The action attribute
actionAttribute: ‘data-ga-action’,

//The label attribute (could be changed to href when tracking file downloads)
labelAttribute: ‘data-ga-label’,

//The value attribute (value must be integer)
valueAttribute: ‘data-ga-value’,

//Whether to look for the label
useLabel: true,

//Whether to look for a value
useValue: false,

//false = track as soon as the plugin loads, true = bind to an event
useEvent: false,

//The event to bind to if useEvent is true
event: ‘click’,

//A method to call to check whether or not we should call the tracking when the event is clicked
valid: function (elem) { return true; },

//Tracking complete
complete: function (elem) { },

//Category should always be set if using gaTrackEvent
category: ‘Unspecified’,

//Action should always be set if using gaTrackEvent
action: ‘Unspecified’
});
[/code]

In summary…

This post should have demonstrated the use of the plugin and allowed you to form an opinion. Hope this can help people out with using Google Analytics on any project. If you’ve got any feedback post a comment or let me know directly. The plugin is hosted on GitHub.

Questions? We are here to help!