Improve website event tracking with trak.js
Whether you use Google Analytics or another provider, adding tracking events to a site is often a painful experience. Events usually have to be defined in javascript which can make it tricky to dynamically change parameters based on certain criteria. Wouldn’t it be nice to define events within the markup so that hundreds of click events can be left free from your javascript code? Trak.js does just that.
Put simply, trak.js is a wrapper for any analytics API. By default it uses Google Universal Analytics but you can override this with the older ga.js or Google Tag Manager if you wish, or you can even add custom event trackers as well, instead of Google Analytics.
Using trak.js
There are two main ways to use trak.js, as data-trak attributes in your markup or in your javascript code.
data-trak attr implementation:
<a href="#pagehref" data-trak='{"category":"Test category","action":"Test action","label":"Test label"}' title="1 title">link</a>
Custom trigger type (new as of v0.4.0)
data-trak attrs can also define a custom trigger type instead of click. Now mouseover, touchstart, focus, blur or any other valid event can be used to trigger a trak event. Just add “trigger”: “eventName”to the options object. See below for an example of this using the focusevent:
<!-- Triggered on focus -->
<a data-trak='{"trigger":"focus","category":"Test category","action":"Test action","label":"Test label"}' href="#pagehref">Custom trigger type</a>
Javascript implementation
trak.event({
category: 'engagement',
action: 'signpost',
label: 'page.href'
});trak.event({
category: 'engagement',
action: 'signpost',
label: 'page.href',
value: 10,
nonInteraction: true,
eventName: 'This is a Google Tag Manager event name'
});
API Reference
Arguments object: (these are all optional)
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
value: An integer
trigger: A string value of a valid event name: click, focus, mouseover etc
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.
Wildcards
trak.js introduces the concept of wildcards when working with your events, this makes it extremely easy to use more complex values in your events. There are a number of wildcards available for both the data-trakattr and js implentation. These can be used to specify certain options like the page title, the url, the current anchor’s href value and a few others.
- page.href wildcard uses window.location.href as the value.
- page.title wildcard uses document.title as the value.
- link.href wildcard uses this.href as the value.
- link.title wildcard uses this.title as the value.
- referrer uses document.referrer as the value
<!-- page.href wildcard -->
<a href="#" data-trak='{"category":"Rating","action":"page.href","label":"Up"}'>link</a><!-- page.title wildcard -->
<a href="#" data-trak='{"category":"Rating","action":"page.title","label":"Up"}'>link</a><!-- link.href wildcard -->
<a href="#" data-trak='{"category":"Rating","action":"link.href","label":"Up"}'>link</a><!-- link.title wildcard -->
<a href="#" data-trak='{"category":"Rating","action":"link.title","label":"Up"}'>link</a><!-- referrer wildcard -->
<a href="#" data-trak='{"category":"Rating","action":"document.referrer","label":"Up"}'>link</a>
Getting the Library
Direct downloads
- Minified (~481 B gzipped)
- Unminified (~1.7 KB gzipped)
Bower
bower install trak
NPM
npm install trak.js -S
More information
More information and the full documentation can be found at our repository on Github. Also, options can be overridden; there’s a debug mode; and most importantly, almost any other analytics APIs can be used.