Trackiffer 0.4.2

Trackiffer is a dead-simple, yet suprisingly powerful, drop-in script for tracking GA events, social actions, and setting custom vars.

It takes a simple set of CSS selectors and tracking rules, and tracks a wide variety of elements in a number of really cool ways.

So what does it handle for you?

• Tracking events on forms (submit), select elements (change), text inputs (blur), and anything else (click).
• Provides a super-helpful debug mode you can use for setting up your events.
• Loads from a bookmarklet, so you can even test your rules out on sites you don't have access to yet.
• Loading jQuery. Trackiffer depends on jQuery, but if you must deploy it on a site without jQuery, Trackiffer will load it for you.
• Delay outbound links AND form submissions by 100ms to maximize your chances of tracking the event.

Adding to your site

Add the trackiffer script to the end of your page's body tag, and call trackiffer like so:

<script type="text/javascript" src="/js/trackiffer.min.js"></script>
<script type="text/javascript">
	trackiffer({
		'a.blog' : ['event', 'Link', 'Social', 'Twitter']
	});
</script>

Alternately, you can add your tracking code to the bottom of trackiffer.min.js and deploy that file on its own. I recommend renaming it to trackiffer-[sitename].min.js when using this method.

Use

trackiffer({
	// virtual pageview
	'a.virtual' : ['pageview', '/path/for/virtual/pageview'],

	// event tracking
	'a' : ['event', 'Link', 'Social', '{{text}}', 1],
	'select' : ['event', 'Outbound', 'Social', '{{value}}'],
	'.comment_form' : ['event', 'Outbound', 'Social', 'Left Sidebar - Twitter - {{action}}'],
	'.outbound_form' : ['event', '{{class}} Form', '{{method}}', function(N){return N.find("input#agree").val()}]

	// social tracking
	'.retweet' : ['social', 'Twitter', 'Retweet', '{{href}}', window.location.href],

	// custom variables - remember to track something (event/pageview/etc) after this, or the value won't be visible to analytics!
	'select.gender' : ['dimension1', '{{value}}']
});

The left side is the jQuery selector you'd like to use, and the right side is the event data you want to track.

Any {{token}} will be replaced at the time of event:

• {{text}} by the result of $element.text();
• {{value}} by the result of $element.val();
• {{anything_else}} is replaced by the result of $element.attr('anything_else');

In extreme cases, you can just pass callbacks instead of strings. This lets you do all kinds of fancy stuff - in the example, we're recording the value of a particular input at the moment the form submits.

Extra Configuration

trackiffer({
	'body' : {
		delay : false,
		delegate : 'form',
		type : 'submit'
		rule : ['event', 'Link', 'Social', '{{text}}', 1]
	}
});

By assigning an object literal to your selector, you get two new options ('rule' is your event data, and it's required):

• delay - by setting delay to false, you override trackiffer's default outbound behavior. The event will no longer cancel, and the user will no longer be forwarded to a new URL after 100ms.
• delegate - setting a delegate option allows you to bind events to DOM elements that might not exist yet on the page. Read more about delegate here. At the moment, these links WILL NOT be highlighted, but their element you delegate from will have a faint highlight. You can still test these elements by interacting with them and reading the console.
• type - only set this if you're delegating and want to track a non-click event. Examples might be submit, update.

Debug mode

You definitely want to run Trackiffer in debug mode to test this all out. It's simple:

trackiffer('debug');

Debug mode will cancel all tracked clicks (so you stay on the current page) and log tons of cool info in the console. You can also do a quick debug by visiting the url in question with a #trackiffer_debug hash:

http://example.com/#trackiffer_debug

Is Trackiffer broken?

MAYBE! Trackiffer is very new and relatively untested in the wild. If you experience issues, please report them on the issues page.

Bookmarklet

Once you download Trackiffer, you can install the bookmarklet from the index.html page. This will drop trackiffer onto any page you view and set debug mode - you can then execute and test trackiffer({rules}) from your browser's console.

Running the Tests

Simply open test/index.html in your browser. Please verify that all tests pass before submitting PRs.

Why does this exist?

The Viget marketing people are awesome - when we remake a site, they put event tracking on the OLD site, then track the same actions on the new one when it launches.

The problem? This means we set up event tracking twice per site, and it's not a very repeatable or simple process....at least, until now.

I wanted to make a script that handled all the messy aspects of tracking, and enabled our GA wizards simply put together a ruleset and deploy, maybe even without developer help.

Thanks To

Paul Koch and the rest of the Viget marketers for being GA badasses and always asking us to do cool stuff with analytics.