Introduction

The mPulse Beacon API (Version 2) exposes a simple way to send and log beacon data from configured web and native apps.

This API includes both a REST API for use with web and native apps, as well as an mPulse Library for iOS and Android.

This Reference details how to configure and initialize the mPulse Library in native iOS and Android apps as well as via the REST API on the web and from native apps.

What types of data can I send?

mPulse recognizes beacons from configured Metrics, Timers, and Page Groups (web) or View Groups (native).

Getting Started

Before using this API, the user will need to have an mPulse configured app and an associated API Key.

Once your app has been configured in mPulse, you will use the REST API, iOS, and/or Android integration sections to get started.

Choosing An Integration Method

For web apps use the REST API. Refer to REST API for details.
For iOS/Android app instrumentation, you can use either the native mPulse Library or the REST API.
- The REST API requires writing code to download the mPulse configuration, time the HTTP requests to use, and issue API requests to send beacons. Refer to REST API for details.
- The mPulse Library provides auto-instrumentation of HTTP requests and a programmatic API for setting Timer and Metric values. Refer to the Integration section for iOS and/or Android.

Getting Started with REST API

After electing to use the REST API, your integration steps include all of the following:

Learn how to construct a beacon.
Start or stop (send) a timer.
Set the value of a metric.
Set the beacon page group.

All of the above values are defined by an App Administrator using mPulse’s Configure Apps box.

Getting Started with iOS

The iOS integration section describes how to add the mPulse Framework to an Xcode project.

Once this is done you can do any of the following:

Start or stop (send) a timer.
Set the value of a metric.
Set the beacon view group.

All of the above values are defined by an App Administrator using mPulse’s Configure Apps box.

Getting Started with Android

The Android integration section describes how to inject the mPulse Library into your app using the Add mPulse utility and to initialize it in your code.

Once this is done you can do any of the following:

Start or stop (send) a timer.
Set the value of a metric.
Set the beacon view group.

All of the above values are defined by an App Administrator using mPulse’s Configure Apps box.

Metrics

Metrics are user-defined counts that refer to a business goal, or to a Key Performance Indicators (KPI) such as revenue, conversion, orders per minute, widgets sold, etc. The value or meaning of a Metricis defined by the App Administrator.

You can programmatically set a Metric for a given page or view using the REST API or in your mPulse-enabled native app’s source code.

Timers

A Timer can be based on any measurable user-defined value in the page or view. Timers set the clock on the performance of your app that may not be covered by using a default navigation timer.

For example, use the REST API to track the time it took for widget to initialize or data to be processed.

Similarly, use the native mPulse Library to programmatically start and stop a timer on actions such as photo uploads.

Refer to mPulse Timers

Page Groups and View Groups

A Page Group (or View Group in a native app) allows for measurement across pages (or views) that belong together. Grouping pages and view in this way helps you capture and summarize the performance characteristics across the entire group.

For web apps, the home page may make up one page group, while the login page may make up a second, and product pages a third such group. Search results and checkout pages may also have their own groups.

You can programmatically set page group for a given page or view using the REST API or in your mPulse-enabled native app’s source code.

Dimensions

In addition to the out-of-the-box dimensions already provided within mPulse, App Admins can define additional dimensions for the given app. For example, a custom dimension to track back-end data from a CRM, or Premium Users versus Free Users.

In general, the possible values for a Custom Dimension should have a limited number of possible return values.

You can programmatically set the dimension using the REST API or in your mPulse-enabled native app’s source code.

Integration

The following examples detail integration steps for web apps using the REST API, iOS, and Android.

REST API

The REST API exposes a simple way to send beacon data from any web, native, hybrid, or server app in any programming language.

Developers will create HTTP requests for two different URLs:

The Configuration URL (config.json)

Returns the configuration response in JSON form. This response includes the session ID, session start timestamp, a unique crumb, and so forth.

The Beacon URL

This is constructed from required values found in the config.json response, as well as any additional optional parameters.

Getting Config

You will need the API Key for the configured mPulse app (e.g. the key found in mPulse’s Configure Apps, General tab, API key field), as well as the additional required fields covered below.

Construct a GET request to the config.json URL using all of the required fields.

The Configuration URL to use is:

https://c.go-mpulse.net/api/config.json

Config.json Request Fields

The following fields are added to the request.

API_Key (&key) - required.

For example, if the API key is:

XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY

Then, begin constructing a config.json request using:

https://c.go-mpulse.net/api/config.json?key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY

Beacon URL (&bcn=) - optional.

The first call to config.json will return the Beacon URL, which should be cached and used.

Users can optionally attach the cached Beacon URL to subsequent Config request calls using &bcn= field. This will make sure that the beacon URL delivered as part of the Config JSON reflects the beacon URL used by the client as long as it’s valid. If the beacon URL is not valid anymore, the Config URL will deliver a different beacon URL that should be used afterwards.

So, for example, if //36d71138.mpstat.us/ is the Beacon URL, the URL encoded config request will look like - https://c.go-mpulse.net/api/config.json?key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY&bcn=%2F%2F36d71138.mpstat.us%2F

Refreshing the CONFIG.JSON

Changes to the app or domain’s definition within mPulse will be reflected in config.json.

In addition, mPulse may change other data returned by config.json periodically, such as the Beacon URL.

Finally, the request crumb values (h.cr and h.t) expire after 10 minutes. For these reasons, you should refresh config.json every 5 minutes.

Refresh (&r) - optional.

You can optionally use the &r field with the Config request URL to request a smaller payload.

When the &r field is used, the server assumes that the user already has the initial payload and will only send updated h.t and h.cr data.

For example,

{"h.t": 1426624783420,"h.cr": "3cf38dd8e4923e96c30760f67ba352cdf06e8d0f"}

When the &r field is present, the Config request URL will look like this,

https://c.go-mpulse.net/api/config.json?key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY&r

Getting Config using curl

Example curl request

$ curl -A "" "https://c.go-mpulse.net/api/config.json?key=#####-#####-#####-#####-#####"

Note the curl syntax example shown on the right:

Use all of the required fields and any optional ones that are pertinent (e.g. such as the occasional use of crumb refresh).

Example curl response

  {
    "session_id":"6ad5f44a-466f-4373-b3c7-b5cfdd22118d",
    "h.key":"XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY",
    "h.d":"mobile-beacons.example.com",
    "h.t":1421874698124,
    "h.cr":"131b1721c986a42bb8f7f8488ad556f12115fa3d",
    "site_domain":"mobile-beacons.example.com",
    "beacon_url":"//xyz.mpstat.us/",
    "beacon_interval":5
  }

The curl command should return a JSON response similar to the example one (right column):

Required Fields to Parse

Issuing a request to config.json using the required parameters covered in the Getting Config section above will get a JSON response similar to the following one:

Once the config.json response has been received, take steps to extract the following required fields.

You should also take note of the Collector value (e.g. "//36d71138.mpstat.us/") for use in the subsequent Beacon URL.

Table 1: Required Fields to Parse

session_id	The session_id is used for the entire user session. It can be parsed from the response or you can provide a different session ID (for example, by generating a UUID to use).
h.cr	Anti Cross-Site-Request-Forgery (CSRF) hash. Expires after 10 minutes (and can be refreshed by a new config.json request with the `&r` parameter)
h.t	Anti Cross-Site-Request-Forgery (CSRF) hash timestamp in EPOCH format. Expires after 10 minutes (and can be refreshed by a new config.json request with the `&r` parameter).
beacon_url	The URL to which the beacon is sent. Subsequent config.json refresh(es) with the `&r` parameter may change this URL.

Construct a Beacon URL

Now that the config.json response has been parsed, do the following:

1. Issue a beacon to the beacon_url value returned on your config.json.

For example, based on the beacon_url of //36d71138.mpstat.us/ you would send a Beacon to https://36d71138.mpstat.us.

    https://<beacon_url>/?

      h.key=<API-KEY>

      &h.d=<registered domain name>

      &h.cr=<cached h.cr value>

      &h.t=<cached h.t value>

      &rt.si=<session id>

      &rt.ss=<timestamp when session started>

      &rt.sl=<number of actions/pages/views in this session>

      &rt.start=manual

      &rt.tstart=<timestamp when all timings start>

      &t_done=<time to complete request>

      &u=<url>

Sending a Beacon using curl

You can use curl to send your beacon:

$ curl POST -A "" "https://[beacon_url]/?[parameters]"

The following parameters can be sent to the Beacon URL:

Table 2: Required and Optional Beacon Parameters

h.key	<API-KEY>	(required)
h.cr	<h.cr> (The crumb)	(required)
h.d	<h.d > (The registered domain)	(required)
h.t	<h.t > (The timestamp)	(required)
rt.si	<session_id or your own session ID>	(required)
rt.ss	<timestamp when session started>	(required)
rt.sl	<number of actions/pages/views in this session>	(optional)
rt.start	“manual”	(required)
rt.tstart	<event start timestamp>	(required)
t_done	<event duration>	(required)
u	<event URL>	(required)

iOS

The mPulse Native iOS API can be used in your iOS app to send beacons to mPulse.

Instrument An iOS Project with mPulse Framework

The preferred instrumentation method uses SOASTA’s mPulse Framework and is covered below. For alternate instructions using Cocoa Pods, refer to Appendix I below.

1. Navigate to the mPulse Resources page and download the MPulse.framework.zip archive.

2. Unzip the MPulse.framework.

3. Drag and drop the framework into your Xcode project.

4. Navigate to the “Build Phases” section of your target and add the following Libraries (if not already present) to the “Link Binary With Libraries” step:

- CoreTelephony.framework

- CoreLocation.framework

- SystemConfiguration.framework

- libc++.dylib

- libz.dylib

Initialize the mPulse Library in iOS

To initialize the library:

    #import <MPulse/MPulse.h>`
    #define MPULSE_API_KEY @"YOUR_API_KEY"
    // Initialize the library with your 
    // mPulse api key, MPULSE_API_KEY 
    [MPulse initializeWithAPIKey:MPULSE_API_KEY]; 
    // Later, you can get your instance with
    MPulse *mpulse = [MPulse sharedInstance];

Add #import <MPulse/MPulse.h> to the Xcode project.
Then, call [MPulse initializeWithAPIKey:MPULSE_API_KEY]; (using your API Key as its argument).

The iOS MPulse Native API has a single shared instance that you can use to send beacons.

After you’ve called initializeWithAPIKey:, you can access the mPulse API shared instance by calling [MPulse sharedInstance].

In most cases, it makes sense to initialize in application:didFinishLaunchingWithOptions:.

Send a Timer using Start and Stop

This API lets users start a Timer specified by timerName and returns the timerID that can be used to stop this Timer.

Using startTimer and stopTimer you can track the time it took for any action to occur, such as an image upload or an attachment file download.

Start a Timer at the beginning of an action:

NSString *timerID = [[MPulse sharedInstance] startTimer:@"NewPhotoAutoUpload"];

Call startTimer and give the timer a name.

mPulse returns a unique ID for the timer and keeps track of time.

Stop a Timer at the end of an action:

[[MPulse sharedInstance] stopTimer:timerID];

Once the action is complete, stop the timer.

Call stopTimer by passing in the timerID.

mPulse stops the timer and sends a beacon to the server.

Send a Timer by Name and Value

[[MPulse sharedInstance] sendTimer:@"TimerName" value:4];

This API also lets users specify a timer name and value using sendTimer (as shown on the right).

Send a Metric using Metric Name and Value

Once you’ve initialized the library, you can send any metric defined within your app configuration.

[[MPulse sharedInstance] sendMetric:@"MyMetric" value:23];

Send a metric’s value using setMetric and the metric name.

sendMetric:metricName:value:

For example, using the name “MyMetric” and value 23:

Set View Groups in iOS Apps

[[MPulse sharedInstance] setViewGroup:@"MyViewGroup"];

This API lets you get, set, and reset the View Group. Once set, the View Group will be associated with every subsequent beacon.

Set a value using setViewGroup and the group name:

[[MPulse sharedInstance] resetViewGroup];

NSString* viewGroup = [[MPulse sharedInstance] getViewGroup];

Reset the currently set View Group value.
Get the current View Group value.

Set Dimensions in iOS Apps

This API lets you get, set, and reset user-defined Dimensions. Once set, the Dimension will be associated with every subsequent beacon.

[[MPulse sharedInstance] setDimension:@"My Dimension" value:@"new value"];

Set a value using setDimension and the dimension name:

[[MPulse sharedInstance] resetDimension:@"My Dimension"];

Reset the currently set dimension value.

NSString* dimension = [[MPulse sharedInstance] getDimension:@"My Dimension"];

Get the current Dimension value.

Android

The mPulse Native Android API can be used in your Android app to send beacons to mPulse.

Instrument an Android Project with AMP

The Add MPulse (AMP) utility supports static instrumentation of an Android project.

To get the Add mPulse utility, login to mPulse and open Central > Resources (found at the bottom of the Central tree).
In Resources, locate the Downloads section, and click the Add MPulse Utility to download it.
Unarchive the AddMPulse.zip file. This archive contains the AddMPulse executable that is used to perform mPulse Library injection. Take note of your AddMpulse folder for use in the command line steps below.
From the AddMpulse folder, run the AMP command substituting your own values:

sh AddMPulse/bin/AddMPulse -project <Android project directory>

where:

Android project directory is the path to the Android folder representing your project.

Note that for Windows the syntax is slightly different. For example,

C:\> AddMPulse\bin\AddMPulse.bat -project <Android project directory>

Initialize the mPulse Library in Android

To start tracking with the mPulse Native Android API, you must first initialize your Android project with your API Key.

import com.soasta.mpulse.android.MPulse;
public static final String MPULSE_API_KEY = "YOUR_API_KEY";
// Initialize the library with your MPulse api key 
MPulse.initializeWithAPIKey(MPULSE_API_KEY);
// Later, you can get your instance with
MPulse mpulse = MPulse.sharedInstance();

Add import com.soasta.mpulse.android.MPulse; to the Android project.
Then, call MPulse.initializeWithAPIKey() using your API Key as its argument.

The Android MPulse Native API has a single shared instance that you can use to send beacons.

After you’ve called initializeWithAPIKey(), you can access the mPulse API shared instance by calling MPulse.sharedInstance().

In most cases, it makes sense to do this in your main launch activity’s onCreate() method.

Send a Timer using Start and Stop

The mPulse Android Native API can be used to send a Timer.

You can track the time it took for an action to occur, such as an image upload or an attachment file download, using Timers.

At the “start” of your action, call startTimer by giving it a timerName. mPulse returns a unique ID for the timer and keeps track of time.
At the “end” of your action, call stopTimer by passing in the timerID. mPulse stops the timer and sends a beacon to the server.

String timerID = MPulse.sharedInstance().startTimer("MyTimer"); // returns a timer ID, ex: "MyTimer-d4d67062-7064-42b5-85ed-4e69d8824ef9"

Start a Timer at the beginning of an action:

Call startTimer and give the timer a name.

mPulse returns a unique ID for the timer and keeps track of time.

MPulse.sharedInstance().stopTimer(timerID);

Stop a Timer at the end of an action:

Once the action is complete, stop the timer.

Call stopTimer by passing in the timerID.

mPulse stops the timer and sends a beacon to the server.

MPulse.sharedInstance().sendTimer("MyTimer", 4);

Send a Timer by Name and Value

This API also lets users specify a timer name and value using sendTimer(as shown on the right).

MPulse.sharedInstance().sendMetric("MyMetric", new Integer(23));

Send a Metric using Metric Name and Value

Once you’ve initialized the library, you can send any metric defined within your app configuration.

Send a metric’s value using setMetric and the metric name. For example, using the name “MyMetric” and value 23:

Set View Groups in Android Apps

MPulse.sharedInstance().setViewGroup("MyViewGroup");

This API lets you get, set, and reset the View Group. Once set, the View Group will be associated with every subsequent beacon.

Set a value using setViewGroup and the group name:

MPulse.sharedInstance().resetViewGroup();

Reset the currently set View Group value.

MPulse.sharedInstance().getViewGroup();

Get the current View Group value.

Set Dimensions in Android Apps

This API lets you get, set, and reset user-defined Dimensions. Once set, the Dimension will be associated with every subsequent beacon.

MPulse.sharedInstance().setDimension("MyDimension", "new value");

Set or reset a value using setDimension and the dimension name:

MPulse.sharedInstance().resetDimension("MyDimension");

Reset the currently set Dimension value.
Get the current Dimension value.

MPulse.sharedInstance().getDimension("MyDimension");

Appendices

Appendix I

Instrument An iOS Project using Cocoa Pods

An alternate instrumentation method that uses Cocoa Pods is covered below.

1. Install CocoaPods using:

$ gem install cocoapods

2. Create a file in your Xcode project called Podfile and add the following line to it:

pod 'mPulse'

3. Run pod install in your Xcode project directory, and then open the Xcode workspace.

$ pod install

After completing these steps, return to iOS Integration and provide your app’s API key in the initialization steps. You can find it in the Configure App box in mPulse Central > Apps.