MobileFirst Foundation development in Cordova applications

improve this page | report issue



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.

IBM Mobile Foundation provides an SDK in the form of several Cordova plug-ins. Learn how to Add the Mobile Foundation 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, read the blog Preparing iOS apps for App Store submission in IBM Mobile Foundation, to know more.

Jump to:

Cordova application development

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


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.


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 and in popular Cordova plug-ins websites, such as Plugreg and NPM.

Example plug-ins:

Note: Modifying the default behaviour of a Cordova app (such as overriding the back button behavior) when the MobileFirst 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.

Integration blog posts

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:

MobileFirst APIs

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

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

MobileFirst SDK Startup Flow

In Android Studio, you can review the start-up process of the Cordova app for Android with MobileFirst. The MobileFirst Cordova plug-in, cordova-plugin-mfp, has native asynchronous bootstrap sequence. The bootstrap sequence must be completed before the Cordova application loads the application's main html file.

Adding the cordova-plugin-mfp plug-in to a Cordova application instruments the application's AndroidManifest.xml file and the MainActivity file (which extends CordovaActivity) native code to perform the MobileFirst initialization.

The application native code instrumentation consists of:

  • Adding com.worklight.androidgap.api.WL API calls to perform the MobileFirst initialization.
  • In the AndroidManifest.xml file adding
    • An activity called MFPLoadUrlActivity to allow proper MobileFirst initialization in case the cordova-plugin-crosswalk-webview has been installed.
    • A custom attribute android:name="" to the application element (see below).

Implementing WLInitWebFrameworkListener and creating the WL object

The file creates the initial MainActivity class extending the CordovaActivity class. The WLInitWebFrameworkListener receives notification when the MobileFirst framework is initialized.

public class MainActivity extends CordovaActivity implements WLInitWebFrameworkListener {

The MFPApplication class is called from within onCreate and creates a MobileFirst client instance (com.worklight.androidgap.api.WL) that is used throughout the app. The onCreate method initializes the WebView framework.

@Overridepublic void onCreate(Bundle savedInstanceState){

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

The MFPApplication class has two functions:

  • Defines the showSplashScreen method for loading a splash screen if one exists.
  • Creates two listeners for enabling analytics. These listeners can be removed if not needed.

Loading the WebView

The cordova-plugin-mfp plug-in adds an activity to the AndroidManifest.xml file that is required for initializing the Crosswalks WebView:

<activity android:name="" />

This activity is used to ensure the asynchronous initialization of the Crosswalk WebView as follows:

After the MobileFirst framework is initialized and ready to load in the WebView, the onInitWebFrameworkComplete connects to the URL if WLInitWebFrameworkResult succeeds.

public void onInitWebFrameworkComplete(WLInitWebFrameworkResult result){
if (result.getStatusCode() == WLInitWebFrameworkResult.SUCCESS) {
   } else {

The MobileFirst framework is initialized in the iOS platform to display a WebView in the Cordova app with MobileFirst.


The AppDelegate.m file is found in the Classes folder. This initializes the MobileFirst framework before the view controller loads the WebView.

The didFinishLaunchingWithOptions method initializes the framework:

[[WL sharedInstance] initializeWebFrameworkWithDelegate:self];

Once the initialization succeeds the wlInitWebFrameworkDidCompleteWithResult checks that the MobileFirst framework has been loaded and creates a MainViewController that connects to the default index.html page.

Once the iOS Cordova app is built in Xcode without errors, you can proceed to add features to the native platform and WebView.

The MobileFirst Cordova plug-in, cordova-plugin-mfp has native asynchronous bootstrap sequence. The bootstrap sequence must be completed before the Cordova application loads the application's main HTML file.

Adding the cordova-plugin-mfp plug-in to a Cordova application adds the index.html file to the application's appxmanifest file. This extends the CordovaActivity native code to perform the MobileFirst initialization.

Cordova Application Security

IBM 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, IBM MobileFirst Foundation provides features that can provide a higher level of security for your cross-platform Cordova apps.

Learn more about the MobileFirst 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 Mobile Foundation 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 MobileFirst features. If you use this MobileFirst template, the following resources are made available to you as a starting point. If you do not use the MobileFirst template, all of the resources are provided except splash screens and icons. You add the template by specifying the --template option and the MobileFirst 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 mfpdev app config command. If you can change names and paths with the mfpdev 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 mfpdev 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 mfpdev app config command.

Thumbnail image

The thumbnail image provides a graphical identification for the application on the MobileFirst 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 mfpdev app config command.

Splash image

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

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

Various default splash images are included that are appropriate for different displays, and for iOS and Windows, 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 MobileFirst 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 Mobile Foundation. 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 MobileFirst template, the default splash images that are displayed are the images that are used by the Mobile Foundation plug-in. The file names of the default MobileFirst 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/
  • Windows: /res/icon/windows/

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.


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
  • Windows: /platforms/windows/www/css


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
  • Windows: /platforms/windows/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, Windows Emulator, or physical devices. In Mobile Foundation, two additional live-preview options are available: IBM MobileFirst Foundation Mobile Browser Simulator and Simple Browser rendering.

Security Restriction: You can preview your web resources, however not all MobileFirst 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 MobileFirst Server 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 MobileFirst Operations Console, by using the Runtime/Settings menu. For more information about confidential clients, see Confidential clients.

Note: The MobileFirst Server in a development environment includes a confidential client “test” that has an unlimited allowed scope (“*”). By default mfpdev 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


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

     mfpdev 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 MobileFirst 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|windows. 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|windows. 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 MobileFirst Cordova project contains a defintion file for providing autocomplete for MobileFirst API elements.

Each MobileFirst Cordova plug-in provides a d.ts configuration file for each MobileFirst 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 MobileFirst 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, [myapp]\platforms\android\assets\www, or [myapp]\platforms\windows\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 MobileFirst 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 MobileFirst 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 MobileFirst 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:

Tutorials to follow next

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

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on January 08, 2020