Adding the MobileFirst Foundation SDK to Cordova Applications

improve this page | report issue

Overview

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 < 5.0
  • cordova-android: >= 5.1.1 and < 6.0
  • cordova-windows: >= 4.3.2 and < 5.0

Jump to:

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:

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 and Main.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

  1. Create a Cordova project: cordova create projectName applicationId --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).

  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|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.

  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 MobileFirst core Cordova plug-in:

    cordova plugin add cordova-plugin-mfp
    
  2. Navigate to the www\js folder and select the index.js file.

  3. 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.

Registering the application

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

  2. Register the application to MobileFirst Server:

    mfpdev app register
    

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:

  1. Load the MobileFirst 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 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:
  • id: This is the application package name that was specified when the Cordova project was created. If this value is manually changed after the application was registered with the MobileFirst Server, then the application must be registered again.
  • xmlns:mfp: The MobileFirst plug-in XML namespace.
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.
  • url: The url value specifies the MobileFirst Server protocol, host, and port values that the client will use to connect to the server by default.
  • runtime: The runtime value specifies the MobileFirst Server runtime to which the application was registered. For more information about the MobileFirst runtime, see MobileFirst Server overview.
  • The server url value is set with the mfpdev app config server command.
  • The server runtime value is set with the mfpdev app config runtime command.
mfp:ios This element contains all MobileFirst-related client application configuration for the iOS platform.
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:android This element contains all MobileFirst-related client application configuration for the Android platform.
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:windows This element contains all MobileFirst-related client application configuration for the Windows platform.
  • mfp:appChecksum
  • mfp:windowsphone8
  • mfp:windows8
  • mfp:windows10
mfp:windows8 This element contains all MobileFirst-related client application configuration for Windows 8.1 platforms.
  • mfp:sdkChecksum
  • mfp:security
mfp:windows10 This element contains all MobileFirst-related client application configuration for Windows 10 platforms.
  • mfp:sdkChecksum
  • mfp:security
mfp:windowsphone8 This element contains all MobileFirst-related client application configuration for Windows Phone 8.1 platforms.
  • mfp:sdkChecksum
  • mfp:security
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
mfp:testWebResourcesChecksum Controls whether the application verifies the integrity of its web resources each time it starts running on the mobile device. Attributes:
  • enabled: Valid values are true and false. If this attribute is set to true, the application calculates the checksum of its web resources and compares this checksum with a value that was stored when the application was first run.
  • ignoreFileExtensions: Checksum calculation can take a few seconds, depending on the size of the web resources. To make it faster, you can provide a list of file extensions to be ignored in this calculation. This value is ignored when the enabled attribute value is false.
  • The enabled attribute is set with the mfpdev app config android_security_test_web_resources_checksum key-value command.
  • The ignoreFileExtensions attribute is set with the mfpdev app config android_security_ignore_file_extensions value command.

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

Tutorials to follow next

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

Last modified on January 30, 2017