ashea-code / trak.js

Universal analytics event tracking API

trak.js - Universal analytics event tracking API

trak.js is a API wrapper for your analytics APIs. By default it uses the Google Universal Analytics but you can override this witht the older ga.js or Google Tag Manager if you wish. You can even add custom event trackers as well as, or instead of GA.

Getting the Library

Direct downloads

• Minified (~481 B gzipped)
• Unminified (~1.7 KB gzipped)

Bower

bower install trak

Usage:

Include trak.js in your JavaScript bundle or add it to your HTML page like this:

<script type='application/javascript' src='/path/to/trak.js'></script>

then run trak(); when the DOM is ready:

// Native JS
document.addEventListener('DOMContentLoaded', function(e) {
	trak();
}

// jQuery
$(function(){
	trak();
});

API Reference

There are two main ways to use trak.js, in your js code or as data-* attributes in your markup.

JS implementation:

trak.event(category, action, label [, options])

Fires an analytics event

Arguments:

category: A string value of the category value to set
action: A string value of the action value to set
label: A string value of the label value to set
extendedOptions: An object containing additional parameters for more advanced analytics events.

The 'extendedOptions' Object:

value: An integer
nonInteraction: An integer
eventName: A string value used only with Google Tag Manager. Define your GTM event name here

If any property is left undefined, the browser's default value will be used instead.

trak.event('category', 'action');
trak.event('category', 'action', 'label');
trak.event('category', 'action', 'label', extendedOptions);

Example:

trak.event('engagement', 'signpost', 'page.href');
trak.event('engagement', 'signpost', 'page.href', {
  value: 10,
  nonInteraction: true,
  eventName: 'This is a Google Tag Manager event name'
});

Data-* attr implementation:

<a href="#" data-trak='{"category":"Rating","action":"Comparison notepad","label":"Up"}'>link</a>

<!-- With an extended option -->
<a href="#pagehref" title="1 title" data-trak='{"category":"Test category","action":"Test action","label":"Test label","options":{"eventName":"Event name test"}}'>Data attr test #1</a>

Extended options

These can be used

data-trak wildcards:

Wildcards can be used to specify certain options like the page title or url.

page.href: Uses window.location.href

<a href="#" data-trak='{"category":"Rating","action":"page.href","label":"Up"}'>link</a>

page.title: Uses document.title

<a href="#" data-trak='{"category":"Rating","action":"page.title","label":"Up"}'>link</a>

link.href: Uses this.href

<a href="#" data-trak='{"category":"Rating","action":"link.href","label":"Up"}'>link</a>

link.title: Uses this.title

<a href="#" data-trak='{"category":"Rating","action":"link.title","label":"Up"}'>link</a>

referrer: Uses document.referrer

<a href="#" data-trak='{"category":"Rating","action":"document.referrer","label":"Up"}'>link</a>

---

Options

Various default trak.js options can be overridden:

trak.options.clean

Type: boolean
Default: true

Choose whether you'd like to clean the provided category, action and labels

trak.options.delimeter

Type: string
Default: _

trak.js includes a cleaning method to normalise the arguments that are passed to it. Spaces are converted to an underscore by default but can be overridden by reassigning this value.

trak.options.trackType

Type: string
Default: ga Alternatives:

• ga : Google Analytics (Universal
• _gaq : Google Analytics (ga.js) Old version
• gtm : Google Tag Manager

Use this to change your default tracking provider.

trak.options.additionalTypes

Type: function
Default: undefined

Add any other event tracking providers. See below for example:

trak.options.additionalTypes = function() {
	UDM.evq.push(['trackEvent', trak.clean(category), trak.clean(action)]); // trak.clean(label)
	console.log('Fire additional event');
}

trak.options.debug

Type: boolean
Default: false

Show debug logs in the js console

---

Which tracking API's are used?

The default implementation uses latest version of Google Analytics (ga.js) but trak.js also supports the older _gaq type or Google Tag Manager.

---

Browser Compatibility

trak.js has been tested in the following browsers:

• Chrome
• Firefox 3+
• Opera 10+
• Internet Explorer 8+