Adding the MobileFirst Foundation SDK to Android Applications

Overview

The IBM Mobile Foundation SDK consists of a collection of dependencies that are available through Maven Central, and which you can add to your Android Studio project. The dependencies correspond to core functions and other functions:

IBMMobileFirstPlatformFoundation - Implements client-to-server connectivity, handles authentication and security aspects, resource requests, and other required core functions.
IBMMobileFirstPlatformFoundationJSONStore - Contains the JSONStore framework. For more information, review the JSONStore for Andoid tutorial.
IBMMobileFirstPlatformFoundationPush - Contains the Push Notifications framework. For more information, review the Notifications tutorials.

In this tutorial, you learn how to add the MobileFirst Native SDK by using Gradle to a new or existing Android application. You also learn how to configure the MobileFirst Server to recognize the application, and to find information about the MobileFirst configuration files that are added to the project.

Prerequisites:

Android Studio and MobileFirst CLI installed on the developer workstation.
A local or remote instance of MobileFirst Server is running.
Read the Setting up your MobileFirst development environment and Setting up your Android development environment tutorials.

Adding the MobileFirst Native SDK

Follow the instructions below to add the MobileFirst Native SDK to a new or existing Android Studio project, and to register the application to the MobileFirst Server instance.

Before you start, make sure that MobileFirst Server is running.
If you use a locally installed server: From a Command-line window, navigate to the server’s folder and run the command ./run.sh on a Mac or Linux OS, or run.cmd on Windows.

Creating an Android application

Create an Android Studio project or use an existing one.

Adding the SDK

In Android → Gradle Scripts, select the build.gradle (Module: app) file.
Add the following lines after apply plugin: 'com.android.application':
```
repositories{
     jcenter()
}
```

Add the following line inside the android section:

packagingOptions {
     pickFirst 'META-INF/ASL2.0'
     pickFirst 'META-INF/LICENSE'
     pickFirst 'META-INF/NOTICE'
}

Add the following lines inside the dependencies section:
```
implementation group: 'com.ibm.mobile.foundation',
name: 'ibmmobilefirstplatformfoundation',
version: '8.0.+',
ext: 'aar',
transitive: true
```
Or on a single line:
```
implementation 'com.ibm.mobile.foundation:ibmmobilefirstplatformfoundation:8.0.+'
```
Note: If you are using Google Dynamic Delivery feature and would like to call MobileFirst APIs in a feature module then use api declaration instead of implementation. Using implementation would restrict using MobileFirst APIs in the same module itself while using api would make MobileFirst APIs available across all modules present in the app including feature modules. For more details read API and implementation separation.

   api 'com.ibm.mobile.foundation:ibmmobilefirstplatformfoundation:8.0.+'

In Android → app → manifests, open the AndroidManifest.xml file. Add the following permissions above the application element:

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

Add the MobileFirst UI activity next to the existing activity element:

<activity android:name="com.worklight.wlclient.ui.UIActivity" />

If a Gradle Sync request appears, accept it.

Manually adding the MobileFirst Native SDK

You can also manually add the MobileFirst SDK:

Click for instructions

To manually add the MobileFirst SDK, first download the SDK .zip file from the MobileFirst Operations Console → Download Center → SDKs tab. After completing the above steps, follow the below as well.

Extract the downloaded .zip file and place the relevant aar files to the app\libs folder.

Add the following to the dependencies closure:

compile(name:'ibmmobilefirstplatformfoundation', ext:'aar')
compile 'com.squareup.okhttp3:okhttp-urlconnection:3.4.1'   
compile 'com.squareup.okhttp3:okhttp:3.4.1'

Add the following to the repositories closure:

repositories {
    flatDir {
        dirs 'libs'
    }
}

Close section

Registering the application

Open a Command-line window and navigate to the root of the Android Studio project.
Run the command:
```
 mfpdev app register
```
- If a remote server is used, use the command mfpdev server add to add it.

The mfpdev app register CLI command first connects to the MobileFirst Server to register the application, followed by generating the mfpclient.properties file in the [project root]/app/src/main/assets/ folder of the Android Studio project, and to add to it the metadata that identifies the MobileFirst Server.

Tip: You can also register applications from the MobileFirst Operations Console:

Load the MobileFirst Operations Console.

Click the New button next to Applications to register a new application and follow the on-screen instructions.

After the application is registered, navigate to the application’s Configuration Files tab and copy or download the mfpclient.properties file. Follow the onscreen instructions to add the file to your project.

Creating a WLClient instance

Before using any MobileFirst APIs, create a WLClient instance:

WLClient.createInstance(this);

Note: Creating a WLClient instance should happen only once in the entire application lifecycle. It is recommended to use the Android Application class to do it.

Updating the MobileFirst Native SDK

To update the MobileFirst Native SDK with the latest release, find the release version number and update the version property accordingly in the build.gradle file.
See step 4 above.

SDK releases can be found in the SDK’s JCenter repository.

Generated MobileFirst Native SDK artifacts

mfpclient.properties

Located in the ./app/src/main/assets/ folder of the Android Studio project, this file defines the client-side properties used for registering your Android app on the MobileFirst Server.

Property	Description	Example values
wlServerProtocol	The communication protocol with the MobileFirst Server.	http or https
wlServerHost	The host name of the MobileFirst Server.	192.168.1.63
wlServerPort	The port of the MobileFirst Server.	9080
wlServerContext	The context root path of the application on the MobileFirst Server.	/mfp/
languagePreferences	Sets the default language for client sdk system messages.	en

Support for Javadoc and Android Service

For information about support for Javadoc and Android Service see the Additional Information page.

Tutorials to follow next

With the MobileFirst Native SDK now integrated, you can now:

Review the Using the Mobile Foundation SDK tutorials
Review the Adapters development tutorials
Review the Authentication and security tutorials
Review the Notifications tutorials
Review All Tutorials

▲

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.

Last modified on June 20, 2019