mPulse Beacon API (Version 2) Reference

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

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
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&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/"
}

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[n] Custom Dimension #n 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

Example

Here’s a full example setting a Page Group, A/B test, 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
    &cmet.MyMetric=1
    &t_other=custom0|10

Return Values

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