Alpha WKWebView Engine Plugin

Description

This plugin allows you to use the enhanced Alpha WKWebView within an iOS Cordova App

Discussion

The UIWebView was deprecated in iOS 8 (over 6 years ago) and has been replaced by the WKWebView class.

The Apple developer documentation includes this note on the UIWebView class: "Deprecated: In apps that run in iOS 8 and later, use the WKWebView class instead of using UIWebView."

A note on deprecations from developer.apple.com

"Periodically, Apple adds deprecation macros to APIs to indicate that those APIs should no longer be used in active development. When a deprecation occurs, it’s not an immediate end of life for the specified API. Instead, it is the beginning of a grace period for transitioning from that API and to newer and more modern replacements. Deprecated APIs typically remain present and usable in the system for a reasonable time past the release in which they were deprecated. However, active development on them ceases, and the APIs receive only minor changes to accommodate security patches or to fix other critical bugs. Deprecated APIs may be removed entirely from a future version of the operating system. As a developer, avoid using deprecated APIs in your code as soon as possible. At a minimum, new code you write should never use deprecated APIs. And if your existing code uses deprecated APIs, update that code as soon as possible"

While the current version iOS (12.2) and the current version of Xcode (10.2.1) include support for UIWebView, we expect Apple to finally pull support for the deprecated UIWebView in the next release of iOS and Xcode. When that happens, all Cordova apps must use a WKWebView.

A Cordova WKWebView plugin has been available since the release of iOS 8 however, it is known to have a number of problems. We have forked the WKWebView plugin and modified it to work specifically with Alpha Anywhere.

A few key issues that we had to resolve include the ability to read and write to local files stored on the device for off-line data storage and to support our Instant Update feature. There were also problems with XHR requests and CORS exceptions.

Some of the new capabilities of the Alpha WKWebView include:

* Ability to read from and write to the applications local file system

* Ability to natively view and print (via any AirPrint enabled printer) local PDF, DOC, XLSX, PPT, RTF, TXT, CSV and Apple Keynote, Pages and Numbers file formats in the iOS QuickLook framework via a native iOS modal View Controller. A future release will be able to view remote files as well as multiple files of varying type from a local or remote source.

Advantages of WKWebView

Uses Nitro, a faster JavaScript engine

WKWebView uses the Nitro JavaScript engine, also used by mobile Safari, which comes with significant performance improvements over UIWebView's JavaScript engine. In practice, you'll probably see something in the area of a 20% improvement in speed.

Handles JavaScript asynchronously

In a WKWebView, communication between JavaScript and native code is handled asynchronously. That means your WKWebView UI is still able to respond to HTML events which results in a faster more fluid user experience.

Runs in a separate process, not in the apps main process

WKWebView runs out of process, meaning that its memory is threaded separately from the app; when it exceeds its allocation, WKWebView will crash without crashing the app (which results in the app being notified and attempting to reload the page). By using this process isolation, Apple is able to offer tight security benefits that are not possible when using UIWebView.

In contrast, UIWebView runs in process, which means that the memory it uses is considered to be part of the apps footprint and, if this exceeds what iOS wants to allocate, the app itself will crash. It simply disappears.

Eliminates touch delays

The UIWebView and WKWebView browser components interpret and pass touch events to the app.

A UIWebView adds a 300ms delay after you touch anything to determine whether the user is single or double clicking. This delay is one of the most prominent reasons that HTML-based web apps are considered "sluggish" by many users.

Supports server-side authentication challenges

Unlike UIWebView, which does not support server authentication challenges, WKWebView does. In practical terms, this means that when using WKWebView, you can enter site credentials for password protected websites.

Supports authenticating self-signed security certificates and certificates with errors

WKWebView allows you to bypass errors in security certificates (for example, when using self-signed certificate or an expired certificate) through a "Continue/Cancel" pop up.

Important Notes

Requires iOS 11 or later.

Since the Alpha WKWebView plugin uses a custom protocol for handling access to and the display of local device files, it requires iOS 11 or later to function. While WKWebView was introduced in iOS 8, there are significant limitations in earlier versions, including the inability to access locally stored files, that we are unable to work around so this feature is not backwards-compatible.

Cookies require special handling

Each WKWebView has its own cookie storage and cookies are not shared by the whole app, as is done in a UIWebView. This may affect your application so it's good to know.

When switching to a WKWebView, some plugins have a known issue that cookies will not be used properly on the initial load of the app. In particular session cookies. This is due to a missing proper sync between the underlying WKHTTPCookieStore and the WebView. This will most likely be fixed by Apple in a future update. If you run into a problem, a plugin is available to handle this.

See: https://github.com/CWBudde/cordova-plugin-wkwebview-inject-cookie

Does not support 'Advanced Cache Settings'

‘Cache Source’ and ‘Only Notify Browser of Server Redirection Events’ are not applied when using the WKWebView browsing engine.

Enabling the Alpha WKWebView Plugin

The Alpha WKWebView plugin can be enabled from the Cordova App Builder genie included with Alpha Anywhere. When enabled, the cordova-plugin-alpha-wkwebview-file-xhr will be specified in the config.xml file and that plugin will automatically load the dependent cordova-plugin-alpha-wkwebview-engine plugin. The two are required for proper operation.

The Generated Cordova config.xml File Entries

Do not manually alter the generated config.xml file entries for this plugin! All of these entries are required for proper operation of XHR callbacks and Instant Update.

The alpha-local Custom URL Scheme

The Alpha WKWebView Engine supports a custom URL scheme, alpha-local:// for access to local asset files stored in the device local file system. The local file URL must use the file:// protocol.

• alpha-local://jpg?url=name_of_local_jpg_file

  To access local jpg image files add the prefix: alpha-local://jpg?url= to the local jpg file name. Typical use case is to set the source property of an image to be displayed in a HTML page.

• alpha-local://png?url=name_of_local_png_file

  To access local png image files add the prefix: alpha-local://png?url= to the local png file name. Typical use case is to set the source property of an image to be displayed in a HTML page.

• alpha-local://audio?url=name_of_local_m3a_file

  To access local audio files add the prefix: alpha-local://audio?url= to the local audio file name. Typical use case is to set the source property of an audio player in a HTML page.

• alpha-local://video?url=name_of_local_mp4_file

  To access local video files, add the prefix: alpha-local://video?url= to the local video file name. Typical use case is to set the source property of a video player in a HTML page.

• alpha-local://html?url=name_of_local_html_file

  To access local HTML files, add the prefix: alpha-local://html?url= to the local HTML file name. All referenced local CSS and JavaScript files will automatically load. Typical use case is a URL redirect for the WkWebView window. Instant Update uses this technique.

• alpha-local://view?url=name_of_local_file_to_view

  To display an image, pdf, xlsx, doc, ppt, text, csv, RTF, Pages, Keynote, Numbers, zip, audio or video local file in a native iOS viewer (that supports pinch zoom and sharing options), add the prefix: alpha-local://view?url= to the local pdf file name.

{dialog.object}.addCustomSchemeForAlphaWkWebView(fileSystemURL)

The .addCustomSchemeForAlphaWkWebView() method adds a custom URL scheme to the file URL so that any local image (jpg or png), audio file, or video file can be used as a source for an HTML image tag, audio player or video player.

• If you pass a document type (pdf, doc, xlsx, txt, ppt, rtf, csv), the alpha-local://view scheme is used. To display a PDF file, set up a hidden img tag and set the source to the local file.

• Example: $(hiddenImgTag).src = {dialog.object}.addCustomSchemeForAlphaWkWebView(fileSystemURL_With_PDF_Extension)

• In the image below, a native iOS QuickLook View Controller is displaying a local PDF file (that supports pinch zoom) using the technique described above. The native iOS sharing pop up is displayed.

• 

The Alpha WKWebView Engine and the Alpha Anywhere Local File Manifest tools make it simple to create a powerful data driven offline document viewer that can display a wide variety file formats.

Methods

The following methods are available for use with this plugin:

Method

Description

allowsBackForwardNavigationGestures(true:false)

Allows swiping forward or backwards in browser history

isAlphaWkWebView()

Returns true if the custom Alpha WkWebView Engine is installed.

Limitations

iOS 11 and later

See Also

• GitHub: cordova-plugin-alpha-wkwebview-engine