Introduction

The mPulse Beacon API (version 2) is a programmatic interface that you can use to send beacons from any web or mobile application to mPulse.

The API includes a REST interface that can be used by web and mobile applications written in any language and running on any platform.

In addition, there are mPulse Beacon API libraries for Android, iOS, Java, and JavaScript.

What types of data can I send?

The mPulse Beacon API lets you send Custom Metric and Custom Timer beacons to mPulse.

For each beacon, you can set the Page Group (View Group), A/B test, and Custom Dimensions.

Getting Started

Before using this API, you will need to have a mPulse app and an associated API Key. For information on how to setup the mPulse app and the API Key, go to mPulse setup.

Once your app has been configured in mPulse, you can use any integration method to send beacons.

Choosing An Integration Method

Any app may use the REST API.
For native Android apps, use the mPulse Android SDK.
For native iOS apps, use the mPulse iOS SDK.
For Java apps, use the mPulse Java SDK.
For web apps, use the mPulse JavaScript SDK.
For NodeJS apps, use the mPulse JavaScript SDK.

Custom Metrics

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

You can programmatically increment a Custom Metric using any of the integration methods.

Custom Metrics must be defined in the App dialog before use.

Custom Timers

A Custom Timer can be based on any measurable user-defined duration.

You can programmatically send the value of a Custom Timer using any of the integration methods.

Custom Timers must be defined in the App dialog before use.

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 views 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 using any of the integration methods.

Custom Dimensions

In addition to the out-of-the-box dimensions already provided within mPulse, App Admins can define additional Custom Dimensions for the given app. For example, a Custom Dimension to track Premium Users versus Free Users.

You can programmatically set a Custom Dimension using any of the integration methods.

Custom Dimensions must be defined in the App dialog before use.

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.

If you use Custom Timers, Custom Metrics, or Custom Dimensions, then you must define them first. For more information, see Custom Timers, Custom Metrics, and Custom Dimensions.

To use the REST API, developers will need to create HTTP requests for two different URLs:

The Configuration URL returns the configuration response (JSON). This response includes the session ID, session start timestamp, a unique crumb, and so forth.
The Beacon URL is where the beacon data is sent to, and is constructed from values found in the Configuration URL response.

Getting Config

The Configuration URL is located at:

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

You will need the API Key for your mPulse app, as well as the additional required fields covered below.

Request Parameters

The following parameters should be sent in the query string:

Name	Value	Description
`key`	API-Key	Example: `XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY`
`d`	Domain	Example: `example.com`
`bcn`	URL	(Optional) Only used on a Config Refresh. Should be the value of `beacon_url` from the first Config response.
`r`	(empty)	(Optional) Only used on a Config Refresh. Used to get a new Anti-CSRF token.

Example:

https://c.go-mpulse.net/api/config.json?key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY&d=example.com&bcn=%2F%2F36d71138.akstat.io%2F&r=

Note:

If you are loading config.json via a tool like curl, you may need to spoof the User-Agent string. mPulse apps configured with Include Bot Beacons un-checked will reject requests from curl. You can use -A to specify the curl User-Agent string:

curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36" \
    "https://c.go-mpulse.net/api/config.json?key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY&d=example.com&bcn=%2F%2F36d71138.akstat.io%2F&r="

Response

A JSON object, containing the following values:

Name	Description
`session_id`	Session ID for the user. You can use this ID, or you can provide your own session ID (for example, by generating a UUID to use).
`h.key`	The API key you provided.
`h.d`	The app’s domain.
`h.t`	Anti-CSRF timestamp to use when sending beacons. Expires after 10 minutes.
`h.cr`	Anti-CSRF token to use when sending beacons.
`beacon_url`	Where to send beacons to.

Example

{
    "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",
    "beacon_url": "//xyz.akstat.io/"
}

If the URL given back by beacon_url is not the same as you sent in for the bcn parameter, you should switch to the new beacon_url server for sending beacons.

Refreshing Config

Changes to the app’s configuration within mPulse will be reflected in the config.json response.

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 using the &r= parameter.

Sending a Beacon

To send a beacon, you will need to first fetch the config.json response. From that response, you can use the beacon_url to send a beacon.

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

Generic Request Parameters

Parameter	Value	Sample	Required?
`api`	`1`	`1`	Yes
`api.v`	`1`	`1`	Yes
`h.key`	API-key	`XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY`	Yes
`h.d`	`h.d` from `config.json`	`mydomain.com`	Yes
`h.cr`	`h.cr` from `config.json`	`ad73390de5ba3bdff928806651a4f528dfa98983`	Yes
`h.t`	`h.t` from `config.json`	`1450215931908`	Yes
`rt.end`	When the event occurred	`1450215932000`	Yes
`rt.start`	`manual`	`manual`	Yes
`rt.si`	`session_id` from `config.json` (Or your own)	`c66b9434-965f-47a0-8c41-302dacc1fbcf`	No
`rt.ss`	Timestamp when the session started	`1450215932314`	No
`rt.sl`	Session length	`3`	No
`h.pg`	Page Group / View Group	`My Page Group`	No
`h.ab`	A/B test	`AB Test 1`	No
`cdim.[name]`	Custom Dimension	`MyDimension`	No

For a full list of beacon parameters, see the What’s in a Beacon document.

Adding Custom Metrics

To add a Custom Metric, you will need to parse the config.json response for the PageParams.customMetrics object.

For example, if you have a single Custom Metric:

{
    // ...
    "PageParams": {
        "customMetrics": [
            {
                "name": "MyMetric",
                "index": 2,
                "type": "Custom",
                "label": "cmet.MyMetric",
                "dataType": "Number"
            }
        ]
    }
}

Custom Metrics get added to a beacon as the parameter specified by label.

For example, to send a Custom Metric for MyMetric with a value of 1:

cmet.MyMetric=1

Adding Custom Timers

To add a Custom Timer, you will need to parse the config.json response for the PageParams.customTimers object.

For example, if you have a single Custom Timer:

{
    // ...
    "PageParams": {
        "customTimers": [
            {
                "name": "MyTimer",
                "index": 0,
                "type": "Custom",
                "label": "custom0"
            }
        ]
    }
}

Custom Timers get added to a beacon as the t_other parameter. t_other is a comma-separated list of Custom Timer labels and values in the following format:

t_other=[label1]|[value1],[label2]|[value2],...

For example, to send a Custom Timer for MyTimer with a value of 10:

t_other=custom0|10

Adding Custom Dimensions

To add a Custom Dimension, you will need to parse the config.json response for the PageParams.customDimensions object.

For example, if you have a single Custom Dimension:

{
    // ...
    "PageParams": {
        "customDimensions": [
            {
                "name": "Visibility State",
                "index": 0,
                "type": "JavaScriptVar",
                "label": "cdim.Visibility_State",
                "dataType": "Text",
                "xhr_ok": true,
                "varName": "document.visibilityState"
            }
        ]
    }
}

Custom Dimensions get added to a beacon as the cdim.[name] parameter. [name] is the Dimension’s name with any spaces replaced with _. You can use the label attribute for the beacon parameter name.

For example, to send a Custom Dimension for Visibility State with a value of visible:

cdim.Visibility_State=visible

Example

Here’s a full example setting a Page Group, A/B test, Dimension, and sending a Custom Metric and Timer:

https://<beacon_url>/?
    h.key=XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY
    &h.d=mydomain.com
    &h.cr=ad73390de5ba3bdff928806651a4f528dfa98983
    &h.t=1450215931908
    &rt.start=manual
    &rt.si=c66b9434-965f-47a0-8c41-302dacc1fbcf
    &rt.ss=1450215932314
    &rt.sl=3
    &h.pg=My%20Page%20Group
    &h.ab=AB1
    &cdim.Visibility_State=visible
    &cmet.MyMetric=1
    &t_other=custom0|10

Return Values

The Beacon URL will respond with an empty 204 No Content response.