mPulse.js

mpulse.js

The mPulse JavaScript API (mpulse.js) allows you to send beacons from JavaScript to SOASTA mPulse via the mPulse Beacon API.

Quick-Start

mpulse.js is available from the SOASTA/mpulse.js Github repository.

The un-minified version is available at :

dist/mpulse.js

There is a minified version available at:

dist/mpulse.min.js

Please include the script in your web app prior to its use:

<script src="mpulse.js"></script>

NOTE: Use the files in dist/ instead of src/, unless the CryptoJS libraries are already loaded

mpulse.js is also available via bower. You can install using:

bower install mpulse

Usage

Once mpulse.js is loaded, there is a global mPulse object available on window.mPulse.

mpulse.js also registers itself as a RequireJS module.

For information on how to obtain the REST API Secret Key, go to mPulse setup.

To start working with the API, you first need to configure it with your API key and REST API Secret Key:

var mPulseApp = mPulse.init("api-key", "rest-api-secret-key");

After init() has been called, you can either interact with it via the returned object or via the same methods on the core mPulse object:

mPulseApp.sendTimer("My Timer", 100);
// or
window.mPulse.sendTimer("My Timer", 100);

Cordova Usage

For mPulse to work on Cordova, you need to make the following changes in your application:

In your index.html you need to extend the Content-Security-Policy to support HTTP requests to the mPulse servers:

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval' c.go-mpulse.net s.go-mpulse.net *.mpstat.us *.akstat.io; style-src 'self' 'unsafe-inline'; media-src *">

Adding the URLs [c|s].go-mpulse.net is required to receive its configuration and *.mpstat.us and *.akstat.io is required to send beacons back to servers. The asterisk (*) is required as we have multiple subdomains mapped to different regions. The configuration received from c.go-mpulse.net will point mpulse.js to the right server to send beacons to that is closest.

Include mpulse.js in your applications body as a script:

<script type="text/javascript" src="js/mpulse.min.js"></script>

NOTE: Point the src to the place where your project’s setup installed the bower build of mpulse.js. For more information, refer to the Quick-Start Guide.

Initializing mPulse in your application

In your application initialization, you need to add the following lines:

// The mpulse.js instance to use later on
var mPulseInstance = null;

// Your application specific API credentials
var APIKEY = "YOUR API KEY";
var REST_API_SECRET = "YOUR REST API SECRET";

// The start of your application
var app = {
  // Your application initialization
  initialize: function() {
    mPulseInstance = mPulse.init(APIKEY, REST_API_SECRET);
    // The rest of your application initialization
    this.bindEvents();
  },
  // Bind your application events
  bindEvents: function() {
    document.addEventListener('deviceready', this.onDeviceReady, false);
  },

  onDeviceReady: function() {
    // example mPulse.js instance interaction
    mPulseInstance.sendTimer("deviceReady", deviceReadyTime - deviceInitTime);
  },
};
app.initialize();

API Reference

Initialization

`mPulse.init(apiKey, restApiSecretKey, options)`

Parameters

apiKey (String) mPulse API key
restApiSecretKey (String) mPulse REST API Secret Key
options (Object) Additional options

Returns

A reference to the mPulse app.

Example

var mPulseApp = mPulse.init("api-key", "rest-api-secret-key");

Custom Timers

`mPulse.startTimer(name)`

Starts a timer with the specified name. Use stopTimer(id) to stop and send the timer.

Parameters

name (String) Custom Timer name

Returns

An id (string) that you can use with stopTimer(id).

Example

var timerId = mPulse.startTimer("My Timer");
// ... do stuff ...
mPulse.stopTimer(timerId);

`stopTimer(id)`

Stops a timer previously started via startTimer().

Parameters

id (String) Timer ID from startTimer()

Returns

The number of milliseconds that the timer ran.

Example

var timerId = mPulse.startTimer("My Timer");
// ... do stuff ...
mPulse.stopTimer(timerId);

`sendTimer(name, value)`

Sends a timer with the specified name and value.

Parameters

name (String) Custom Timer name
value (Number) Time (milliseconds)

Returns

The number of milliseconds that the timer ran.

Example

mPulse.sendTimer("My Timer", 100);

Custom Metrics

`sendMetric(name, value)`

Sends a Custom Metric with the specified value.

Parameters

name (String) Custom Metric name
value (Number) Custom Metric value

Example

mPulse.sendMetric("My Metric", 2);

Page Group

`setPageGroup(pageGroup)`

Set the Page Group. All subsequent beacons will have this page group. It can be later cleared via resetPageGroup().

Parameters

pageGroup (String) Page Group name

Example

mPulse.setPageGroup("My Page Group");

`getPageGroup()``

Gets the current Page Group.

Returns

The current Page Group, or false if one was not set.

Example

var pg = mPulse.getPageGroup();

`resetPageGroup()`

Resets (clears) the Page Group.

Example

mPulse.resetPageGroup();

A/B Test

`setABTest(bucket)`

Set the A/B bucket. All subsequent beacons will have this bucket. It can be later cleared via resetABTest().

Parameters

bucket (String) A/B bucket

Example

mPulse.setABTest("A");

`getABTest()`

Gets the A/B bucket.

Returns

The current A/B Test, or false if one was not set.

Example

var abTest = mPulse.getABTest();

`resetABTest()`

Resets (clears) the A/B bucket.

Example

mPulse.resetABTest();

Custom Dimensions

`setDimension(name, value)`

Set the Custom Dimension. All subsequent beacons will have this Custom Dimension. It can be later cleared via resetDimension().

Parameters

name (String) Custom Dimension name
value (String) Custom Dimension value

Example

mPulse.setDimension("My Dimension", "abc");

`resetDimension(name)`

Resets (clears) a Custom Dimension.

Parameters

name (String) Custom Dimension name

Example

mPulse.resetDimension(name);

Session

`setSessionID(id)`

Set the Session ID.

Parameters

id (String) Session ID

Example

mPulse.setSessionID("ABC-123");

`getSessionID()`

Gets the current Session ID.

Returns

The current Session ID, or false if it was not set.

Example

var sid = mPulse.getSessionID();

`startSession(id)`

Starts a new Session and sets the Session Length to 0.

Parameters

id (String) Session ID (optional). If not specified, a new UUID is used.

Returns

The new Session ID.

Example

var sid = mPulse.startSession();
// or
var sid = mPulse.startSession("MY-SID");

`incrementSessionLength()`

Increment the Session Length by one.

Example

mPulse.startSession();
mPulse.incrementSessionLength();

`setSessionLength(len)`

Sets the Session Length to the specified value.

Parameters

len (Number) Session length

Example

mPulse.startSession();
mPulse.setSessionLength(2);

`getSessionLength()`

Gets the Session Length.

Returns

The Session Length.

Example

mPulse.startSession();

mPulse.setSessionLength(2);

// should be 2
var sl = mPulse.getSessionLength();

`getSessionStart()`

Gets the Session Start.

Returns

The Session Start.

Example

mPulse.startSession();

var st = mPulse.getSessionStart();

`setSessionStart()`

Sets the Session Start.

Example

mPulse.startSession();

mPulse.setSessionStart(Date.now());

`transferBoomerangSession()`

Transfers the Session details from Boomerang (BOOMR) into mpulse.js.

This will transfer the Session ID, Start and Length from Boomerang, if it’s already on the page.

mpulse.js and Boomerang do not synchronize their session details during usage. For example, if you use mPulse.incrementSessionLength(), it will increment the Session Length for the mPulse app but not for Boomerang (BOOMR).

Returns

true on success.

Example

mPulse.transferBoomerangSession();

Misc

`subscribe(event, callback)`

Subscribe to events.

Available events:

before_beacon - Before a beacon is sent
beacon - After a beacon has been sent

Parameters

event (String) Event name
callback (Function) Function to run when the event occurs

Example

mPulse.subscribe("beacon", function() {
    console.log("A beacon was sent!");
});

Examples

Sending a custom timer

// initialize the app
mPulse.init("abcd-efgh-ijkl-mnop-qrst", "secret-key");

// set global settings
mPulse.setPageGroup("my page group");
mPulse.setABTest("my bucket");

// start the timer
var timerId = mPulse.startTimer("Timer1");

// ... do your work ...

// stop the timer
mPulse.stopTimer(timerId); // sends a beacon

// or, you can specify the amount of time
mPulse.sendTimer("Timer2", 500); // in ms