Using PMF Analytics API in Client Applications

Overview

Persistent Mobile Foundation Analytics provides client-side APIs to help a user get started with collecting analytics data about the application. This tutorial provides information on how to set up analytics support on the client application, and lists available APIs.

Configuring analytics on the client side

Before you can start collecting the predefined data that Persistent Mobile Foundation Analytics provides, you must first import the corresponding libraries to initialize the analytics support.

JavaScript (Cordova)

In Cordova applications, no setup is required and initialization is built-in.

JavaScript (Web)

In Web applications, the analytics JavaScript files must be referenced. Make sure you have first added the PMF Web SDK. For more information, see Adding the PMF SDK to Web applications tutorial.

Depending on how you’ve added the PMF Web SDK, proceed in either of the following ways:

Reference Persistent Mobile Foundation Analytics in the HEAD element:

<head>
    ...
    <script type="text/javascript" src="node_modules/ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics.js"></script>
    <script type="text/javascript" src="node_modules/ibm-mfp-web-sdk/ibmmfpf.js"></script>
</head>

Or, if using RequireJS, write:

require.config({
	'paths': {
		'ibmmfpfanalytics': 'node_modules/ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics',
		'mfp': 'node_modules/ibm-mfp-web-sdk/ibmmfpf'
	}
});

require(['ibmmfpfanalytics','mfp'], function(ibmmfpfanalytics, WL) {
    // application logic.
});

Note that you can select your own namespace to replace “ibmmfpfanalytics”.

ibmmfpfanalytics.logger.config({analyticsCapture: true});

Important: Some JavaScript API differences exist between the Cordova and Web SDKs. Please refer to the API Reference topic in the user documentation.

iOS

Import the WLAnalytics library

Objective-C

import "WLAnalytics.h"

Swift

import PersistentMobileFoundation

Initialize Analytics

Objective-C
No setup required. Pre-initialized by default.

Swift
Before calling other methods of the WLAnalytics class, call WLAnalytics.sharedInstance().

Android

Import WLAnalytics

import com.worklight.common.WLAnalytics;

Initialize Analytics

Inside the onCreate method of your main activity include:

WLAnalytics.init(this.getApplication());

Enabling/disabling client event types

The Analytics API gives the developer the freedom to enable and disable collecting Analytics for the event they want to visualize on their PMF Analytics Console.

The Persistent Mobile Foundation Analytics API allows for the capturing of the following metrics.

Lifecycle events: app usage rates, usage duration, app crash rates
Network usage: breakdown of API call frequencies, network performance metrics
Users: users of the app that are identified by a supplied user ID
Custom analytics: custom key/value pairs that are defined by the app developer

The initialization of the analytics API must be written in native code, even in Cordova apps.

To capture app usage, you must register app lifecycle event listeners before the relevant event occurs and before sending the data to the server.
To use the file system or native language and device features, the API must be initialized. If the API is used in a way that requires native device features (like the file system), but was not initialized, the API call fails. This behavior is especially true on Android.

Note: To build Cordova applications, the JavaScript Analytics API does not have methods to enable or disable the collection of LIFECYCLE or NETWORK events. In other words, Cordova applications come with LIFECYCLE and NETWORK events pre-enabled by default. If you want to disable these events, see Client Lifecycle Events and Client Network Events.

Client lifecycle events

After the Analytics SDK is configured, app sessions start to be recorded on the user’s device. A session in Persistent Mobile Foundation Analytics is recorded when the app is moved from the foreground to the background, which creates a session on the PMF Analytics Console.

As soon as the device is set up to record sessions and you send your data, you can see the PMF Analytics Console populated with data, as shown below.

sessions-chart

Enable or disable the collecting of app sessions using the Analytics API.

JavaScript

Web
To use client lifecycle events, initialize analytics:

ibmmfpfanalytics.logger.config({analyticsCapture: true});

Cordova
To enable the capture of the lifecycle events, it must be initialized in the native platform of the Cordova app.

For the iOS platform:
- Open the [Cordova application root folder] → platforms → ios → Classes folder and find the AppDelegate.m (Objective-C) or AppDelegate.swift (Swift) file.
- Follow the iOS guide below to enable or disable LIFECYCLE activities.
- Build the Cordova project by running the command: cordova build.
For the Android platform:
- Open the [Cordova application root folder] → platforms → android → src → com → sample → [app-name] → MainActivity.java file.
- Look for the onCreate method and follow the Android guide below to enable or disable LIFECYCLE activities.
- Build the Cordova project by running the command: cordova build.

Android

To enable client lifecycle event logging:

WLAnalytics.addDeviceEventListener(DeviceEvent.LIFECYCLE);

To disable client lifecycle event logging:

WLAnalytics.removeDeviceEventListener(DeviceEvent.LIFECYCLE);

iOS

To enable client lifecycle event logging:

Objective-C:

[[WLAnalytics sharedInstance] addDeviceEventListener:LIFECYCLE];

Swift:

WLAnalytics.sharedInstance().addDeviceEventListener(LIFECYCLE);

To disable client lifecycle event logging:

Objective-C:

[[WLAnalytics sharedInstance] removeDeviceEventListener:LIFECYCLE];

Swift:

WLAnalytics.sharedInstance().removeDeviceEventListener(LIFECYCLE);

Client Network Activities

Collection on adapters and the network occur in two different locations: on the client and on the server:

The client collects information such as roundtrip time and payload size when you start collecting on the NETWORK device event.
The server collects back-end information such as server processing time, adapter usage, used procedures.

Because the client and the server each collect their own information, charts do not display data until the client is configured to do so. To configure your client, you need to start collecting for the NETWORK device event and send it to the server.

JavaScript

Web
To use client network events, initialize analytics:

ibmmfpfanalytics.logger.config({analyticsCapture: true});

Cordova
To enable the capture of the network events, it must be initialized in the native platform of the Cordova app.

For the iOS platform:
- Open the [Cordova application root folder] → platforms → ios → Classes folder and find the AppDelegate.m (Objective-C) or AppDelegate.swift file.
- Follow the iOS guide below to enable or disable NETWORK activities.
- Build the Cordova project by running the command: cordova build.
For the Android platform: navigate to the subactivity of the main activity to disable.
- Open the [Cordova application root folder] → platforms → ios → src → com → sample → [app-name] → MainActivity.java file.
- Look for the onCreate method and follow the Android guide below to enable or disable NETWORK activities.
- Build the Cordova project by running the command: cordova build.

iOS

To enable client network-event logging:

Objective-C:

[[WLAnalytics sharedInstance] addDeviceEventListener:NETWORK];

Swift:

WLAnalytics.sharedInstance().addDeviceEventListener(NETWORK);

To disable client network-event logging:

Objective-C:

[[WLAnalytics sharedInstance] removeDeviceEventListener:NETWORK];

Swift:

WLAnalytics.sharedInstance().removeDeviceEventListener(NETWORK);

Android

To enable client network-event logging:

WLAnalytics.addDeviceEventListener(DeviceEvent.NETWORK);

To disable client network-event logging:

WLAnalytics.removeDeviceEventListener(DeviceEvent.NETWORK);

Custom events

Use the following API methods to create custom events.

JavaScript (Cordova)

WL.Analytics.log({"key" : 'value'});

JavaScript (Web)

For the web API, custom data is sent with the addEvent method.

ibmmfpfanalytics.addEvent({'Purchases':'radio'});
ibmmfpfanalytics.addEvent({'src':'App landing page','target':'About page'});

Android

After setting the first two configurations, you can start to log data as in this example:

JSONObject json = new JSONObject();
try {
    json.put("key", "value");
} catch (JSONException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

WLAnalytics.log("Message", json);

iOS

After importing WLAnalytics, you can now use the API to collect custom data, as follows:

Objective-C:

NSDictionary *inventory = @{
    @"property" : @"value",
};

[[WLAnalytics sharedInstance] log:@"Custom event" withMetadata:inventory];
[[WLAnalytics sharedInstance] send];

Swift:

let metadata: [NSObject: AnyObject] = ["foo": "bar"];  
WLAnalytics.sharedInstance().log("hello", withMetadata: metadata);

Tracking users

To track individual users, use the setUserContext method:

Cordova

Not supported.

Web applications

ibmmfpfanalytics.setUserContext(user);

iOS

Objective-C

[[WLAnalytics sharedInstance] setUserContext:@"John Doe"];

Swift

WLAnalytics.sharedInstance().setUserContext("John Doe")

Android

WLAnalytics.setUserContext("John Doe");

To un-track individual users, use the unsetUserContext method:

Cordova

Not supported.

Web applications

There is no unsetUserContext in the PMF Web SDK. The user session ends after 30 minutes of inactivity, unless another call is made to ibmmfpfanalytics.setUserContext(user).

iOS

Objective-C

[[WLAnalytics sharedInstance] unsetUserContext];

Swift

WLAnalytics.sharedInstance().unsetUserContext

Android

WLAnalytics.unsetUserContext();

Sending Analytics data

Sending Analytics is a crucial step to see client-side analytics on the Analytics Server. When data for the configured event types is collected for Analytics, the analytics logs are stored in a log file on the client device. The data from the file is sent to the PMF Analytics Server by using send method of the Analytics API.

Consider sending the captured logs periodically to the server. Sending data at regular intervals ensures that you will see up-to-date analytic data in the PMF Analytics Console.

JavaScript (Cordova)

In a Cordova application, use the following JavaScript API method:

WL.Analytics.send();

JavaScript (Web)

In a Web application, use the following JavaScript API method (depending on the namespace you’ve selected):

ibmmfpfanalytics.send();

iOS

Objective-C

[[WLAnalytics sharedInstance] send];

Swift

WLAnalytics.sharedInstance().send();

Android

In an Android application, use the following Java API method:

WLAnalytics.send();

Capturing & Sending In-App User Feedback

Use In-App User Feedback to deepen your application performance analysis. You can enable your application users and testers to provide rich contextual feedback to the app owners. App owners get real-time feedback from its users on the application usage experience which App owners and Developers can further act on. This feature brings in significant agility to application up-keep. Use the following API to switch your application to Interactive Feedback Mode in any action handler in your application, for example, when you handle the click of a button or the selection of a menu item.

This feature is not supported for Web Applications.

JavaScript (Cordova)

First add the following plug-in to include In-App Feedback capability into your Cordova application and ensure that the plugin is successfully added

cordova plugin add cordova-plugin-mfp-analytics

Now, use the following JavaScript API method in the action handler of your Cordova application.

WL.Analytics.triggerFeedbackMode();

JavaScript (Web)

Not Supported

iOS

Swift

First add the following to your application’s podfile.

pod 'PersistentMobileFoundationAnalytics'

Next ensure you update your pod by running the following command at the root of your XCode project.

pod update

Now call the following API in the action handler of your application.

WLAnalytics.sharedInstance().triggerFeedbackMode();

Android

First add the following dependency into your application’s gradle script.

compile 'com.ibm.mobile.foundation:ibmmobilefirstplatformfoundationanalytics:9.0.+@aar'

Then in your Android application, use the following Java API method in the action handler:

WLAnalytics.triggerFeedbackMode();

▲

Last modified on

Using PMF Analytics API in Client Applications

Overview

Jump to

Configuring analytics on the client side

JavaScript (Cordova)

JavaScript (Web)

iOS

Import the WLAnalytics library

Initialize Analytics

Android

Import WLAnalytics

Initialize Analytics

Enabling/disabling client event types

Client lifecycle events

JavaScript

Android

iOS

Client Network Activities

JavaScript

iOS

Android

Custom events

JavaScript (Cordova)

JavaScript (Web)

Android

iOS

Tracking users

Cordova

Web applications

iOS

Android

Cordova

Web applications

iOS

Android

Sending Analytics data

JavaScript (Cordova)

JavaScript (Web)

iOS

Android

Capturing & Sending In-App User Feedback

JavaScript (Cordova)

JavaScript (Web)

iOS

Android