Adding the MobileFirst Foundation SDK to Cordova Applications
improve this page | report issueOverview
In this tutorial, you learn how to add the MobileFirst SDK to a new or existing Cordova application that has been created with Apache Cordova, Ionic, or another thirdy-party tool. You also learn how to configure the MobileFirst Server to recognize the application, and to find information about the MobileFirst configuration files that are changed in the project.
The MobileFirst Cordova SDK is provided as a set of Cordova plug-ins, and is registered at NPM.
Available plug-ins are:
- cordova-plugin-mfp - The core SDK plug-in
- cordova-plugin-mfp-push - Provides push notifications support
- cordova-plugin-mfp-jsonstore - Provides JSONStore support
- cordova-plugin-mfp-fips - Android only. Provides FIPS support
- cordova-plugin-mfp-encrypt-utils - iOS only. Provides support for encryption and decryption
Support levels
The Cordova platform versions supported by the MobileFirst plug-ins, are:
- cordova-ios: >= 4.1.1 and < 7.0
- cordova-android: >= 6.1.2 and < 11.0
- cordova-windows: >= 5.0.0 and < 8.0
Note: The cordova-windows latest published version has a bug, which will throw an exception during app launch. Apache Cordova has fixed the issue in the development repository but it is not published yet. It is recommended to use the cordova-windows version from the main repository that contains the fix. Below is the command that can be used to add the cordova-windows platform to have the fix in place.
cordova platform add https://github.com/apache/cordova-windows
Jump to:
- Cordova SDK components
- Adding the MobileFirst Cordova SDK
- Updating the MobileFirst Cordova SDK
- Generated MobileFirst Cordova SDK artifacts
- Cordova browser platform support
- Tutorials to follow next
Note: The Keychain Sharing capability is mandatory while running iOS apps in the iOS Simulator when using Xcode 8. You need to enable this capability manually before building the Xcode project.
Cordova SDK components
cordova-plugin-mfp
The cordova-plugin-mfp plug-in is the core MobileFirst plug-in for Cordova, and is required. If you install any of the other MobileFirst plug-ins, the cordova-plugin-mfp plug-in is automatically installed, too, if not already installed.
The following Cordova plug-ins are installed as dependencies of cordova-plugin-mfp:
- cordova-plugin-device
- cordova-plugin-dialogs
- cordova-plugin-globalization
- cordova-plugin-okhttp
cordova-plugin-mfp-jsonstore
The cordova-plugin-mfp-jsonstore plug-in enables your app to use JSONstore. For more information about JSONstore, see the JSONStore tutorial.
cordova-plugin-mfp-push
The cordova-plugin-mfp-push plug-in provides permissions that are necessary to use push notification from the MobileFirst Server for Android applications. Additional setup for using push notification is required. For more information about push notification, see the Push notifications tutorial.
cordova-plugin-mfp-fips
The cordova-plugin-mfp-fips plug-in provides FIPS 140-2 support for the Android platform. For more information, see FIPS 140-2 support.
cordova-plugin-mfp-encrypt-utils
The cordova-plugin-mfp-encrypt-utils plug-in provides iOS OpenSSL frameworks for encryption for Cordova applications with the iOS platform. For more information, see Enabling OpenSSL for Cordova iOS.
Prerequisites:
- Apache Cordova CLI(>=6.x and <11.0) 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 Cordova development environment tutorials.
- For cordova-windows, a version of Visual C++ that is compatible to the Visual Studio and .NET versions installed in the machine have to be installed.
- In case of Windows Phone SDK 8.0 and Visual Studio Tools for Universal Windows Apps, ensure that the cordova-windows applications created have all the required supporting libraries.
Adding the Mobile Foundation Cordova SDK
Follow the instructions below to add the Mobile Foundation Cordova SDK to a new or existing Cordova project, and register it in the MobileFirst Server.
Before you start, make sure that the MobileFirst Server is running.
If using a locally installed server: From a Command-line window, navigate to the server’s folder and run the command: ./run.sh
.
Note: If you are adding the SDK to an existing Cordova application, the plug-in overwrites the
MainActivity.java
file for Android andMain.m
file for iOS.
Adding the SDK
Consider creating the project by using the MobileFirst Cordova application template. The template adds the necessary MobileFirst-specific plug-in entries to the Cordova project’s config.xml file, and provides a MobileFirst-specific, ready-to-use, index.js file that is adjusted for MobileFirst application development.
New Application
-
Create a Cordova project:
cordova create projectName applicationId applicationName --template cordova-template-mfp
.
For example:cordova create Hello com.example.helloworld HelloWorld --template cordova-template-mfp
- “Hello” is the folder name of the application.
- “com.example.helloworld” is the ID of the application.
- “HelloWorld” is the Name of the application.
- –template modifies the application with MobileFirst-specific additions.
The templated index.js enables you to use additional MobileFirst features as such Multilingual application translation and initialization options (see the user documentation for more information).
-
Change directory to the root of the Cordova project:
cd hello
-
Add one or more supported platforms to the Cordova project by using the Cordova CLI command:
cordova platform add ios|android|windows
. For example:cordova platform add ios
Note: Because the application was configured using the MobileFirst template, the MobileFirst core Cordova plug-in is added automatically as the platform is added in step 3.
-
Prepare the application resources by running the
cordova prepare command
:cordova prepare
Existing Application
-
Navigate to the root of your existing Cordova project and add the MobileFirst core Cordova plug-in:
cordova plugin add cordova-plugin-mfp
-
Navigate to the www\js folder and select the index.js file.
-
Add the following function:
function wlCommonInit() { }
The MobileFirst API methods are available after the MobileFirst client SDK has been loaded. The wlCommonInit
function is then called.
Use this function to call the various MobileFirst API methods.
Manually adding SDK
We also have an option to install the plugin from local path. cordova-plugin-mfp can be downloaded from our MFP console and install it in cordova application .
-
In MFP server console Dashboard ,Click on Download Center => Click on SDKs tab => Download the cordova SDK .
-
Navigate to the root of your existing Cordova project and add the MobileFirst core Cordova plug-in:
cordova plugin add [path-to downloaded mfp cordova plugin]/mfp-cordova/plugins/cordova-plugin-mfp
Registering the application
-
Open a Command-line window and navigate to the root of the Cordova project.
-
Register the application to MobileFirst Server:
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, then updates the config.xml file at the root of the Cordova project with metadata that identifies the MobileFirst Server.
Each platform is registered as an application in 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.
Using the SDK
The MobileFirst API methods are available after the MobileFirst client SDK has been loaded. The wlCommonInit
function is then called.
Use this function to call the various MobileFirst API methods.
Updating the MobileFirst Cordova SDK
To update the MobileFirst Cordova SDK with the latest release, remove the cordova-plugin-mfp plug-in: run the cordova plugin remove cordova-plugin-mfp
command and then run the cordova plugin add cordova-plugin-mfp
command to add it again.
SDK releases can be found in the SDK’s NPM repository.
Generated MobileFirst Cordova SDK artifacts
config.xml
The Cordova configuration file is a mandatory XML file that contains application metadata, and is stored in the root directory of the app.
After the MobileFirst Cordova SDK is added to the project, the Cordova-generated config.xml file receives a set of new elements that are identified with the namespace mfp:
. The added elements contain information related to MobileFirst features and the MobileFirst Server.
example of MobileFirst settings added to the config.xml file
<?xml version='1.0'encoding='utf-8'?>
<widget id="..." xmlns:mfp="http://www.ibm.com/mobilefirst/cordova-plugin-mfp">
<mfp:android>
<mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
<mfp:appChecksum>0</mfp:appChecksum>
<mfp:security>
<mfp:testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3" />
</mfp:security>
</mfp:android>
<mfp:windows>
<mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
<mfp:windows10>
<mfp:sdkChecksum>...</mfp:sdkChecksum>
<mfp:security>
<mfp:testWebResourcesChecksum/>
</mfp:security>
</mfp:windows>
<mfp:platformVersion>8.0.0.00-20151214-1255</mfp:platformVersion>
<mfp:clientCustomInit enabled="false" />
<mfp:server runtime="mfp" url="http://10.0.0.1:9080" />
<mfp:directUpdateAuthenticityPublicKey>the-key</mfp:directUpdateAuthenticityPublicKey>
<mfp:languagePreferences>en</mfp:languagePreferences>
</widget>
Element | Description | Configuration |
widget | Root element of the config.xml document. The element contains two required attributes:
|
|
mfp:platformVersion | Required. The product version on which the application was developed. | Set by default. Must not be changed. |
mfp:directUpdateAuthenticityPublicKey | Optional. When you enable the Direct Update Authenticity feature, the direct update package is digitally signed during deployment. After the client downloaded the package, a security check is run to validate the package authenticity. This string value is the public key that will be used to authenticate the direct update .zip file. | Set with the mfpdev app config direct_update_authenticity_public_key key-value command. |
mfp:languagePreferences | Optional. Contains a comma-separated list of locales to display system messages. | Set with the mfpdev app config language_preferences key-value command. |
mfp:clientCustomInit | Controls how the WL.Client.init method is called. By default, this value is set to false and the WL.Client.init method is automatically called after the MobileFirst plug-in is initialized. Set this value to true for the client code to explicitly control when WL.Client.init is called. |
Edited manually. You can set the enabled attribute value to either true or false. |
mfp:server | Default remote server connection information, which the client application uses to communicate with the MobileFirst Server.
|
|
mfp:ios | This element contains all MobileFirst-related client application configuration for the iOS platform.
|
|
mfp:android | This element contains all MobileFirst-related client application configuration for the Android platform.
|
|
mfp:windows | This element contains all MobileFirst-related client application configuration for the Windows platform.
|
|
mfp:windows8 | This element contains all MobileFirst-related client application configuration for Windows 8.1 platforms.
|
|
mfp:windows10 | This element contains all MobileFirst-related client application configuration for Windows 10 platforms.
|
|
mfp:windowsphone8 | This element contains all MobileFirst-related client application configuration for Windows Phone 8.1 platforms.
|
|
mfp:appChecksum | This value is the checksum of application web resources. It is calculated when mfpdev app webupdate is run. |
Not user-configurable. The checksum value is updated when the mfpdev app webupdate command is run. For more details about the mfpdev app webupdate command, type mfpdev help app webupdate in your command window. |
mfp:sdkChecksum | This value is the MobileFirst Operations Console SDK checksum that is used to identify unique MobileFirst SDK levels. | Not user-configurable. This value is set by default. |
mfp:security | This element contains the client application's platform-specific configuration for MobileFirst security. Contains
|
|
mfp:testWebResourcesChecksum | Controls whether the application verifies the integrity of its web resources each time it starts running on the mobile device. Attributes:
|
|
Close section
Editing MobileFirst settings in the config.xml file
You can use the MobileFirst CLI to edit the above settings by running the command:
mfpdev app config
Cordova Browser Platform support
MobileFirst Platform now supports the Cordova Browser platform along with the other supported platforms of Cordova Windows, Cordova Android, and Cordova iOS.
The use of Cordova Browser platform with MobileFirst Platform (MFP) is similar to using MFP with any of the other platforms. A sample to illustrate this feature is explained below.
Create a cordova application using the following command:
cordova create <your-appFolder-name> <package-name>
This will create a vanilla cordova app.
Add the MFP plugin using the following command:
cordova plugin add cordova-plugin-mfp
Add a button that can be used to ping your MFP server(the server could be your locally hosted server or server on IBM Cloud). Ping your MFP server on click of the button. You can use the sample code below:
index.html
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
<meta name="format-detection" content="telephone=no">
<meta name="msapplication-tap-highlight" content="no">
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
<link rel="stylesheet" type="text/css" href="css/index.css" />
<!-- load script with wlCommonInit defined before loading cordova.js -->
<script type="text/javascript" src="js/index.js"></script>
<script type="text/javascript" src="cordova.js"></script>
<title>MFP Starter - Cordova</title>
</head>
<body>
<div id="main">
<div id="main_title">Hello MobileFirst</div>
<div id="main_status"></div>
<div id="main_info"></div>
</div>
<div id="button_content">
<button id="ping_button" style="display:none">Ping MobileFirst Server</button>
</div>
</body>
</html>
index.js
var Messages = {
// Add here your messages for the default language.
// Generate a similar file with a language suffix containing the translated messages.
// key1 : message1,
};
var wlInitOptions = {
// Options to initialize with the WL.Client object.
// For initialization options please refer to IBM MobileFirst Platform Foundation Knowledge Center.
mfpContextRoot : '/mfp', // "mfp" is the default context root in the MobileFirst Development server
applicationId : 'io.cordova.hellocordova' // Replace with your own app id/package name.
};
function wlCommonInit() {
app.init();
}
var app = {
//initialize app
"init": function init() {
var buttonElement = document.getElementById("ping_button");
buttonElement.style.display = "block";
buttonElement.addEventListener('click', app.testServerConnection, false);
},
//test server connection
"testServerConnection": function testServerConnection() {
var titleText = document.getElementById("main_title");
var statusText = document.getElementById("main_status");
var infoText = document.getElementById("main_info");
titleText.innerHTML = "Hello MobileFirst";
statusText.innerHTML = "Connecting to Server...";
infoText.innerHTML = "";
WLAuthorizationManager.obtainAccessToken()
.then(
function (accessToken) {
titleText.innerHTML = "Yay!";
statusText.innerHTML = "Connected to MobileFirst Server";
},
function (error) {
titleText.innerHTML = "Bummer...";
statusText.innerHTML = "Failed to connect to MobileFirst Server";
}
);
},
}
Note: It is important to mention the
mfpContextRoot
andapplicationId
in the wlInitOptions in index.js file.
index.css
body {
position: static;
font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif;
font-weight: 300;
margin: 0px;
padding: 0px;
}
#button_content {
position: absolute;
bottom: 10%;
width: 100%;
}
#ping_button {
display: block;
margin: 0 auto;
height: 50px;
width: 240px;
font-size: 20px;
color: white;
background-color: #325c80;
}
#main {
top: 10%;
position: absolute;
text-align: center;
width: 100%
}
#main_title {
font-size: 40px;
}
#main_status {
font-size: 20px;
margin-top: 10px;
}
#main_info {
font-size: 14px;
margin-top: 10px;
}
Add the browser platform using the following command:
cordova platform add browser
To manually register your application:
- Login to your MFP server’s console.
- Click the New button next to the *Applications* option.
- Provide a name to your application, select Web as the platform and provide your application’s id (which was defined in the wlInitOptions function of your
index.js
).Remember: Add the server details to the
config.xml
of your application.
Note: mfpdev-cli to register browser platform app will be released soon.
Then execute the following commands:
cordova prepare
cordova build
cordova run
This launches a browser that runs on a proxy server (on port 9081
) and connects to the MFP server. The cordova browser’s default proxy server(that runs on port 8000
) has been suppressed as it cannot connect to the MFP server due to the same-origin-policy.
The default browser to run is set to Chrome. Use the
--target
option to run on different browsers and can be used using the following command:cordova run --target=Firefox
The app can be previewed using the command:
mfpdev app preview
The only supported browser option is Simple Browser Rendering. The option Mobile Browser Support is not supported for the browser platform.
Using WebSphere Liberty to serve cordova browser resources
Follow the instruction to use WebSphere Liberty in this tutorial and make the below changes.
Add the contents of your browser project’s www
folder to [MyWebApp] → src → Main → webapp
as mentioned in Step 1 of Building the Maven webapp with the web application’s resources section of this tutorial. Finally, register your app on your Liberty server and test it by running it in the browser with the path localhost:9080/MyWebApp
. Also add the sjcl
and jssha
folders to their parent folder and change their reference in the ibmmfpf.js
file.
Tutorials to follow next
With the MobileFirst Cordova 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.