Adding the MobileFirst Foundation SDK to Android Applications
improve this page | report issueOverview
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.
Jump to:
- Adding the MobileFirst Native SDK
- Manually Adding the MobileFirst Native SDK
- Updating the MobileFirst Native SDK
- Generated MobileFirst Native SDK artifacts
- Support for Javadoc and Android Service
- Tutorials to follow next
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 ofimplementation
. Usingimplementation
would restrict using MobileFirst APIs in the same module itself while usingapi
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:
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.
- If a remote server is used, use the command
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.