NAV

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>

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' http://c.go-mpulse.net http://*.mpstat.us; style-src 'self' 'unsafe-inline'; media-src *">

Adding the URLs http://c.go-mpulse.net is required to receive its configuration and http://*.mpstat.us is required to send beacons back to servers. The asterisk (*) is required as we have multiple subdomains mapped to different regions. The configuration recieved 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>

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
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
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
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
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
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
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
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
Example
mPulse.setDimension("My Dimension", "abc");

resetDimension(name)

Resets (clears) a Custom Dimension.

Parameters
Example
mPulse.resetDimension(name);

Session

setSessionID(id)

Set the Session ID.

Parameters
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
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
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();

Misc

subscribe(event, callback)

Subscribe to events.

Available events:

Parameters
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