API
TrainingSupportCommunity

mPulse Beacons

Introduction to mPulse Beacons

The mPulse Beacons API is a programmatic interface that you can use to send beacons from any web application to mPulse. This includes a Representational State Transfer (REST) interface that can be used by web applications written in any language and running on any platform. In addition, there is an mPulse Beacon API reference library for JavaScript.

Types of data you can send

You can send custom metric and custom timer beacons to mPulse with the mPulse Beacons API. For each beacon, you can set the Page Group (View Group), A/B test, and Custom Dimensions.

📘

Note:

App configuration is performed by an app administrator in mPulse Central.
The beacon component of this API is not used to manager permissions or to change the configuration of an app.

Getting started

Before using this API, you need an mPulse app and an associated API key. For information on how to setup the mPulse app and API key, see mPulse setup. Once your app has been configured in mPulse, you can use any integration method to send to beacons.

Choosing an integration method

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.

For more information, see Set up a custom metric.

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.

For more information, see Set up a custom timer.

Page groups

A page group allows for measurement across pages that belong together. Grouping pages 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.

For more information, see How page groups work.

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.

More more information, see Set up a custom dimension.

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 Set up a custom metric, Set up a custom timer, Set up a custom dimension.

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.

📘

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, shown below:

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="

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.

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