immeria

gaAddons gaAddons v2.0® - Google Analytics addons

 

You like gaAddons®?
Donate to help out!


Consultants & Agencies: read important rights of use info.
gaAddons mailing list

gaAddons® is a collection of useful enhancements to extend and improve upon the default Google Analytics implementation. It actually leverage the popular jQuery lightweight JavaScript library.

Bookmark and Share

Current stable version: 2.0.7
Current beta version: 2.0.8
Last updated: 2010-09-03 10:29


News

What's new in v2.0.7?

  • New: use the _Options call to overwrite global gaAddons defaults
  • Enhanced: use "action: 'mouseup'" to track right clicks with _trackDownloads, _trackOuntbounds and _trackMailTo
  • Updated: _trackDownloads now use page views by default.
  • Bug fix: _trackDownloads optimization and bug fix (wasn't working)
  • Beta: _setHourOfDay and _setDayOfWeek

Upcoming

  • Form Analysis
  • Distinct site for gaAddons®
  • Enhanced documentation

Send in your ideas!
 

Features

gaAddons events
  • Use the new async calls syntax
  • Track outbound, downloads and email links using events
    ("fake" pageview mode also supported)
  • Track real bounce rate by triggering an event after 30 seconds on a page (default)
  • Track page loading time
  • Optionally avoid affecting bounce rate when above events are on 1st page view of a visit
  • Easily customize the default options
  • Use a tagging syntax identical to Google Analytics style

There are a number of ideas and upcoming features - use the Feedback tab on the right to share your ideas!

 

Integrating gaAddons® to your site

Integration gaAddons® to your site should be a snap!

1. Google Analytics tags
Refer to the GA async for your regular implementation guidelines.
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(
      ['_setAccount', 'UA-XXXXX-X'],
	  ['_trackPageview']
	  );
(function() {
   var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
   })();
</script>
2. Save a copy of gaAddons-2.0.min.js to your own website
Note: in theory you could link directly to the file on this site but this would create an unnecessary cross-site dependency and potential vulnerability.

3a. Optional: Add a link to jQuery
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"> </script>
gaAddons® is dependent on the jQuery library but maybe your site already use it. In any case, if jQuery isn't already loaded, gaAddons will automatically add it for you.

3. Add the gaAddons code snipet
The resuting JavaScript should look like this:
<script type="text/javascript">
   var _gaq = _gaq || [];
   _gaq.push(
      ['_setAccount', 'UA-XXXXX-X'],
      ['_trackPageview']
      );
   var gaAddons = gaAddons || [];
   gaAddons.push(
      // put gaAddons calls here
      );
(function() {
      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      var gaAddons = document.createElement('script'); gaAddons.type = 'text/javascript'; gaAddons.async = true;
      gaAddons.src = 'gaAddons-2.0.min.js';
      s.parentNode.insertBefore(gaAddons, s);
   })();
</script>

gaAddons calls

_options
Overwrite global defaults for gaAddons®
gaAddons.push(['_options', {
	debug: true, // show console information as gaAddons is working
	autoload: true, // automatically load jQuery if it's not there
	timeout: 100, // delay between retries to check if all depencencies are loaded
	jQuerySrc: 'http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js' // URL of jQuery library
	}]);
_trackOutbound
Track outbound links as "outbount" click events. Once this call is included you do not have to modify the individual links.
gaAddons.push(['_trackOutbound', {
	onBounce: false,
	method: 'event',
	category: 'outbound',
	action: 'click',
	value: 0,
	include: /./,
   exclude: /^$/,
	tracker: _gaq
	}]);
_trackDownloads
Track download links as page views under the /download/ path. Once this call is included you do not have to modify the individual links.

Page views or events? Downloads are tracked as page views by default (if you prefer events, simply set 'method' to 'event'). The Web Analytics Association defines a page as being "an analyst definable unit of content", which a downloabable document is in most cases.

Note:
if both _trackOutbound and _trackDownloads are present and the link leads to an externally downloadable document, the same click will be tracked under two distinct metrics.
gaAddons.push(['_trackDownloads', {
	onBounce: false,
	method: 'page',
	category: 'download',
	action: 'click',
	value: 0,
	include: /\.(docx*|xlsx*|pptx*|exe|rar|zip|pdf|xpi|mp3)$/i,
   exclude: /^$/,
	tracker: _gaq
	}]);
_trackMailto
Track email links as "mailto" click events. Once this call is included you do not have to modify the individual links.
gaAddons.push(['_trackMailto', {
	onBounce: false,
	method: 'event',
	category: 'mailto',
	value: 0,
	include: /./,
   exclude: /^$/,
	tracker: _gaq
	}]);
_trackRealBounce
If staying more than "delay" seconds on the 1st page of a visit, an event is fired to force a NoBounce, resulting in more accurate bounce rate information.
gaAddons.push(['_trackRealBounce', {
	onBounce: false,
	method: 'event',
	category: 'NoBounce',
	value: 0,
	delay: 30,
   include: /./,
   exclude: /^$/,
	tracker: _gaq
	}]);
_trackLoadTime
Track the loading time of the page. An event will be triggered with the corresponding 'bucket' of time. The accuracy of this method is to be taken with a grain of salt, however, since the methodology is consistent the results provide some insight on your fast vs slow loading pages. Bucket can be an array of time slots (in milliseconds) or an integer representing the number of seconds in each bucket (i.e. 10 for buckets 10 seconds apart).

Caveat: It is recommended to use this feature sparsely, if you use it on every page, the number of Google Analytics calls will be doubled.
gaAddons.push(['_trackLoadTime', {
    onBounce: false,
    category: 'loadTime',
    bucket: [100, 500, 1500, 2500, 5000],
	time: (new Date()).getTime(),
    value: 0,
   include: /./,
   exclude: /^$/,
    tracker: _gaq
	}]);
_trackError
Easily track errors such as broken links (HTTP 404) or server errors (HTTP 500).
 
Mandatory: Make sure you set the "include" option to your custom error page handler URL (or page name).
gaAddons.push(['_trackError', {
    method: 'event',
   category: 'error',
   action: '404',
    value: 0,
   include: /404.htm/, // mandatory
   exclude: /^$/,
    tracker: _gaq
	}]);
_4Q
Easily integrates 4Q by iPerceptions with Google Analytics. This replaces the default 4Q integration script and automatically add the advanced 4Q + GA integration. By default, this feature will overwrite the _setAllowLinker and _setDomainName values to allow tracking across multiple domains (your domain and 4q.iperceptions.com).
 
Mandatory: "account" is the sdfc code provided by 4Q.

Note about using multiple custom variables:
4Q integration uses several custom variables slots, be careful if you use this feature alongside other gaAddons features also making use of custom variables (namely, _setDayOfWeek and _setHourOfDay). In this case, only the last value being set during the session will be recorded. The 4Q custom variables being used are:
  1. Survey ID (4QSurveyID) - mandatory
  2. Unique ID (4QUID) - mandatory
  3. Overall satisfaction (4QSAT) - optional
  4. Purpose of visit (4QPoV) - optional
  5. Task completion (4QTask) - optional
gaAddons.push(['_4Q', {
    account: 'sdfc account ID provided by 4Q', // mandatory
    tracker: _gaq,
    allowLinker: true,
    domainName: 'none',
    ...
	}]);
_setDayOfWeek beta
Create a new session custom variable with the current weekday. This is particularly useful for segmentation.
Note: See _4Q note about using mutliple custom variables.
Caveat: Won't be recorded if no other calls are made. Will be fixed in next release.
gaAddons.push(['_setDayOfWeek', {
	onBounce: false,
	index: 1,
	name: 'DayOfWeek',
	value: null,
	scope: 2,
	days: ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday'],
	include: /./,
	exclude: /^$/,
	tracker: _gaq
	}]);
_setHourOfDay beta
Create a new session-level custom variable with the current hour of the day (24 hours basis, based on client local time). This is particularly useful for segmentation.
Note: See _4Q note about using mutliple custom variables.
Caveat: Won't be recorded if no other calls are made. Will be fixed in next release.
gaAddons.push(['_setHourOfDay', {
	onBounce: false,
	index: 2,
	name: 'HourOfDay',
	value: (new Date()).getHours(),
	scope: 2,
	include: /./,
	exclude: /^$/,
	tracker: _gaq
	}]);

Options

Unless mentionned as MANDATORY, you don't have to specify any option if you want to use the default values.

acccount: string
The account identifier as provided by one of gaAddons integrated partner.
action: 'click|string'
The event label showing up under GA report /Content/Event Tracking/Actions.
For _trackOutbound, _trackDownloads, _trackMailto, if action is set to 'mouseup' then the left, middle and right mouse buttons will be tracked (as well as the regular 'click' event). Be forewarned this technique simply means the buttons were pressed, not the link was actually followed (i.e. someone can press the right-button to a "open in new window", "save as..." or nothing at all).
bucket: [100, 500, 1500, 2500, 5000]|integer
Time slices used with _trackLoadTime. If using the default array, a page loading in 344 milliseconds will be classified as 100-499. If passed as a number of seconds (integer), for example, 10 seconds, that same page would be classified as 0-9.
category: 'outbound|download|mailto|NoBounce'
Events are tracked with a Category, Action, optional Label and optional Value. This is the label that will show under the Content/Event Tracking/Categories report. If not using events, Category, Action and Label will be the faked page hierarchy represented as /Category/Action/Label. Label is the URL of the outbound, download or email link.
delay: 30|seconds
For the _trackRealBounce call, specify the number of seconds to wait before triggering the NoBounce event.
exclude: /^$/|regex
The exclude filter can be used to exclude gaAddons functionality under specific conditions. By default, nothing is excluded (/^$/ will always be false). For example, if you set this option to /myfile.pdf/ with the _trackDownloads call, every PDF download will be tracked (because of the include rule) except myfile.pdf.
include: /\.(docx*|xlsx*|pptx*|exe|rar|zip|pdf|xpi|mp3)$/i|regex
The include filter is mainly used with _trackDownloads to qualify which links should be tracked. If you set a filter value for other calls, it will be used to narrow down which links are tracked.
method: 'event|page'
By default, the tracking use events. If any other value, a fake page view will be generated (this was how things were done before GA introduced events)
onBounce: false|true
By default, if the tracking would affect the way GA track bounces, the call won't be made - and therefore this outbound link won't be tracked. If this option is true, the outbound link will be tracked - resulting in a non-bounce visit. This is is particularly useful when outbound links are to be considered desired behavior/business outcome you want to track.
time: datetime
Use with _trackLoadTime to specify the starting timestamp.
tracker: _gaq|object
By default, all calls will use the _gaq tracker. You can use a different tracker by overwriting the value of this parameter.
value: 0|real
If using events, you can assign a default value. This is not used with the "fake page view" method.

 

Support

Share ideas, ask questions or report problems.

Badge_get_help

Please note any support request where gaAddons® is not at fault will be billable.

Only authorized consultants and agencies will receive email support, all other requests should be done through GetSatisfaction.

 

Test cases

Get WASPHint: Use the Web Analytics Solution Profiler (WASP), to see gaAddons® calls firing and the data being sent to Google Analytics.

Track outbound links
Track downloads
Track mailto
Track real bounce rate
Make sure your GA __utmb cookie for this site is cleared (force it to be refreshed as a 1st page visit). Refresh the page and the NoBounce event should be triggered after staying for 30 seconds on the page.
Track error
Follow this broken link.

 

License and Rights of use: a fair use model

Personal use
Creative Commons LicensegaAddons® by Stéphane Hamel is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

Basically, you are allowed to use gaAddons® on your own website if you don't resell/repackage/redistribute it.
 
Corporate websites
Althought it is not a requirement, a donation would be much appreciated! As a web analytics practitioner, you are allowed to use gaAddons® on your corporate website.
 
Consultants & Agencies
As an agency or consultant you are NOT authorized to use gaAddons® for client projects unless you get a waiver. Read the license carefully and contact me if you would like to get a commercial rights of use. This will allow you to use gaAddons® with your clients and help me work on many more great gaAddons® features.
 
For consultant
49$ USD

Benefits for consultants:
  • priority email support
  • request new features
  • rights of integration within client sites

For agency
249$ USD

Benefits for agencies:
  • same as above plus...
  • access to source code
  • be listed as a supporting partner with logo and link to your site.

Why is this?

Simply put, I don't want consultants & agencies to use my work and make money out of it without being fairly compensated. When I created the Excel Dashboard sample I realized consultants & agencies started to use it, saved a lot of time by leveraging my work, and charged their clients... With WASP, a similar situation happened - consultants consistently used the free version without ever paying a license.

Please be fair, if you find gaAddons® useful, contribute or request a waiver if you are a consultant or agency.