Adding the MobileFirst Foundation SDK to Ionic Applications

Overview

In this tutorial, you learn how to add the MobileFirst SDK to a new or existing Ionic application, created using Ionic CLI. You also learn how to configure the MobileFirst Server to recognise the application and to find information about the MobileFirst configuration files that are changed in the project.

The MobileFirst Ionic SDK is provided as a set of Typescript Wrappers along with the 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

Support levels

The Ionic Cordova platform versions supported by the MobileFirst plug-ins are:

• cordova-ios: >= 4.1.1 and < 5.0
• cordova-android: >= 6.1.2 and < 7.0
• cordova-windows: >= 4.3.2 and < 6.0

Jump to:

• Ionic SDK components
• Adding the MobileFirst Ionic SDK
• Updating the MobileFirst Ionic SDK
• Generated MobileFirst Ionic SDK artifacts
• Tutorials to follow next

Ionic 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:

• Ionic CLI 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 Visual Studio Tools for Universal Windows Apps, ensure that the cordova-windows applications created have all the required supporting libraries.

Adding the Mobile Foundation Ionic SDK

Follow the instructions below to add the Mobile Foundation Ionic SDK to a new or existing Ionic 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, then from a Command-line window, navigate to the server’s folder and run the command: ./run.sh.

Adding the SDK

Consider creating the project by using the MobileFirst Ionic application template. The template adds the necessary MobileFirst-specific plug-in entries to the Ionic 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 Ionic project: ionic start projectName starter-template.
   For example:

   ionic start Hello blank
   

   • “Hello” is the folder name and name of the application.
   • “blank” is the name of the starter template.

   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 Ionic project: cd hello

3. Add the MobileFirst Plugins by using the Ionic CLI command: ionic cordova plugin add cordova-plugin-name For example:

   ionic cordova plugin add cordova-plugin-mfp
   

   The above command adds MobileFirst Core SDK Plugin to the Ionic project.

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

   cordova platform add ios
   

5. Prepare the application resources by running the ionic cordova prepare command:

   ionic cordova prepare
   

Existing Application

Navigate to the root of your existing Ionic project and add the MobileFirst core Ionic Cordova plug-in:

   ionic cordova plugin add cordova-plugin-mfp

The MobileFirst API methods are available after the MobileFirst client SDK has been loaded. The mfjsloaded event is then called.

Registering the application

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

2. Register the application to MobileFirst Server:

   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, then updates the config.xml file at the root of the Ionic 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 mfjsloaded event is then called.
Call the various MobileFirst API methods only after event is called.

Updating the MobileFirst Ionic SDK

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

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

Generated MobileFirst Ionic SDK artifacts

config.xml

The Ionic configuration file is a mandatory XML file that contains application metadata, and is stored in the root directory of the app.
After the MobileFirst Ionic SDK is added to the project, the Ionic-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>

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