Adding the Persistent Mobile Foundation SDK to Ionic Applications

Overview

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

The PMF Ionic SDK is provided as a set of Typescript Wrappers along with the Cordova plug-ins and 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

Support levels

The Ionic Cordova platform versions supported by the Persistent Mobile Foundation plug-ins are:

cordova-ios: >= 4.1.1 and < 7.0
cordova-android: >= 6.1.2 and < 12.0

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

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

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

Before you start, make sure that the PMF 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 PMF Ionic application template. The template adds the necessary PMF-specific plug-in entries to the Ionic 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

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 PMF features as such Multilingual application translation and initialization options (see the user documentation for more information).
Change directory to the root of the Ionic project: cd hello
Add the Persistent Mobile Foundation Plugins by using the Ionic CLI command: ionic cordova plugin add cordova-plugin-name For example:
```
ionic cordova plugin add cordova-plugin-pmf
```
The above command adds Persistent Mobile Foundation Core SDK Plugin to the Ionic project.
Add one or more supported platforms to the Cordova project by using the Ionic CLI command: ionic cordova platform add ios|android|browser. For example:
```
cordova platform add ios
```
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 PMF core Ionic Cordova plug-in:

   ionic cordova plugin add cordova-plugin-pmf

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

Registering the application

Open a Command-line window and navigate to the root of the Ionic project.
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 Ionic 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:

Load the PMF Operations Console.

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 mfjsloaded event is then called.
Call the various PMF API methods only after event is called.

Updating the PMF Ionic SDK

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

Generated PMF 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 PMF 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 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>

Click for full list of config.xml properties

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 PMF, then the application must be registered again. xmlns:mfp: The PMF 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 `pmfdev 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 `pmfdev 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 PMF 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 PMF. url: The url value specifies the PMF protocol, host, and port values that the client will use to connect to the server by default. runtime: The runtime value specifies the PMF runtime to which the application was registered. For more information about the PMF runtime, see PMF overview.	The server url value is set with `the pmfdev app config server` command. The server runtime value is set with the `pmfdev app config runtime` command.
mfp:ios	This element contains all PMF-related client application configuration for the iOS platform. mfp:appChecksum mfp:sdkChecksum mfp:security
mfp:android	This element contains all PMF-related client application configuration for the Android platform. mfp:appChecksum mfp:sdkChecksum mfp:security
mfp:appChecksum	This value is the checksum of application web resources. It is calculated when `pmfdev app webupdate` is run.	Not user-configurable. The checksum value is updated when the `pmfdev app webupdate` command is run. For more details about the `pmfdev app webupdate` command, type `pmfdev help app webupdate` in your command window.
mfp:sdkChecksum	This value is the PMF Operations Console SDK checksum that is used to identify unique PMF SDK levels.	Not user-configurable. This value is set by default.
mfp:security	This element contains the client application's platform-specific configuration for PMF 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 `pmfdev app config android_security_test_web_resources_checksum key-value` command. The ignoreFileExtensions attribute is set with the `pmfdev app config android_security_ignore_file_extensions value` command.

Close section

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

Tutorials to follow next

With the PMF Ionic 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

▲

Last modified on