A Faster Hybrid App for the New Year

January 11, 2016By 1 Comment



In case you missed it, the official release of Cordova iOS 4.0.0 was announced in December (and subsequently 4.0.1). It’s important to emphasize it not only due to it being a major version change but due to the significant app performance benefits it enables. By updating your iOS apps to Cordova 4.x, you’re immediately eligible to take advantage of iOS’s nitro-powered WKWebView.

Prior to this version there was a way to do it (as noted in my post here), but it required some hoop jumping and was not without its caveats. Now however, we’re happy to promote this new version to help you easily take advantage of all the goodness the WKWebView has to offer.

In this post I’ll show you how to use this latest version in a new project and an existing project as well as help troubleshoot some things you may run into depending on your current environment. Much of the information here is available elsewhere too but it’s scattered between the Apache Cordova blog, JIRA issues and the Cordova docs so I decided to summarize it all in this post for a one stop reference.

Cordova and the WebView

As most of you may know, Cordova has always supported the iOS UIWebView by default, which was the only webview class available until iOS8 was released. Due to reasons discussed here, Cordova was unable to support the WKWebView fully and cleanly until this latest release. In Cordova 4.0.x, the UIWebView is still currently the default for backwards-compatibility reasons. But now using the pluggable webviews first implemented in cordova-android 4.0.0 with support for Crosswalk), it can easily be swapped to use the WKWebView instead by simply adding a plugin (cordova-plugin-wkwebview-engine).

Use in a New Project

Add the iOS platform with the latest keyword

$ cordova platform add ios@latest

You could also add a specific version using:

$ cordova platform add ios@4.0.1

Use in an Existing Project

Before updating an existing project to Cordova iOS 4+, you need to be sure to remove the existing iOS platform. Run the following commands to remove the previous iOS version and add the latest:

$ cordova platform remove ios
$ cordova platform add ios@latest
TROUBLESHOOTING: If you forget to remove the previous ios version you will get an error like the following upon build:

MainViewController.m:109:19: error: no visible @interface for ‘CDVViewController’ declares the selector ‘webViewDidFinishLoad:’ return [super webViewDidFinishLoad:theWebView];

ios-deploy version

Cordova iOS 4.0.0 is dependent on ios-deploy version 1.8.0 or greater. If you have anything less you will get an error like the following and will be asked to install the latest when you run your app.

ERROR running one or more of the platforms: Cordova needs ios-deploy version 1.8.0 or greater, you have version 1.7.0. Please download, build and install version 1.8.0 or greater from https://github.com/phonegap/ios-deploy into your path, or do 'npm install -g ios-deploy'

To fix it run:

$ npm install -g ios-deploy
TROUBLESHOOTING: If you receive an error like this after running the above:

2016-01-07 14:57:07.873 xcodebuild[32761:1714037] *** Assertion failure in -[SimServiceContext reloadServiceIfMovedOrAbortIfWeAreInvalid], /BuildRoot/Library/Caches/com.apple.xbs/Sources/CoreSimulator/CoreSimulator-201.3/CoreSimulator/SimServiceContext.m:453
** INTERNAL ERROR: Uncaught exception **
Exception: The loaded com.apple.CoreSimulator.CoreSimulatorService job does not match our expectations: versionOfLoadedJob: (null), our version: 201.3S

Visit this link and try running it with the following flags instead:

$ sudo npm install -g ios-deploy --unsafe-perm=true --allow-root

Use WKWebView

Once you get through installing all the latest Cordova iOS and ios-deploy versions, the last step is to add the WKWebView Engine plugin to ensure the faster webview is used for your app.

$ cordova plugin add cordova-plugin-wkwebview-engine --save

Once added, your app will automatically use it instead of the UIWebView by default when it runs and the plugin will be saved to the config.xml file.

Important Notes

  • Whitelist Plugin no longer needed – It’s included in cordova-ios 4.0.0 and greater automatically, but you’ll still need to set up your whitelist in the config.xml as described by the guide here.

    Also on a related note, iOS App Transport Security support is now added to the plist automatically for you by the CLI as of Cordova CLI version 5.4.0. The settings will be added to the .plist based on what you specified for your <allow-*> tags in the config.xml.

    For example, adding the following to your config.xml:

    <allow-navigation href="http://devgirl.org" />

    results in the following plist keys/values outlined in red below:


    or raw source values:

    NOTE: The NSAllowsArbitraryLoads key value is set to true in the above due to the config.xml setting for <access origin=”*”/>.
  • InAppBrowser Update – The InAppBrowser plugin was updated to support 4.0.0+ and is also backwards compatible with Cordova iOS 3+. If your project uses it, remove and add the latest with:
    $ cordova plugin remove cordova-plugin-inappbrowser
    $ cordova plugin add cordova-plugin-inappbrowser --save
  • iPhone 6s and iPhone 6s Plus Simulator targets – If you’re reading this soon after this post goes live, the support for the iPhone 6s and 6s Plus target in the simulator may not be supported yet even if it’s displayed in the list returned when you run the cordova run --list command. The fix will be in the next release, see this link for details.


Please feel free to comment here with any additional notes or troubleshooting tips you may have found helpful as well.

Filed in: CordovaMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (1)

Trackback URL | Comments RSS Feed

Sites That Link to this Post

  1. Updating and Reverting to Different Cordova PhoneGap Versions | | January 12, 2016

Leave a Reply