Adding the Persistent Mobile Foundation SDK to Cordova Applications

Overview

In this tutorial, you learn how to add the PMF 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 PMF to recognize the application, and to find information about the PMF configuration files that are changed in the project.

The PMF Cordova SDK is provided as a set of Cordova plug-ins, these plugins can be downloaded at CordovaSDK.
Available plug-ins are:

• cordova-plugin-pmf - The core SDK plug-in
• cordova-plugin-pmf-push - Provides push notifications support
• cordova-plugin-pmf-jsonstore - Provides JSONStore support
• cordova-plugin-pmf-fips - Android only. Provides FIPS support
• cordova-plugin-pmf-encrypt-utils - iOS only. Provides support for encryption and decryption

Support levels

The Cordova platform versions supported by the PMF plug-ins, are:

• cordova-ios: >= 4.1.1 and <= 7.0.1
• cordova-android: >= 6.1.2 and <= 12.x

Jump to:

• Cordova SDK components
• Adding the PMF Cordova SDK
• Updating the PMF Cordova SDK
• Generated PMF 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 15. You need to enable this capability manually before building the Xcode project.

Cordova SDK components

cordova-plugin-pmf

The cordova-plugin-pmf plug-in is the core PMF plug-in for Cordova, and is required. If you install any of the other PMF plug-ins, the cordova-plugin-pmf plug-in is automatically installed, too, if not already installed.

The following Cordova plug-ins are installed as dependencies of cordova-plugin-pmf:

• cordova-plugin-device
• cordova-plugin-dialogs
• cordova-plugin-globalization
• cordova-plugin-okhttp

cordova-plugin-pmf-jsonstore

The cordova-plugin-pmf-jsonstore plug-in enables your app to use JSONstore. For more information about JSONstore, see the JSONStore tutorial.

cordova-plugin-pmf-push

The cordova-plugin-pmf-push plug-in provides permissions that are necessary to use push notification from the PMF for Android applications. Additional setup for using push notification is required. For more information about push notification, see the Push notifications tutorial.

cordova-plugin-pmf-fips

The cordova-plugin-pmf-fips plug-in provides FIPS 140-2 support for the Android platform. For more information, see FIPS 140-2 support.

cordova-plugin-pmf-encrypt-utils

The cordova-plugin-pmf-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 PMF CLI installed on the developer workstation.
• A local or remote instance of PMF is running.
• Read the Setting up your PMF development environment and Setting up your Cordova development environment tutorials.

Adding the PMF Cordova SDK

Follow the instructions below to add the PMF Cordova SDK to a new or existing Cordova project, and register it in the PMF.

Before you start, make sure that the PMF 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 and Main.m file for iOS.

Adding the SDK

Consider creating the project by using the PMF Cordova application template. The template adds the necessary PMF-specific plug-in entries to the Cordova project’s config.xml file, and provides a PMF-specific, ready-to-use, index.js file that is adjusted for PMF application development.

New Application

1. 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 PMF-specific additions.

   The templated index.js enables you to use additional PMF features as such Multilingual application translation and initialization options (see the user documentation for more information).

2. Change directory to the root of the Cordova project: cd hello

3. Add one or more supported platforms to the Cordova project by using the Cordova CLI command: cordova platform add ios|android. For example:

   cordova platform add ios
   

   Note: Because the application was configured using the PMF template, the PMF core Cordova plug-in is added automatically as the platform is added in step 3.

4. Prepare the application resources by running the cordova prepare command:

   cordova prepare
   

Existing Application

1. Navigate to the root of your existing Cordova project and add the PMF core Cordova plug-in:

   cordova plugin add cordova-plugin-pmf
   

2. Navigate to the www\js folder and select the index.js file.

3. Add the following function:

   function wlCommonInit() {
   
   }
   

The PMF API methods are available after the PMF client SDK has been loaded. The wlCommonInit function is then called.
Use this function to call the various PMF API methods.

Manually adding SDK

We also have an option to install the plugin from local path. cordova-plugin-pmf can be downloaded from our PMF console and install it in cordova application .

1. In PMF server console Dashboard ,Click on Download Center => Click on SDKs tab => Download the Cordova SDK .

2. Navigate to the root of your existing Cordova project and add the PMF core Cordova plug-in:

   cordova plugin add [path-to downloaded pmf cordova plugin]/cordova-plugin-pmf
   

Registering the application

1. Open a Command-line window and navigate to the root of the Cordova project.

2. Register the application to PMF:

   pmfdev app register
   

   • If a remote server is used, use the command pmfdev server add to add it.

The pmfdev app register CLI command first connects to the PMF to register the application, then updates the config.xml file at the root of the Cordova project with metadata that identifies the PMF.

Each platform is registered as an application in PMF.

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

1. Load the PMF Operations Console.
2. Click the New button next to Applications to register a new application and follow the on-screen instructions.

Using the SDK

The PMF API methods are available after the PMF client SDK has been loaded. The wlCommonInit function is then called.
Use this function to call the various PMF API methods.

Updating the PMF Cordova SDK

To update the PMF Cordova SDK with the latest release, remove the cordova-plugin-pmf plug-in: run the cordova plugin remove cordova-plugin-pmf command and then run the cordova plugin add cordova-plugin-pmf command to add it again.

Generated PMF 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 PMF 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 PMF features and the PMF.

example of PMF 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-pmf">
    <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:platformVersion>9.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>

Editing PMF settings in the config.xml file

You can use the PMF CLI to edit the above settings by running the command:

pmfdev app config

Cordova Browser Platform support

Persistent Mobile Foundation now supports the Cordova Browser platform along with the other supported platforms of Cordova Android, and Cordova iOS.

The use of Cordova Browser platform with Persistent Mobile Foundation (PMF) is similar to using PMF 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 PMF plugin using the following command:

cordova plugin add cordova-plugin-pmf

Add a button that can be used to ping your PMF server(the server could be your locally hosted server). Ping your PMF 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>PMF Starter - Cordova</title>
</head>

<body>

  <div id="main">
    <div id="main_title">Hello PMF</div>
    <div id="main_status"></div>
    <div id="main_info"></div>
  </div>

  <div id="button_content">
    <button id="ping_button" style="display:none">Ping PMF 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 Persistent Mobile Foundation Knowledge Center.
   mfpContextRoot : '/mfp', // "mfp" is the default context root in the Mobile Foundation 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 PMF";
    statusText.innerHTML = "Connecting to Server...";
    infoText.innerHTML = "";

    WLAuthorizationManager.obtainAccessToken()
      .then(
        function (accessToken) {
          titleText.innerHTML = "Yay!";
          statusText.innerHTML = "Connected to PMF Server";
        },
        function (error) {
          titleText.innerHTML = "Bummer...";
          statusText.innerHTML = "Failed to connect to PMF Server";
        }
        );
    },
 }

Note: It is important to mention the mfpContextRoot and applicationId 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 PMF 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: pmfdev-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 PMF server. The cordova browser’s default proxy server(that runs on port 8000) has been suppressed as it cannot connect to the PMF 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:

pmfdev 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 PMF Cordova SDK now integrated, you can now:

• Review the Using the PMF SDK tutorials
• Review the Adapters development tutorials
• Review the Authentication and security tutorials
• Review the Notifications tutorials
• Review All Tutorials