Getting Started

The full documentation can be found here.

Prerequisites

If you intend to use any of the optional device analytics in an Apache Cordova mobile app (e.g. call log or geofence tracking) you will need the following dependencies:

You only need to install the ones which you intend to use.

Installation - HTML/JavaScript

Add the JavaScript library ma-analytics.min.js to your project (download). A full example is given below in index.html and sample-script.js:

File: index.html

<!DOCTYPE html>
<html>
    <head>
        <!-- Analytics library -->
        <script type="text/javascript" src="ma-analytics.min.js"></script>
        <!-- Developer's custom code -->
        <script type="text/javascript" src="sample-script.js"></script>
    </head>
    ...
</html>

File: sample-script.js

// Initialise the MaAnalytics library
var maa = new MaAnalytics({
    tid: "YOUR-TRACKING-ID-HERE"
});

Without any additional parameters, autoTrack_AllPageViews and track_AppBackgrounding is enabled by default.

Sample Usage

Below are example capabilities. For information on all of the features, you can view all of the available features in the documentation.

Tracking a Custom Event

Here is an example of tracking a custom event. You can add this call the function trackEvent(...) inside any event listener to track custom events. The below example shows tracking a specific button click.

File: index.html

<!DOCTYPE html>
<html>
    <head>
        <!-- Analytics library -->
        <script type="text/javascript" src="ma-analytics.min.js"></script>
        <!-- Developer's custom code -->
        <script type="text/javascript" src="sample-script.js"></script>
    </head>
    <body>
        <!-- Sample button -->
        <input type="button" id="myButton" value="Click me"></input>
    </body>
</html>

File: sample-script.js

// Initialise the MaAnalytics library
var maa = new MaAnalytics({
    tid: "YOUR-TRACKING-ID-HERE"
});

// Log an analytics event on a mouse click
var myButton = document.getElementById("myButton");
myButton.addEventListener("click", function(){

    // Variables to be passed as parameters
    var CATEGORY = "my-custom-category"; // E.g. alternatives: 'app-navigation', 'order', 'search'
    var ACTION = "click"; // E.g. alternatives: 'click', 'confirm', 'purchase'
    var VALUE = 0; // optional int value, if needed.
    var LABEL = "This can be used for supplemental information";

    // Log an event to the MaAnalytics service
    maa.trackEvent(CATEGORY, ACTION, VALUE, LABEL);
});

Tracking all Button Presses

Here is an example of how to track all button presses. All of the following will be tracked: <a>, <button>, <input type="button">, and <input type="submit">.

This is enabled during the initialisation of the analytics library, but additional data may be required for each button (see below).

File: sample-script.js

Initialise the library with the parameter autoTrack_AllButtons set to true

// Initialise the MaAnalytics library
var maa = new MaAnalytics({
    tid: "YOUR-TRACKING-ID-HERE",
    autoTrack_AllButtons: true
});

File: index.html

All buttons will fire an automatic analytics event when clicked; the category for the event is automatically set to ma-analytics-autotracked-button. The action is also automatically set to the id of the DOM element, e.g. id=myButton (buttons will not be tracked if an id is not set, unless you override the action in the alternate HTML file below this example); this allows the analytics service to differentiate between button clicks.

<!DOCTYPE html>
<html>
<head>
    <!-- Analytics library -->
    <script type="text/javascript" src="ma-analytics.min.js"></script>
    <!-- Developer's custom code -->
    <script type="text/javascript" src="sample-script.js"></script>
</head>
<body>
    <!-- Sample button -->
    <input type="button" id="myButton" value="Click me"></input>
</body>
</html>

File: index.html (alternative)

Alternatively, you can override the category, action, value, and label, of individual buttons by utilising specific data attributes on each DOM element you wish to set the analytics data for:

<!-- Sample button, with override for event category and action -->
<input type="button" value="Click me" data-maanalytics-category="my-custom-category" data-maanalytics-action="my-custom-action"></input>