mPulse Native

Document created by DPM Admin on Jul 13, 2017
Version 1Show Document
  • View in full screen mode

The latest mPulse native documentation:

 

iOS

The mPulse Native iOS API can be used in your iOS app to send Custom Metrics and Custom Timers to mPulse.

The mPulse Native iOS library will also automatically track network requests.

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.

You can either use the library via a Framework package or via CocoaPods.

Getting the Library (Framework)

To use the mPulse Native iOS API, you can install the mPulse Native iOS Framework:

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

  2. Unzip MPulse.framework.

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

  4. Navigate to the Build Settings section of your target and add the following (if not already present) to the Other Linker Flags setting: -ObjC

  5. 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 or libc++.tdb
    • libz.dylib or libz.tdb
  6. If using mPulse from Swift, you must add the following line to the Objective-C bridging header ([project name]-Bridging-Header.h): #import "MPulse/MPulse.h

Getting the Library (CocoaPods)

The mPulse Native iOS library can also be installed via CocoaPods

gem install cocoapods  pod setup
  • Create (or update) a file in your Xcode project called Podfile and add the following line to it:
pod 'mPulse'
  • In the Podfile, use_frameworks! must be set for the desired targets.

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

pod install

Configuration

To use the mPulse Native iOS API, you must first initialize your iOS project with your API Key.

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

Objective-C

#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 withMPulse *mpulse = [MPulse sharedInstance];

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

Swift

// If mPulse was installed using Cocoapods then add the following line:import mPulse// Initialize the library with your mPulse api keylet apiKey = "YOUR_API_KEY"MPulse.initializeWithAPIKey(apiKey)

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

Automatic Network Request Instrumentation

Once included in the project, mPulse will automatically instrument all network requests.

Network requests will be instrumented as long as they are sent from one of the following classes (or a library that uses one of these classes):

  • URLConnection
  • URLSession

The following libraries (which use the above classes) will be instrumented:

  • AFNetworking
  • SDWebImage

mPulse does not automatically instrument CFNetwork usage at this time.

Send a Custom Timer

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

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

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

Objective-C:

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

Swift:

let timerID = MPulse.sharedInstance().startTimer("TimerName")

At the “end” of your action, call stopTimer: by passing in the timerID. mPulse stops the timer and sends a beacon to the server:

Objective-C:

[[MPulse sharedInstance] stopTimer:timerID];

Swift:

 MPulse.sharedInstance().stopTimer(timerID)

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

Objective-C:

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

Swift:

MPulse.sharedInstance().sendTimer("TimerName", value: 4)

 The value passed to sendTimer() in Android is a long (in milliseconds) while it is a NSTimeInterval (in seconds.milliseconds) in iOS.

Send a Custom Metric

You may increment a Custom Metric by using sendMetric::

Objective-C:

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

Swift:

MPulse.sharedInstance().sendMetric("MyMetric", value: 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 names are limited to 100 characters, and can include any of the following: 0-9, a-z, A-Z, “ ” (space), _ (underbar) and - (dash)

Set a View Group using setViewGroup::

Objective-C:

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

Swift:

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

Reset the View Group using resetViewGroup::

Objective-C:

[[MPulse sharedInstance] resetViewGroup];

Swift:

MPulse.sharedInstance().resetViewGroup()

Get the current View Group using getViewGroup::

Objective-C:

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

Swift:

let viewGroup = MPulse.sharedInstance().getViewGroup()

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::

Objective-C:

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

Swift:

MPulse.sharedInstance().setDimension("My Dimension", value: "new value")

Reset the Custom Dimension using resetDimension::

Objective-C:

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

Swift:

MPulse.sharedInstance().resetDimension("My Dimension")

Troubleshooting

No Beacons Being Sent

If you are not seeing beacons in the mPulse dashboards, please ensure the app has been configured correctly:

  • Ensure you are using the correct mPulse API Key in initializeWithAPIKey:
  • Ensure you see the following lines in the debug log after the application has started: mPulse Mobile build: n.n.n mPulse initialized. mPulse session has started.
  • If you are trying to send a Custom Timer or Custom Metric, ensure they have already been defined in the mPulse app configuration
  • Using a system proxy such as Fiddler or Charles, validate that:

FAQ

  1. I see the following error in my build logs:
Ignoring file libMPulse[Sim].a, missing required architecture [arch] in file libMPulse.a ([n] slices)

Answer: This is just a warning, and is expected. The mPulse libraries are split into two files (libMPulse.a and libMPulseSim.a) because of GitHub file size limits (100 MB), where the CocoaPod libraries are hosted. libMPulseSim.a is for simulators and libMPulse.a is for devices, and only one will be used at a time.

Java

The mPulse Java API can be used in your Java app to send Custom Metrics and Custom Timers to mPulse.

Note that you must define Custom Timers, Custom Metrics, or Custom Dimension first.

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 compilation 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 API, 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 KeyMPulse.sharedInstance().initializeWithAPIKey(MPULSE_API_KEY);// Later, you can interact with MPulse by getting the shared instanceMPulse mpulse = MPulse.sharedInstance();

After you have called initializeWithAPIKey(), you can access the shared 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 API, 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 API should not be used after calling shutdown().

Send a Custom Timer

The mPulse Java API 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():

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

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 names are limited to 100 characters, and can include any of the following: 0-9, a-z, A-Z, “ ” (space), _ (underbar) and - (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 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");

Attachments

    Outcomes