Tracking downloads using URI redirects [tutorial]


#1

A common requirement on the web is to track downloads. In this guide, we’ll cover two approaches to tracking downloads:

  1. Tracking downloads using Javascript event listeners on the link click (common approach)
  2. Tracking downloads using the collector URI redirect (more robust / reliable approach)

1. Tracking downloads using Javascript event listeners (common approach)

Downloads are generally triggered when a user clicks a particular link.

A common approach, then, to tracking downloads, is simply to use Javascript and add an event listener on the link / button that needs to be clicked to trigger a download, such that when that link or button is clicked, a Snowplow event is fired. Assuming it is a standard link click that triggers the download, you can for example simply enableLinkClickTracking on initializing your Snowplow JS tracker and make sure the href has an unambiguous id so that you can easily spot the link clicks that trigger downloads. These will then be tracked in Snowplow automatically.

The problem with this approach is that if the download causes the user to leave the website (e.g. in order to load a PDF in the browser) there’s no guarentee that the link click event will fire before the user leaves the website.

A more robust approach, using the collector URI redirect, is detailed below.

2. Tracking downloads using the collector URI redirect (more robust / reliable approach)

Both the Snowplow Clojure and Scala RT collectors support URI redirects. This means they can be used for any type of click tracking. This works as follows:

First, you take the link to the asset that will be downloaded e.g.

<a href="http://mydomain.com/assets/my-excellent-guide.pdf">Download here</a>

You replace the URI in the link link with a Snowplow collector URI, but add /r/tp2 to the URI. This will forward anyone who clicks the link to the Snowplow collector itself. The /r/tp2 tells the Snowplow collector to redirect the user to another URI:

<a href="http://my-snowplow-collector/mydomain.com/r/tp2">Download here</a>

Now add the URI that you want the user redirected to (i.e. URI that the asset to be downloaded is located on) to the querystring as the value for the u parameter. As this is a querystring parameter, we’ll need to URL-encode the URI. So in this, we want to direct the user to:

http://mydomain.com/assets/my-excellent-guide.pdf

Let’s URL encode it e.g. using this URL encoder:

http%3A%2F%2Fmydomain.com%2Fassets%2Fmy-excellent-guide.pdf

Then add it to as the u parameter:

<a href="http://my-snowplow-collector/mydomain.com/r/tp2?u=http%3A%2F%2Fmydomain.com%2Fassets%2Fmy-excellent-guide.pdf">Download here</a>

This will successfully redirect, and record the event as a uri_redirect event. If we’d prefer to record it as a different event (e.g. a custom structured event) we can simply add the e parameter to the querystring and set it’s value to any of the values allowed in the Snowplow Tracker Protocol. So if, for example, we want to record this as a custom structured event with category = download and action = downloaded-my-excellend-pdf, we’d add the following name value pairs to the querystring, based on the Tracker Protocol:

  • e=se (event = structured event)
  • se_ca=download (category = download)
  • se_ac=downloaded-my-excellend-pdf (action = downloaded my excellent PDF)

Putting this all together our link becomes:

<a href="http://my-snowplow-collector/mydomain.com/r/tp2?u=http%3A%2F%2Fmydomain.com%2Fassets%2Fmy-excellent-guide.pdf&e=se&se_ca=download&se_ac=downloaded-my-excellend-pdf`">Download here</a>

Tracking clicks on email clicks - using unstructured event
Configuring link click tracking for the first time