Persistent Mobile Foundation development in Cordova applications

Overview

From http://cordova.apache.org/:

Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies such as HTML5, CSS3, and JavaScript for cross-platform development, avoiding each mobile platforms’ native development language. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device’s sensors, data, and network status.

Persistent Mobile Foundation provides an SDK in the form of several Cordova plug-ins. Learn how to Add the PMF SDK to Cordova applications.

Note: Archive/IPA files generated using Test Flight or iTunes Connect for store submission/validation of iOS apps, might cause a runtime crash/fail.

Jump to:

• Cordova application development
• PMF APIs
• PMF SDK Startup Flow
• Cordova Application Security
• Cordova Application Resources
• Previewing an application’s web resources
• Implementing JavaScript Code
• CrossWalk support for Android
• WKWebView support for iOS
• Further reading
• Tutorials to follow next

Cordova application development

Applications developed with Cordova can be further enhanced by using the following Cordova-provided development paths and features:

Hooks

Cordova Hooks are scripts that provide developers with the ability to customize Cordova commands, enabling to create for example custom build flows.
Read more about Cordova Hooks.

Merges

The Merges folder provides the ability to have platform-specific web resources (HTML, CSS and JavaScript files). These web resources are then deployed during the cordova prepare step to the appropriate native directory. Files placed under the merges/ folder will override matching files in the www/ folder of the relevant platform. Read more about the Merges folder.

Cordova plug-ins

Using Cordova plug-ins can provide enhancements such as adding native UI elements (dialogs, tab bars, spinners and the like), as well as more advanced functionalities such as Mapping and Geolocation, loading of external content, custom keyboards, Device integration (camera, contacts, sensors, and so on).

You can find Cordova plug-ins on GitHub.com and in popular Cordova plug-ins websites, such as Plugreg and NPM.

Example plug-ins:

• cordova-plugin-dialogs
• cordova-plug-inprogress-indicator
• cordova-plugin-statusbar

Note: Modifying the default behaviour of a Cordova app (such as overriding the back button behavior) when the PMF Cordova SDK is added to the project, can lead to the app being rejected by Google Play Store when submitted. For other failures with submission to Google Play Store, you can contact Google support.

3rd-party frameworks

Cordova application development can be further enhanced by using frameworks such as Ionic, AngularJS, jQuery Mobile, Backbone and many others.

3rd-party packages

Applications can be modified using 3rd party packages to achieve requirements such as Minification & Concatenation of the application’s web resources and more. Popular packages to do so are:

• uglify-js
• clean-css

PMF APIs

After adding the PMF Cordova SDK to a Cordova application, the PMF set of API methods is now available for use.

For a complete list of available API methods, see the API Reference.

PMF SDK Startup Flow

public class MainActivity extends CordovaActivity implements WLInitWebFrameworkListener {

@Overridepublic void onCreate(Bundle savedInstanceState){
super.onCreate(savedInstanceState);

if (!((MFPApplication)this.getApplication()).hasCordovaSplashscreen()) {
           WL.getInstance().showSplashScreen(this);
       }
   init();
   WL.getInstance().initializeWebFramework(getApplicationContext(), this);
}

<activity android:name="com.ibm.MFPLoadUrlActivity" />

public void onInitWebFrameworkComplete(WLInitWebFrameworkResult result){
if (result.getStatusCode() == WLInitWebFrameworkResult.SUCCESS) {
super.loadUrl(WL.getInstance().getMainHtmlFilePath());
   } else {
      handleWebFrameworkInitFailure(result);
   }
}

[[WL sharedInstance] initializeWebFrameworkWithDelegate:self];

Cordova Application Security

Persistent Mobile Foundation provides security features that help you protect your Cordova apps.

Much of the content in a cross-platform app can be more easily modified by an unauthorized person than for a native app. Because much of the common content in a cross-platform app is in a readable format, Persistent Mobile Foundation provides features that can provide a higher level of security for your cross-platform Cordova apps.

Learn more about the PMF security framework

Use the following features to improve security on your Cordova apps:

• Encrypting the web resources of your Cordova packages
  Encrypts the contents in the www folder of your Cordova app, and decrypts it when the app is installed and run for the first time. This encryption makes it more difficult for someone to view or modify the content in that folder while the app is packaged.
• Enabling the web resources checksum feature
  Ensures the integrity of the app when it starts by comparing the contents to the baseline checksum results that were gathered the first time the app was started. This test helps prevent the modification of an app that is already installed.
• Enabling FIPS 140-2
  Ensures that the encryption algorithms that are used to encrypt data at rest and data in motion are compliant with the Federal Information Processing Standards (FIPS) 140-2 standard.
• Certificate Pinning
  Helps you prevent man-in-the-middle attacks by associating a host with its expected public key.

Cordova Application Resources

Certain resources are needed as part of the Cordova application. In most cases, they are generated for you when you create your Cordova app with your preferred Cordova development tools. If you use the PMF template, then splash screens and icons are also provided.

You can use a project template that is provided by IBM for use with Cordova projects that are enabled to use PMF features. If you use this PMF template, the following resources are made available to you as a starting point. If you do not use the PMF template, all of the resources are provided except splash screens and icons. You add the template by specifying the --template option and the PMF template when you initially create your Cordova project.

If you change the default file names and paths of any resources, you must also specify such changes in the Cordova configuration file (config.xml). In addition, in some cases, you can change the default names and paths with the pmfdev app config command. If you can change names and paths with the pmfdev app config command, it is noted in the section about the specific resource.

Cordova configuration file (config.xml)

The Cordova configuration file is a required XML file that contains application metadata and is stored in the root directory of the app. The file is automatically generated when you create a Cordova application. You can modify it to add custom properties by using the pmfdev app config command.

Main file (index.html)

This main file is an HTML5 file that contains the application skeleton. This file loads all the web resources (scripts and stylesheets) that are necessary to define the general components of the application and to hook to required document events. You can find this file in the your-project-name/www directory. You can change the name of this file with the pmfdev app config command.

Thumbnail image

The thumbnail image provides a graphical identification for the application on the PMF Operations Console. It must be a square image, preferably of size 90 by 90 pixels.
A default thumbnail image is provided when you use the template. You can override the default image by using the same file name with a replacement image. You can find thumbnail.png in the your-project-name/www/img folder. You can change the name or path of this file with the pmfdev app config command.

Splash image

The splash image is displayed while the application is being initialized. If you use the PMF default template, splash images are provided. These default images are stored in the following directories:

• iOS: /res/screen/ios/
• Android: /res/screen/android/

Various default splash images are included that are appropriate for different displays, and for iOS, different versions of the operating system. You can replace the default image that is provided by the template with your own splash image, or add an image if you did not use the template. When you use the PMF template to build your app for the Android platform, the cordova-plugin-splashscreen plug-in is installed. When this plug-in is integrated, the splash images that Cordova uses are displayed instead of the images that are used by PMF. The images in the folder with the screen.png format are the Cordova standard splash images. You can specify which splash images display by changing the settings in the Cordova config.xml file.

If you do not use the PMF template, the default splash images that are displayed are the images that are used by the PMF plug-in. The file names of the default PMF source splash images are in the form splash-string.9.png.

For more information about using your own splash images, see Adding custom splash screens and icons to Cordova apps.

Application icons

Default images for application icons are provided with the template. These default images are stored in the following directories:

• iOS: /res/icon/ios/
• Android: /res/icon/android/

You can replace the default image with your own image. Your custom application image must match the size of the default application image that you are replacing, and must use the same file name. Various default images are provided, appropriate to different displays and operating system versions.

For more information about using your own splash images, see Adding custom splash screens and icons to Cordova apps.

Stylesheets

The app code can include CSS files to define the application view.

The stylesheet files are located in the /www/css directory, and are copied to the following platform-specific folders:

• iOS: /platforms/ios/www/css
• Android: /platforms/android/assets/www/css

Scripts

Your app code can include JavaScript files that implement various functions of your app such as interactive user interface components, business logic, and back-end query integration.

The JavaScript file index.js is provided by the template, and is located in the your-project-name/www/js folder. This file is copied to the following platform-specific folders:

• iOS: /platforms/ios/www/js
• Android: /platforms/android/assets/www/js

Previewing an application’s web resources

A Cordova application’s web resources can be previewed either in the iOS Simulator, Android Emulator or physical devices. In PMF, two additional live-preview options are available: Persistent Mobile Foundation Mobile Browser Simulator and Simple Browser rendering.

Security Restriction: You can preview your web resources, however not all PMF JavaScript APIs are supported by the simulator. In particular, the OAuth protocol is not fully supported. However, you can test calls to adapters with WLResourceRequest. In this case,

• Security checks are not run on the server-side and security challenges are not sent to the client that runs in the Mobile Browser Simulator.
• If you do not use the PMF in a development environment , register a confidential client that has the adapter’s scope in its list of allowed scopes. You can define a confidential client with the PMF Operations Console, by using the Runtime/Settings menu. For more information about confidential clients, see Confidential clients.

Note: The PMF in a development environment includes a confidential client “test” that has an unlimited allowed scope (“*”). By default pmfdev app preview uses this confidential client.

Simple Browser

In Simple Browser previewing, the web resources of the application are being rendered in the desktop browser without being treated as an “app”, allowing easy debugging of just the web resources.

Mobile Browser Simulator

The Mobile Browser Simulator is a web application that enables testing of the Cordova application by simulating device features without needing to install the app in an Emulator or physical device.

Supported browsers:

• Firefox version 38 and later
• Chrome 49 and later
• Safari 9 and later

Previewing

1. From a Command-line window, run the command:

    pmfdev app preview
   

2. Select a preview option:

    ? Select how to preview your app: (Use arrow keys)
    ❯ browser: Simple browser rendering
    mbs: Mobile Browser Simulator
   

3. Select a platform to preview (only added platform will be displayed):

    ❯◯ android
    ◯ ios
   

Tip: Learn more about the various CLI commands in the Using CLI to manage PMF artifacts tutorial.

Live preview

Applicative code (HTML, CSS and JS) can now be edited in real-time with live-preview.
After making a change to a resource, save the change and it will be immediately reflected in the browser.

Live reload

To achieve a similar effect while previewing in physical devices or simulators/emulators, add the cordova-plugin-livereload plug-in. For usage instructions, see the plug-ins GitHub page.

Running the application on emulator or on a physical device

To emulate the application execute the Cordova CLI command cordova emulate ios|android. For example:

cordova emulate ios

To run the application on a physical device, attached to the development workstation a run the Cordova CLI command cordova run ios|android. For example:

cordova run ios

Implementing JavaScript Code

Editing the WebView resources is more convenient using an IDE that provides autocompletion for JavaScript.

Xcode, Android Studio, and Visual Studio provide full editing capabilities for editing Objective C, Swift, C#, and Java, however they may be limited in how they assist the editing of JavaScript. To facilitate JavaScript editing, the PMF Cordova project contains a defintion file for providing autocomplete for PMF API elements.

Each PMF Cordova plug-in provides a d.ts configuration file for each PMF JavaScript files. The d.ts file name matches the corresponding JavaScript file name and is located within the plug-in folder. For example for the main PMF SDK the file is here: [myapp]\plugins\cordova-plugin-mfp\typings\worklight.d.ts.

The d.ts configuration files provides autocomplete for all IDEs with TypeScript support: TypeScript Playground, Visual Studio Code, WebStorm, WebEssentials, Eclipse.

The resources (HTML and JavaScript files) for the WebView are located in the [myapp]\www folder. When the project is built with the cordova build command, or the cordova prepare command is run, these resources are copied to the corresponding www folder in the [myapp]\platforms\ios\www or [myapp]\platforms\android\assets\www folder.

When you open the main app folder with one of the previous IDEs, the context is preserved. The IDE editor will now be linked to the relevant d.ts files and autocomplete the PMF API elements as you type.

CrossWalk support for Android

Cordova applications for the Android platform can have their default WebView replaced with the CrossWalk WebView.

Note: The CrossWalk project is no longer being maintained by the community and its maintainers. Therefore, there are chances that bugs or issues in CrossWalk could affect the functioning of the Peristent Mobile Foundation SDKs in a CrossWalk WebView. It is therefore discouraged to use CrossWalk WebViews in your applications.

To add it:

1. From a Command-line line, run the command:

   cordova plugin add cordova-plugin-crosswalk-webview
   

   This command will add the CrossWalk WebView to the application.
   Behind the scenes, the PMF Cordova SDK will adjust the Android project activity for using it.

2. Build the project by running the command:

   cordova build
   

WKWebView support for iOS

The default UIWebView used in Cordova iOS applications can be replaced with Apple’s WKWebView.
To add, run the following command from a command-line window: cordova plugin add cordova-plugin-wkwebview-engine.

Learn more about the Cordova WKWebView plug-in.

Update: Using cordova-plugin-wkwebview-engine plugin in Cordova application throws error Cross origin requests are only supported for HTTP and results in direct update failure. To overcome this, your application will require an additional plugin called cordova-plugin-wkwebviewxhrfix. You can find the defect here.

Further reading

Learn more about Cordova:

• Cordova Overview
• Cordova best practices, testing, debugging, cosiderations and keeping up
• Get started with Cordova applications development

Tutorials to follow next

Get started by adding the Persistent Mobile Foundation SDK to your Cordova application, and review PMF-provided features in the All Tutorials section.