mPulse.js

mpulse.js

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

Quick-Start

mpulse.js is available from the Akamai/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' 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>

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.

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