MooTune

A MooTools class for logging events, errors and AB tests to multiple backends such as Google Analytics,
Mixpanel or your own server logs. It can be used to gain insights into the actions your user's take
on your site, the errors they encounter and the affect of variations on the site with their
interactions.

Note: this is an alpha release with functionality that matches my needs and hopefully a few other
people. We're using it on banksimple.com and it's great, but you may need to modify it to your
tastes. Mixpanel is highly recommended, especially over Google Analytics, since the event tracking
there is a wasteland.

Releases

Dependencies

How to use

Setup the tracking scripts for the backend services you'd like to use (e.g Google Analytics,
Mixpanel). Asynchronous scripts should work fine, so use them.

Create a backend if you're using your own server or a service other than the ones mentioned.

Somewhere very early in your application's javascript, create an instance of MooTune (after
domready if you have tests that modify elements).

When something happens that you'd like to track, call handleEvent on your instance and pass
it an event name and a dictionary/map/object of info.

Enjoy your sweet, sweet data.

Events

Once you create an instance of MooTune, you can add calls to myMooTune.handleEvent(obj) in your code
wherever something happens that you'd like to log to your backend(s). For each call to handleEvent,
MooTune will send the appropriate call to all of the backends you have specified. The event obj looks
like this:

The key/value pairs inside info are entirely up to you, but only 'category', 'value' and 'description'
will be sent if you are using Google Analytics. If you are using Mixpanel or your own server the
whole hash will be sent along with the event's name.

Errors

All errors logged via window.onerror will be sent as events with the following information:

Backends

When instantiating MooTune you can either pass in an array of Backends, or let it discover and use
whatever you have available. A Backend is an object that looks like this:

'Name': {
sendTestsAsEvents: <boolean>, // see below
sendTestsWithEvents: <boolean>, // see below
serviceAvailable: function(){
// returns true if service can be used (e.g. tracker code installed)
},
handleEvent: function(event){
// is passed an event and relays it to correct tracker/analytics service
}
}

sendTestsAsEvents - When each test is selected to run it is sent as an event with the form:
(Test) Name-of-test / selected-value. Use this option for backend systems that do not allow for
arbitrary key/value properties to be sent with events.

sendTestsWithEvents - Each time an event is fired, a hash containing all of the your tests will
be included, in the form { test-name: selected-value }.
If the test is not running, the value of the pair will be replaced with 'not running.'

A B Amp Multivariate Testing

MooTune supports a simple method for doing A/B (split) testing. Actually, it's multivariate (as many
options as you want). When instantiating MooTune, pass in an array of tests. Tests are objects
(surprise) that look like this:

{ name: 'Test Name',
description: 'Optional Description',
element: '#css .selector' // a css selector to get the element(s)
type: 'class', // what to set on the element(s) (class, text, html etc)
sampleSize: 1, // float between 0 and 1 for percentage of users to test
alwaysRun: false, // overrides the MooTune option for number of tests to run
persist: false, // stores test choice in cookie to persist across user's sessions
pickVersion: function(){ return test.versions[0]; }, // forces first version every time
versions: [
'some',
'values',
'to',
'test out'
],
onSelected: function(selectedVersion){} // a function that is called when the test is used
}

When a MooTune instance is created with a set of tests, it first determines (based on your options)
how many of the tests to run.

It then runs those tests, which can mean one of two things, depending on the options set for the
backend recieving the data:

sendTestsAsEvents:true - Test triggers an event that can be tracked against all other events.
Using this method, you can compare the number of times a test event fired vs. a conversion
event. If your analytics backend provides funnels, use them.

sendTestsWithEvents:true - Nothing at this point, but when any other event fires, all your tests
will be included as properties. This allows you to drill down into an event (e.g. Signup) and
see the success ratio of each test's option.

After one (or both) of those options is complete, the element itself is modified in the way you
specified, using the value selected at random.

Mootune Method Constructor

var mt = new MooTune(options);

Options

testsAtOnce - (int: defaults to null) How many tests from the tests array to run. Null means all.
if you specify a number N, the tests array will be shuffled and the first N will be
ran. All other tests will be ignored for this session, unless they have the alwaysRun
flag turned on.

useUrlParams - (boolean: defaults to true) parses the parameters in document.location.search and uses any testName/testVersion pairs to statically pick a test version. If the testVersion is a number, it will use that as an index into the versions array.

Events

testRunning - When a test is selected and runs. Arguments: test object and this.