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

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

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] (https://community.akamai.com/docs/DOC-8511).

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

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="img-src https://*.akstat.io; connect-src https://*.akstat.io https://*.go-mpulse.net;">

Explanation of individual rules:

• img-src https://*.akstat.io: Boomerang will send GET requests with beacon data to a host in the akstat.io domain using dynamically created IMG elements over HTTPS.

• connect-src https://*.akstat.io: Boomerang will send POST requests with beacon data using XHR or the sendBeacon API to a host in the akstat.io domain over HTTPS.

• connect-src https://*.go-mpulse.net: Boomerang will fetch it's configuration from *.go-mpulse.net using XHR over HTTPS.

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

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

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

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

A reference to the mPulse app.

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

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

• name (String) Custom Timer name

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

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

Stops a timer previously started via startTimer().

• id (String) Timer ID from startTimer()

The number of milliseconds that the timer ran.

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

Sends a timer with the specified name and value.

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

The number of milliseconds that the timer ran.

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

Sends a Custom Metric with the specified value.

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

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

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

• pageGroup (String) Page Group name

mPulse.setPageGroup("My Page Group");

Gets the current Page Group.

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

var pg = mPulse.getPageGroup();

Resets (clears) the Page Group.

mPulse.resetPageGroup();

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

• bucket (String) A/B bucket

mPulse.setABTest("A");

Gets the A/B bucket.

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

var abTest = mPulse.getABTest();

Resets (clears) the A/B bucket.

mPulse.resetABTest();

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

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

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

Resets (clears) a Custom Dimension.

• name (String) Custom Dimension name

mPulse.resetDimension(name);

Set the Session ID.

• id (String) Session ID

mPulse.setSessionID("ABC-123");

Gets the current Session ID.

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

var sid = mPulse.getSessionID();

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

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

The new Session ID.

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

Increment the Session Length by one.

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

Sets the Session Length to the specified value.

• len (Number) Session length

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

Gets the Session Length.

The Session Length.

mPulse.startSession();

mPulse.setSessionLength(2);

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

Gets the Session Start.

The Session Start.

mPulse.startSession();

var st = mPulse.getSessionStart();

Sets the Session Start.

mPulse.startSession();

mPulse.setSessionStart(Date.now());

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.

true on success.

mPulse.transferBoomerangSession();

Subscribe to events.

Available events:

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

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

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

// 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

• v0.0.1 - May 26, 2015
  • Initial release
• v0.0.2 - September 10, 2015:
  • Added support for A/B tests: setABTest(), getABTest() and resetABTest() functions added
  • BREAKING Change: setViewGroup() was changed to setPageGroup(). resetViewGroup() was changed to resetPageGroup()
  • Added getPageGroup()
• v1.0.0 - March 14, 2016
  • Updated to mPulse Beacon API v2
• v1.0.1 - April 13, 2016
  • console.warn() when using a Custom Timer, Metric or Dimension that doesn't exist
  • console.warn() if you don't specify the REST API Secret Key on init()
• v1.0.2 - July 11, 2016
  • Fix for IE 9 / XDomainRequest
• v1.1.0 - June 1, 2017
  • Fix for session start time
  • Set rt.tstart and rt.end on the beacon instead of when
  • New session start functions: .setSessionStart(), .getSessionStart()
  • New function to transfer Boomerang sessions: .transferBoomerangSession()
• v1.2.0 - July 19, 2018
  • Adds support for Appcelerator Titanium
• v1.3.0 - November 12, 2019
  • Exports sendBeacon
  • Optionally specify the User-Agent for the beacon
• v1.3.1 - November 18, 2019
  • Optionally specify the User-Agent for the config.json fetch
• v1.3.2 - November 18, 2019
  • Switched node-XMLHttpRequest dependency to fix driverdan/node-XMLHttpRequest#128 so User-Agent header is set
• v1.3.4 - March 4, 2020
  • Updated to crypto-js@4.0.0
• v1.3.5 - April 16, 2020
  • mpulse.js will pause sending beacons when the app is rate limited
  • mPulse.isInitialized() function added
• v1.3.6 - July 9, 2021
  • User-Agent header is no longer set in the browser