Track file downloads with Google's Universal Analytics

Introduction

I wanted to track which version of the Radial Menu mixin was more popular. Since I already use Google Analytics for the page views it was logical to use it to track the file downloads. It took a couple of tries and wading through some poor examples on various websites before I had something that worked for me. In this article I will explain how I am counting file downloads using Google Analytics events.

The basics

In theory it is a simple exercise, especially if you already have Google Analytics setup for your website. It should be as easy as adding some code in de the onclick handler of your anchor element and calling the ga method.

<a onclick="ga('send', 'event', 'category', 'download', 'label', 'value');" href="/static/articles/radial-menu/radial-menu-less.zip">LESS version of the mixin</a>
        

That was my first attempt, it failed miserably. Part of it was my fault for not reading Google's track event documentation properly. The value of the last parameter has to be a number and I was passing a string.

The other problem was obvious once I opened the network tab of the Google Chrome debugger. My track event was canceled, according to the debugger so was the request for the zip file. But unlike the zip file which was waiting for me in the download folder, Google Analytics never received the event.

The onclick handler would have worked if the anchor had had the attribute target="_blank". The file download would have taken place in the new tab or window and the Google Analytics event would've been sent from the existing tab. I think this is not a very nice solution, I don't want to burden my visitors with an empty tab they didn't ask for. Time to try something else.

The backwards solution

I started looking around what other people did to track file downloads on anchor elements that don't open a new tab or window. If you search on Google for "track file downloads", one of the first results is How To Track File Downloads & Outbound Links in Google Analytics by Ryan Chase. It has a pretty solid solution for a lot of different situations, I figured this would be a good place to get started.

One of the things I didn't like about it was the usage of jQuery. I don't use jQuery on my site and I wasn't about to use it just so I could track an event in Google Analytics. The other problem was I couldn't get it to work properly. I boiled Ryan's solution down to the following:

(function() {
    'use strict';

    // Get all anchor elements that link to a zip file, these are the links I want to track
    var links = document.querySelectorAll('[href$=".zip"]');
    // Loop over all the elements we've found
    for (var index=0,ubound=links.length; index<ubound; index++) {
        // Attach an event handler on the click event
        links[index].addEventListener('click', handleClickEvent.bind(this));
    }

    function handleClickEvent(event) {
        // Send the event to Google Analytics
        ga.send('send', 'event', 'link', 'download', 'label', 0);
        // Set a timeout of 400ms, after the time out has lapsed we will start the download of
        // the file
        setTimeout(function() {
            location.href = event.target.href;
        }, 400);
        // Prevent the default behaviour of the link, we prioritize sending the event to
        // Google.
        event.preventDefault();
    }
})();
            

The magic happens in the setTimout part of the code. By waiting 400ms before sending the event we give the system enough time to send out the Google Analytics event before we make the request to download the zip file. I am not really sure where the 400ms comes from, I haven't been able to find any articles that explain why this value should be used. Perhaps a short time out will work just as well.

Because I only want to track an event for my download links I could get away by just attaching click handlers to the links whose href ends on ".zip". The other big change I had to make was to replace the return false at the end of the event handler with event.preventDefault(). When returning the value false the zip file downloaded twice, it didn't cancel out the default behavior of the anchor element.

There are plenty more examples you can find on-line. All the articles I came across pretty much did the same thing. Attach an event handler to the link, send out the event, set a time out to download the file and cancel the default behavior of the anchor element. When you think about it for a while it is kind of crazy, you're preventing the default behavior of the anchor only to recreate it a little later.

Fixing it the right way round

I think downloading the file should be the default action of the anchor element, sending out the event is of secondary concern. By prioritizing the file download the code for sending out the event became a little simpler.

(function() {
    'use strict';

    // Get all anchor elements that link to a zip file, these are the links I want to track
    var links = document.querySelectorAll('[href$=".zip"]');
    // Loop over all the elements we've found
    for (var index=0,ubound=links.length; index<ubound; index++) {
        // Attach an event handler on the click event
        links[index].addEventListener('click', handleClickEvent.bind(this));
    }

    function handleClickEvent(event) {
        // Set a timeout of 400ms, after the time out has lapsed we will send the event
        // to Google
        setTimeout(function() {
            // Send the event to Google Analytics
            ga.send('send', 'event', 'link', 'download', 'label', 0);
        }, 400);
    }
})();
            

This way we don't have to prevent the default behavior of the anchor element and just wait 400ms before sending out the event to Google.

<a data-ga="{'action':'download','category':'radial-menu','label':'LESS version','value':'1'}" href="/static/articles/radial-menu/radial-menu-less.zip">LESS version of the mixin</a>
                

(function() {
    'use strict';

    // Get all anchor elements that have information for a Google Analytics event in the data-ga atttibute
    var links = document.querySelectorAll('[data-ga]');
    // Loop over all the elements we've found
    for (var index=0,ubound=links.length; index<ubound; index++) {
        // Attach an event handler on the click event
        links[index].addEventListener('click', handleClickEvent.bind(this));
    }

    function handleClickEvent(event) {
        // Get the content from the data-ga attribute from the element that send the click event
        var data = event.currentTarget.getAttribute('data-ga');
        // We'll be parsing the content of the attribute as JSON, in order to be able
        // to do this we need to make sure all single quotes in the string are double quotes.
        // This regular expression replaces all instances of a single quote
        data = data.replace(/\'/g, '"');
        // Now we can parse the string to an object. If you're not sure this attribute will
        // always contain a string which can be parsed as JSON you should add a try...catch
        // around this so your code won't crash
        try {
            data = JSON.parse(data);
            // Set a timeout of 400ms, after the time out has lapsed we will send the event
            // to Google
            setTimeout(function() {
                // Send the event to Google Analytics. We use the properties from the object we've parsed
                // from the attribute. Be sure to pass the value parameter as a number
                ga.send('send', 'event', data.category, data.action, data.label, parseInt(data.value, 10));
            }, 400);
        } catch (exception) {
            console.log('Unable to parse the string <' + data + '> as JSON');
        }
    }
})();
                

The result

We now have a small, light weight, piece of JavaScript which we can use to send events to Google Analytics. It can be configured per anchor element and it prioritizes the file download over sending the event to Google.

The JavaScript code is compatible with Internet Explorer 9 and up due to the usage of addEventListener. The code could easily be made compatible with Internet Explorer 8 by loading something like the addEventListener polyfill on the Mozilla Developer Network.

• Track download script