web5design / boba.js

Need those links tracked? "As you wish."

Boba.js

Boba.js is a small, easily extensible JavaScript library that makes working with Google Analytics easier.

It supports the old ga.js library as well as the new analytics.js library. It has one out of the box function, trackLinks, and makes tracking everything else child's play. Requires jQuery.

Use it

Include your GA script and jQuery, then create a new instance of Boba:

tracker = new Boba

If you're using Browserify:

$ = require("jquery")
Boba = require("boba.js")
Boba.$ = $

tracker = new Boba

Constructor options

All options are optional.

tracker = new Boba({
  siteName: 'Mandalore',
  pageName: 'Slave I',
  defaultCategory: 'category',
  defaultAction: 'action',
  defaultLabel: 'label',
  watch: [
    ['click', '.js-track-solo', trackSolo],
    ['click', '.js-track-chewie', trackChewie]
  ]
})

siteName, pageName

The name of the site and page, respectively.

You can also get and set tracker.siteName and tracker.pageName at any time:

tracker.siteName = 'Mandalore'
tracker.pageName = 'Slave I'

defaultCategory, defaultAction, defaultLabel

If an event does not have a category, action, or label, these values will be used instead.

You can also change these at any time:

tracker.defaultCategory = 'category'
tracker.defaultAction = 'action'
tracker.defaultLabel = 'label'

watch

An array of arguments to apply to the watch method on initialization.

watch: [
  ['click', '.js-track-solo', trackSolo],
  ['click', '.js-track-chewie', trackChewie]
]

Instance methods

Boba#watch

tracker.watch(eventType, selector, callback)

This will set up delegated event handlers for you. Under the hood, it does something like this:

$('body').on(eventType, selector, function(event) {
  tracker.push(callback(event))
})

Examples:

tracker.watch('click', '.js-track', trackClick)
tracker.watch('change', '.js-track-select', trackSelect)

The callback is passed a jQuery event object and should return an object with category, action, label, and value properties:

{
  category: "category",
  action: "action",
  label: "label",
  value: 42
}

Any values not supplied will use defaults from the options (e.g. tracker.options.defaultCategory).

Boba#trackLinks

This is a helper that basically does this:

tracker.watch('click', '.js-track', function (event) {
  return $(event.currentTarget).data()
})

You can use these data attributes to set the category, action, label, and value when using this method:

• data-ga-category
• data-ga-action
• data-ga-label
• data-ga-value

You can pass in an alternate selector if you don't want to use '.js-track'. For example, you could use a data attribute instead of a class:

tracker.trackLinks('[data-ga-track]')

Boba#push

This can be used to fire events manually.

Example:

tracker.push({
  category: "category",
  action: "action",
  label: "label",
  value: 42
})

Contributing

See the contributing guide.