Purpose
To help web publishers easily track link clicks the correct way, across browser platforms, with tools like Google Analytics (GA) and Google Website Optimizer (GWO).
Typically a web publisher will want to do something like track all external links on a website with GA, setup a
GWO test where the conversion is a click through, or do both on the same page for a few pages of their site. This javascript library was designed to make tasks such as these
simple.
About
clickTrackingLib
Adding the click-tracking-lib.js or the click-tracking-lib-with-presets.js to a web page provides you with a
clickTrackingLib javascript object. Once you provide clickTrackingLib with some match objects, you can then
have clickTrackingLib scan a single, set, or all document links to determine if the link(s) should have
tracking functions applied to it or not, and do so if needed. If one or more tracking functions are applied to
a link, then a delay function will be applied to the link (this can be disabled too of course, and the delay can
user defined but the default is 99 ms).
The Delay Function
The delay function is meant to delay the user from being redirected to a new page for just a bit to allow time for say a
Google Analytics image request to complete, and avoid being canceled by the user's browser. It can be disabled, but it is
added by with a 99 sec delay by default, which can be customized, as the very last onClick event listener, after all of
the desired provided Match object trackingFunc's are applied.
The delay function technically only sets a timeout to redirect the user after x ms, but in order for the delay to work the
link's default functionality, namely redirecting the user, needs to be disabled, if the link doesn't just open in a new tab
(target="_blank" and target="_new" are checked for). To disable the default functionality the link's onclick attribute must
be set to onclick="return false;" which I figured should be fine because all well made websites won't use that attribute except to make
it equal to "return false;" anyhow. If your site is not well made, then you should think about fixing it or having it fixed for you, but
you can still use this library by simply not using the delay function and implementing it by some other means.
Presets
There are a number of presets available if you use click-tracking-lib-with-presets.js or click-tracking-presets.js;
presets are predefined match functions for common use cases, such as matching all internal links, or external links,
or download links. They can be used as they written, you could cut out the ones you won't use, or simply use them as
examples when you define your own custom match objects.
The can be accessed from the clickTrackingLib.getMatchPreset( name ) method. The possible name values and the meanings
behind them are as follows:
- 'rel-external': matches rel-external links
- 'external-hostname': matches external hostname links
- 'all-external': matches all rel-external and external hostname links
- 'filetypes': matches file names: (docx*|xlsx*|pptx*|exe|zip|pdf|xpi|rar|xls)
- 'non-rel-external': matches non-rel-external links
- 'internal-hostname': matches internal hostname links
- 'all-internal': matches non-rel-external links or internal hostname links
Match Objects
Any object that has a 'match(link):boolean' method and 'trackingFunc(event,link):void' method defined.
match(link):boolean
This method will take a link element as input, run some test on it and return true or false, if true is returned then the Match object's trackingFunc will be added to the link.
trackingFunc(event,link):void
This method will be provided with two input values; event is the click event object, and link is a reference to the link element. You can obtain a reference to this from the event object, but there is some cross browser logic you would need to implement, so I thought a direct reference to the link would be handy. The function should not return anything.
new clickTrackingLib._clickTrackingLib();
If you want to create multiple clickTrackingLib objects, that contain different sets of match object arrays, then
you need to create a new one, like so:
var myNewClickTrackingObj = new clickTrackingLib._clickTrackingLib();
This will give you a new object, myNewClickTrackingObj, which is like clickTrackingLib in all but two ways. First
myNewClickTrackingObj will not have a _clickTrackingLib() method, and second it will not have a getMatchPreset()
method, even if clickTrackingLib.getMatchPreset() was defined. This is because you don't need a bunch of objects
in memory with those two methods, only one, which is the singleton clickTrackingLib object.
How To Use
- Download either click-tracking-lib-with-presets.js or click-tracking-lib.js (see ABOUT fore more information) from the project repository at GitHub.
- Minify it with one of the following options:
- Upload the minified script to your site.
- Add <script src=".." type="text/javascript"></script> for the script to the desired pages.
- Write some code:
- define some match objects (just an object with a match method and trackingFunc method)
- Add match objects to your clickTrackingLib object
- Call the clickTrackingLib.attachTrackingFunctions( links, delay ) when desired.
- links: can be a single anchor element, an array of anchor elements, or falsely so that
the default is used, which is document.links.
- delay: should be a positive integer or falsey, in the latter case no delay function will be added to the
links scanned, in the former case a delay function will be applied with the specified delay value.
[More]
@erikvold