MobileFirst Foundation development in Cordova applications
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.
- Cordova application development
- MobileFirst APIs
- MobileFirst SDK Startup Flow
- Cordova Application Security
- Cordova Application Resources
- Previewing an application’s web resources
- 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:
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.
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.
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).
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.
Integration blog posts
- Best Practices for building AngularJS apps with MobileFirst Foundation 8.0
- Integrating Mobile Foundation in Ionic-based apps
- Integrating Mobile Foundation in Ionic 2 based apps
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:
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:
com.worklight.androidgap.api.WLAPI calls to perform the MobileFirst initialization.
- In the AndroidManifest.xml file adding
- An activity called
MFPLoadUrlActivityto allow proper MobileFirst initialization in case the cordova-plugin-crosswalk-webview has been installed.
- A custom attribute android:name="com.ibm.MFPApplication" to the
applicationelement (see below).
- An activity called
Implementing WLInitWebFrameworkListener and creating the WL object
The MainActivity.java file creates the initial
MainActivity class extending the
CordovaActivity class. The
WLInitWebFrameworkListener receives notification when the MobileFirst framework is initialized.
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.
MFPApplication class has two functions:
- Defines the
showSplashScreenmethod 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:
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
The MobileFirst framework is initialized in the iOS platform to display a WebView in the Cordova app with MobileFirst.AppDelegate.m
AppDelegate.m file is found in the Classes folder. This initializes the MobileFirst framework before the view controller loads the WebView.
didFinishLaunchingWithOptions method initializes the framework:
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.
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.
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:
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.
Default images for application icons are provided with the template. These default images are stored in the following directories:
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
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.
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.
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.
- Firefox version 38 and later
- Chrome 49 and later
- Safari 9 and later
From a Command-line window, run the command:
mfpdev app preview
Select a preview option:
? Select how to preview your app: (Use arrow keys) ❯ browser: Simple browser rendering mbs: Mobile Browser Simulator
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.
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.
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
Each MobileFirst Cordova plug-in provides a
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:
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.
Build the project by running the command:
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.
cordova-plugin-wkwebview-engineplugin 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.
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 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.