Background
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
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 http://ift.tt/1i0fD0H into your path, or do 'npm install -g ios-deploy'
To fix it run:
$ npm install -g ios-deploy
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:
<key>NSAppTransportSecurity</key> <dict> <key>NSExceptionDomains</key> <dict> <key>devgirl.org</key> <dict> <key>NSExceptionAllowsInsecureHTTPLoads</key> <true/> </dict> </dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict> - 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 --listcommand. The fix will be in the next release, see this link for details.
Feedback
Please feel free to comment here with any additional notes or troubleshooting tips you may have found helpful as well.
by Holly Schinsky via Devgirl's Weblog
