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="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 theakstat.io
domain using dynamically createdIMG
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 theakstat.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>
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 keyrestApiSecretKey
(String) mPulse REST API Secret Keyoptions
(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 fromstartTimer()
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 namevalue
(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 namevalue
(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 namevalue
(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 sentbeacon
- After a beacon has been sent
Parameters
event
(String) Event namecallback
(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