mPulse Java SDK (Version 2) Reference

Introduction

The mPulse Java SDK (version 2) is a library that you can use to send beacons from any Java application to mPulse.

What types of data can I send?

The mPulse Java SDK lets you send Custom Metric and Custom Timer beacons to mPulse.

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

Getting Started

Before using the mPulse Java SDK, 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 the mPulse Java 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 the SDK.

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 the SDK.

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

View Groups

A View Group (also known as a Page Group in a web app) allows for measurement across views that belong together. Grouping views in this way helps you capture and summarize the performance characteristics across the entire group.

For mobile apps, Launch may make up one View Group, while the Login view may make up a second, and Product views a third group. Search Results and Checkout views may also have their own groups.

You can programmatically set the View Group using the SDK.

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 the SDK.

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

mPulse Java SDK

Getting the Library (Gradle)

Instrumenting a Java app with Gradle can be done by including a dependency to the build.gradle file of your project.

Add the following mPulse Java library to your compile dependencies:

dependencies {
    compile 'com.soasta.mpulse:mpulse-java:<replace with most recent version>'
    // ...
}

For <replace with most recent version>, you can find the most recent version at JCenter or Maven.

Configuration

Initialization

To use the mPulse Java SDK, you must first initialize your Java project with your API Key:

import com.soasta.mpulse.core.MPulse;

public static final String MPULSE_API_KEY = "YOUR_API_KEY";

// First, initialize with your API Key
MPulse.sharedInstance().initializeWithAPIKey(MPULSE_API_KEY);

// Later, you can interact with MPulse by getting the shared instance
MPulse mpulse = MPulse.sharedInstance();

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

In most cases, it makes sense to do this in your main method or in other app initialization code.

Shutdown

To stop using the Java SDK, you may call shutdown():

MPulse.sharedInstance().shutdown();

shutdown() may block in order to flush queued beacons. If this behavior is not desired, shutdown() accepts a timeout parameter in seconds. Setting the timeout to 0 will shutdown immediately.

MPulse.sharedInstance().shutdown(0);

The mPulse Java SDK should not be used after calling shutdown().

Send a Custom Timer

The mPulse Java SDK can be used to send a Custom Timer.

You can track the time it took for an action to occur, such as an file transfer or database request, using Custom Timers.

At the start of your action, call startTimer() by giving it a timerName. startTimer() will return a unique Timer ID (String) and will keep track of the start time:

String timerID = MPulse.sharedInstance().startTimer("MyTimer");
// -> "MyTimer-d4d67062-7064-42b5-85ed-4e69d8824ef9"

At the end of your action, call stopTimer() by passing in the Timer ID. mPulse stops the timer and sends a beacon to the server:

MPulse.sharedInstance().stopTimer(timerID);

You may also directly specify a timer name and value using sendTimer(name, value):

// value is in milliseconds
MPulse.sharedInstance().sendTimer("MyTimer", 4);

By default, the View Group, A/B Test and Custom Dimensions for the timer will be copied at the time startTimer() was called. If you wish to use the View Group, A/B Test and Custom Dimensions copied when stopTimer() was called, you can specify true for the updateDimensions parameter:

// stops the timer and updates dimensions
MPulse.sharedInstance().stopTimer(timerID, true);

If you wish to cancel a timer (and not send a beacon to mPulse), you can call cancelTimer():

// cancel the timer
MPulse.sharedInstance().cancelTimer(timerID);

Send a Custom Metric

You may increment a Custom Metric by using sendMetric():

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

Set View Groups

You may get, set, and reset the View Group. Once set, the View Group will be associated with every subsequent beacon.

View Group strings are limited to 100 characters, and can include any of the following:

  • 0-9
  • a-z
  • A-Z
  • (space)
  • _ (underbar)
  • - (dash)

Set a View Group using setViewGroup():

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

Reset the View Group using resetViewGroup():

MPulse.sharedInstance().resetViewGroup();

Get the current View Group using getViewGroup():

String viewGroup = MPulse.sharedInstance().getViewGroup();

Set A/B Test

You may get, set, and reset the A/B Test. Once set, the A/B Test will be associated with every subsequent beacon.

Set a A/B Test using setABTest():

MPulse.sharedInstance().setABTest("A");

Reset the A/B Test using resetABTest():

MPulse.sharedInstance().resetABTest();

Get the current A/B Test using getABTest():

String abTest = MPulse.sharedInstance().getABTest();

Set Custom Dimensions

You may get, set, and reset Custom Dimensions. Once set, the Custom Dimension will be associated with every subsequent beacon.

Set or reset a Custom Dimension using setDimension():

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

Reset the Custom Dimension using resetDimension():

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

Reset all Custom Dimensions using resetAllDimensions():

MPulse.sharedInstance().resetAllDimensions();

Get a list of all Custom Dimensions using getDimensions():

String[] dimensions = MPulse.sharedInstance().getDimensions();

Global Settings

The MPulseSettings class can be used to configure multiple SDK settings at once. MPulseSettings can be given to initializeWithAPIKey() to apply settings at startup, or later to updateSettings() to update multiple settings at once.

MPulseSettings has getters and setters for configuring the View Group, A/B Test, and Custom Dimensions.

When using MPulseSettings, any items that have not been set will not be changed:

MPulseSettings settings = new MPulseSettings();
settings.setViewGroup("Default");
settings.setABTest("A");

// configure settings at init
MPulse.sharedInstance().initializeWithAPIKey(MPULSE_API_KEY, settings);

// change settings later
MPulse.sharedInstance().updateSettings(settings);