Skip to content

Latest commit

 

History

History
128 lines (85 loc) · 5.7 KB

readme.md

File metadata and controls

128 lines (85 loc) · 5.7 KB
Raw

gatrack.js

gatrack.js

Easily track user events with Google Analytics. Test UI/UX theories, compare client performance/speed, even track client-side errors. All user events are tied to all other session data in Google Analytics.

Is it any good?

You betcha. Check out the provided index.html demo for working examples.

Installation

You can install gatrack.js via Bower or NPM:

bower install gatrack
npm install gatrack

Or, you can just include the dist/gatrack.min.js file anywhere on your page.

Way-cool:

  • Auto-track events on elements with a class-based API
  • Explicit action hook, works with any registerable browser event
  • Support for multiple versions of Google's analytics tracking scripts (ga and _gaq)
  • Supports multiple loading multiple profiles at once
  • Track client errors as separate events, attached to all prior & subsequent interaction data
  • All user events are tied to all other session data in Google Analytics
  • Weighs under 3kb (even smaller if you're smart enough to gzip)
  • Provides tracking support for common events
    • Scrolling
    • Touches
    • Links
    • Clicks
    • Hovering
    • Errors

Things you'll need

  • A Google Analytics profile
  • A version of the Google Analytics tracking script released within the last couple years, installed in your page source

API usage

The API, on load, detects and tracks events for touch, hover, scroll, click, link and load. To specify category or the action being taken (both optional), simply add data-attributes of gatrack-category and/or gatrack-action and/or gatrack-label and/or gatrack-value.

Click events

For an element on which you wish to track click events, add a class of ga-click-trackable.

Link visits

For links (internal or outbound) for which you want to track user interaction, add a class of ga-link-trackable.

Hover events

For an element on which you wish to track hover events, add a class of ga-hover-trackable.

Load events

For an element on which you wish to track load events, add a class of ga-load-trackable.

Touch events

For an element on which you wish to track touch events, add a class of ga-touch-trackable.

Scroll events

For an element on which you wish to track scroll events, add a class of ga-scroll-trackable. You need to specfiy the position at which to trigger the event (either percentage amount or pixel distance, '30%' or '300px', by setting data-gatrack-scroll-point). For this type of event, you can also specify scrolling direction ('x' or 'y', by setting data-gatrack-scroll-direction) to track , which defaults to 'y', or vertical.

Registering custom events

gatrack.action(element, category, action [, label, value, callback(result)])

gatrack.link(element [, category, action, label, value])

gatrack.click(element [, category, action, label, value])

gatrack.load(element [, category, action, label, value])

gatrack.touch(element [, category, action, label, value])

gatrack.hover(element [, category, action, label, value])

gatrack.scrollAt(element, scrollPoint [, scrollDirection, category, action, label, value])

Google Analytics events accept four parameters:

  • category: string
  • action: string
  • label: string
  • value: integer

In general, the event hooks look for things like an element id or title attribute to assign to the action parameter when one is not specified either explicitly or in the data-attribute of the element.

In the case of the link event, it looks for the href value in absence of an explicity declaration or data-attribute, and the scrollAt event looks for the page title content.

gatrack.init() is available and can be used to initialize the event listeners on specified elements whenever you like.

The action hook, when given an optional callback function, returns a 'success' string on success and a traditional error object otherwise.

You can read more specifics about the event object in Google Analytics.

Tracking Errors

You can also track errors on your page through gatrack. All you'll need to do is override the native onerror function with one for gatrack.

To start recording errors, you simply need to place the following snippet in a script tag so that it will be the first code executed on your page, preferrably in the head of your document.

// One-liner, minified (use this one!)
(function(g,a,t,r,a,c,k){g[r]=g[r]||{};g[r][a]=t.getTime();g[r][c]=[];g[c]=function(m,u,l,c,e){this.gatrack.onerror.push([m,u,l,c,e])}})(window,document,(new Date()),'gatrack','timer','onerror');
// Expanded, so you can see
(function(g,a,t,r,a,c,k){
  g[r] = g[r] || {};
  g[r][a] = t.getTime();
  g[r][c] = [];
  g[c] = function( m, u, l, c, e ) {
    this.gatrack.onerror.push([m, u, l, c, e]);
  };
})(window,document,(new Date()),'gatrack','timer','onerror');

This snippet will allow you to record errors that are raised even before any other JavaScript code is executed. The gatrack library records errors in the following format:

  • category: 'Recorded Error'
  • label: The error's message string
  • action: 'Error line:column(url)'
  • value: Time of occurence after HTML load (in seconds, rounded to nearest hundreth)