Panchaksharappa, Varuna

mPulse SDK Integration Guide - ReactNative (Android)

 

Instructions for adding the mPulse SDK to your ReactNative app for Android are shared below.

 

Required For Setup

  • Before using the mPulse SDK, you will need to have a mPulse app configuration and an associated API Key. 
  • For information on how to set up your mPulse app config and the API key, refer our Getting started guide for Pulse.
  • Follow mPulse SDK Integration Guide which details the process of integrating mPulse SDK with your Android application to send beacons from your application to mPulse.

 

Example Project

For your convenience, we've created a Sample App/project that you can use to understand the integration better and learn about using mPulse SDK and its features with ReactNative.

 

Introduction

The mPulse Android 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.

The mPulse Android SDK also monitors all network activity performed by the application and its libraries. Each network request can be monitored individually and its performance data will be sent on a beacon.

  • Network requests will be automatically instrumented as long as they are sent from java.net.URLConnection. 

  • If network requests are made through OkHttpClient or the library that uses it (examples are Picassa, Retrofit, etc.), the OkHttpClient needs to be configured to use the mPulse interceptor.

The SDK  also collects network-related statistics and are sent periodically to a server which can be accessed via portal.

The mPulse Android SDK also allows you to monitor Actions, which are distinct user interactions. Actions can be started at any time via the SDK, and stopped either programmatically or automatically by the SDK once all network activity has quieted down. All network requests during the Action will be included on the Action beacon’s Waterfall.

 

Requirements and Dependencies

The SDK supports API 15 and above. The target/compile SDK should be atleast set to API 28 and it is also required by Google for any app updates from November 2019. Google no longer maintains support libraries up until version 28 and has made androidx the default support library in Android Studio. MAP SDK has migrated from Android Support libraries to androidx-packaged library artifacts. This will not only make our SDK better, but also allows us to use the latest Jetpack features. If you have not migrated to androidx library artifacts, add the following two lines to your gradle.properties file to use MAP SDK.

android.useAndroidX=true
android.enableJetifier=true

Androidx also requires minimum build tools version to be set at 'com.android.tools.build:gradle:3.2.0'  in the root build.gradle file. The minimum gradle version should be set at gradle-4.6 in the gradle-wrapper.properties. MAP SDK has a dependency on Work Manager ('androidx.work:work-runtime:2.2.0') and the dependency is automatically pulled in to your project.

 

1. Installing the Android SDK

1.1 In Android Studio, open the build.gradle file in the app directory (not the one in the root folder ) and edit the dependencies sub-section to include aka-mpulse. Use the latest version of aka-mpulse from jcenter

implementation 'com.akamai.android:aka-mpulse:21.30.+'

1.2 The project gradle file should have jcenter() by default. If not, add it as shown below.

jcenter()

1.3 The SDK requires following permissions for full functionality: 

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2. Integration with your Android Application

Initialization 

mPulse SDK is initialized automatically and the client does not have to explicitly initialize the SDK. After initialization, the SDK needs to be registered with an API key.

 

2.1. Register the SDK

mPulse SDK is initialized automatically and the client does not have to explicitly initialize the SDK. After initialization, the SDK needs to be registered with an API key. 

Client AndroidManifest.xml will need to be updated in order to complete the SDK integration.  

In the Application tag add the below : 

<!-- Refers to sdk init file in res/xml/ -->
<meta-data
android:name="com.akamai.android.sdk"
android:resource="@xml/akamai_sdk_init" />

The SDK uses an XML file to look up the license key to authorize the client app. This information is stored in a file android_sdk_init.xml in the client app’s resources folder. The sample file is shown below.

 

2.2. In …./main/res/xml (create if it doesn’t exist!) folder, add a new file android_sdk_init.xml.

<?xml version="1.0" encoding="utf-8"?>
<com_akamai_sdk_init>
<com_akamai_mpulse_license_key>Add Mpulse License Key</com_akamai_mpulse_license_key>
</com_akamai_sdk_init>

2.3. Download/Add the AkaOkHttpInterceptor.java in your project.

 

2.4. Create a class named CustomNetworkModule and use AkaOkHttpInterceptor as below :

public class CustomNetworkModule implements OkHttpClientFactory {
  public OkHttpClient createNewNetworkModuleClient() {
      return new OkHttpClient.Builder()
              .connectTimeout(60, TimeUnit.MILLISECONDS)
              .readTimeout(60, TimeUnit.MILLISECONDS)
              .writeTimeout(60, TimeUnit.MILLISECONDS)
              .cookieJar(new ReactCookieJarContainer())
              .addInterceptor(new AkaOkHttpInterceptor())
              .build();
  }
}

 

2.5. In your MainActivity.java :

OkHttpClientProvider.setOkHttpClientFactory(new CustomNetworkModule());

 

2.6. The MPulseModule

We start by creating a native module. A native module is a Java class that usually extends the ReactContextBaseJavaModule class and implements the functionality required by the JavaScript. Our goal here is to be able to use the methods of Native mPulse SDK from JavaScript to monitor all network activity performed by the application and its libraries.

From the sample app/project copy MPulseModule.java and add it inside your project, location -  android/app/src/main/java/com/your-app-name/ folder.

ReactContextBaseJavaModule requires that a method called getName is implemented. The purpose of this method is to return the string name of the NativeModule which represents this class in JavaScript. So here we will call this MPulseLib so that we can access it through React.NativeModules.MPulseLib in JavaScript.

 

2.7. Register the Module.

The next step within Java is to register the Module; this happens in the createNativeModules of your app's package. If a module is not registered it will not be available from JavaScript.

From the sample app/project copy CustomMPulsePackage.java and add it inside your projectlocation -  android/app/src/main/java/com/your-app-name/ folder.

 

2.8. Package needs to be provided.

The package needs to be provided in the getPackages method of the MainApplication.java file. This file exists under the android folder in your react-native application directory. 

The path to this file is android/app/src/main/java/com/your-app-name/MainApplication.java.

// MainApplication.java
...
import com.your-app-name.CustomMPulsePackage; // <-- Add this line with your package name.
...


protected List<ReactPackage> getPackages() {
  @SuppressWarnings("UnnecessaryLocalVariable")
  List<ReactPackage> packages = new PackageList(this).getPackages();
  // Packages that cannot be autolinked yet can be added manually here, for example:
  // packages.add(new MyReactNativePackage());
  packages.add(new CustomMPulsePackage()); // <-- Add this line with your package name.
  return packages;
}

 

2.9. Access the functionality from JavaScript.

To access your new functionality from JavaScript, it is common to wrap the native module in a JavaScript module. This is not necessary but saves the consumers of your library the need to pull it off of NativeModules each time. This JavaScript file also becomes a good location for you to add any JavaScript side functionality.

From the sample app/project copy the JavaScript file named MPulseLib.js which has the content below:

import {NativeModules} from 'react-native';
module.exports = NativeModules.MPulseLib;

Now, from your other JavaScript file you can call the method like below :

import MPulseLib from './MPulseLib';

Now that we are all set, we can start using the features from mPulse, below are usages for the same :
 

  • Setting Custom Metric

MPulseLib.sendMetric("M_R_SplashScree",2000);

  • Setting Custom Timer

MPulseLib.startTimer("mPulseDemoTimer");

  • Action Beacons

MPulseLib.startAction("mPulseDemoAction");

  • Setting View Groups

MPulseLib.setViewGroup("MyViewGroup");

  • Setting Custom Dimensions

MPulseLib.setDimension("MyDimension", "value");

Please make sure this JavaScript is in the same hierarchy as MPulseLib.js.

2.10. Run the app

react-native run-android

 

Troubleshooting

If you run into any issues, see our general Troubleshooting section.

See our ReactNative Example Project for more help.

 

Debug logs

You need to set the log level to debug to see the debug logs associated with mPulse-sdk.

Logger.setLevel(Logger.LEVEL.DEBUG);

 

Success

  • SDK discovered

D/AkaSDKLogger: Initialized com.akamai.android.aka_common, version I/AkaSDKLogger: MPulseInternal mPulse initialized.

D/AkaSDKLogger: ComponentContainer: Initialized com.akamai.mpulse.android, version 20.32.47

  • Interception started:

D/AkaSDKLogger: AkaCommon: No external URL handler to handle http/s stream

OR

D/AkaSDKLogger: External Url Stream handler to handle http/s stream:: com.akamai.android.sdk.AkaMap

  • Config requested

D/AkaSDKLogger: MPConfig Config request to url: 'https://c.go-mpulse.net/api/config.json?key=...’ was successful.

D/AkaSDKLogger: MPConfig Response received: {"h.key":"

  • Analytics success

D/AkaSDKLogger: MPBatchTransport Successfully sent 1 record(s) to the server.

Failures

  • Wrong library

ERROR: Failed to resolve: com.akamai.android:aka-mpulse:21.*.*

Solution: Integration step is wrong. Add jcenter() in the project build.gradle

  • Missing config file reference

E/AkaSDKLogger: Couldn't find resource file for meta-data key com.akamai.android.sdk!

Solution: Check akamai_sdk_init.xml file is in res/xml and reference it  in the AndroidManifest.xml

Wrong key

E/AkaSDKLogger: AkaConfigHandler: getConfig with exception:java.io.FileNotFoundException:

E/AkaSDKLogger: AkaSyncController: sync: SDK is not active

Solution: Ensure that licenseKey is added in akamai_sdk_init.xml.