Skip to content

Latest commit

 

History

History
317 lines (265 loc) · 10.9 KB

README.md

File metadata and controls

317 lines (265 loc) · 10.9 KB
Raw

Ti.WKWebView

License Support

Summary

Ti.WKWebView is an open source project to support the WKWebView API with Titanium.

Requirements

  • Titanium SDK 5.0.0 or later
  • iOS 9+
  • Xcode 7+

Download + Setup

Download

Setup

Unpack the module and place it inside the modules/iphone folder of your project. Edit the iOS and modules section of your tiapp.xml file to include this module:

<ios>
  <min-ios-ver>9.0</min-ios-ver>
</ios>
<modules>
  <module>ti.wkwebview</module>
</modules>

Features

API's

Name Example
WebView WK.createWebView(args)
ProcessPool WK.createProcessPool()
Configuration WK.createConfiguration()

WebView

Properties

Name Type
disableBounce Boolean
scalesPageToFit Boolean
disableZoom Boolean
allowsBackForwardNavigationGestures Boolean
allowsLinkPreview Boolean
scrollsToTop Boolean
disableContextMenu Boolean
userAgent String
url String
data Ti.Blob, Ti.File
html String
title String
progress Number
backForwardList Object
ignoreSslError Boolean
basicAuhentication Object
- username (String)
- password (String)
- persistence (CREDENTIAL_PERSISTENCE_*)
cachePolicy CACHE_POLICY_*
timeout Number
selectionGranularity SELECTION_GRANULARITY_*
allowedURLSchemes Array<String>
touchEnabled Boolean
willHandleTouches Boolean
requestHeaders Object<String, Any>
zoomLevel Number
keyboardDisplayRequiresUserAction Boolean

Methods

Name Parameter Return
stopLoading - Void
setHtml html, options (Object - { baseURL, mimeType }, optional) Void
reload - Void
repaint - Void
goBack - Void
goForward - Void
canGoBack - Boolean
canGoForward - Boolean
isLoading - Boolean
evalJS ** Code (String), Callback (Function)
startListeningToProperties Array Void
stopListeningToProperties Array Void
fireEvent Name (String), Payload (Object) Void
addEventListener Name (String), Callback (Function) Void
removeEventListener Name (String), Callback (Function) Void
takeSnapshot * Callback (Function) Void
addUserScript Object: source (String), injectionTime (INJECTION_TIME_*), mainFrameOnly (Boolean Void
removeAllUserScripts - Void
addScriptMessageHandler Name (String) Void
removeScriptMessageHandler Name (String) Void

* Available on iOS 11.0+

** Since iOS 12.0, using evalJS in sync is not possible anymore, because the internal callback is now called on the main thread, causing a deadlock in the run-loop that is used to return the value synchronously. To fix this, please use the asynchronous solution:

webView.evalJS('document.title', function (e) {
    alert(e.result);
});

Events

Name Properties
message name, body, url, isMainFrame
progress value, url
beforeload url, navigationType, title
load url, title
redirect url, title
error success, url, error, code
sslerror url
handleurl url
blacklisturl url

Constants

Name Property
CREDENTIAL_PERSISTENCE_NONE basicAuthentication.persistence
CREDENTIAL_PERSISTENCE_FOR_SESSION basicAuthentication.persistence
CREDENTIAL_PERSISTENCE_PERMANENT basicAuthentication.persistence
CREDENTIAL_PERSISTENCE_SYNCHRONIZABLE basicAuthentication.persistence
AUDIOVISUAL_MEDIA_TYPE_NONE mediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_AUDIO mediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_VIDEO mediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_ALL mediaTypesRequiringUserActionForPlayback
CACHE_POLICY_USE_PROTOCOL_CACHE_POLICY cachePolicy
CACHE_POLICY_RELOAD_IGNORING_LOCAL_CACHE_DATA cachePolicy
CACHE_POLICY_RETURN_CACHE_DATA_ELSE_LOAD cachePolicy
CACHE_POLICY_RETURN_CACHE_DATA_DONT_LOAD cachePolicy
SELECTION_GRANULARITY_AUTOMATIC selectionGranularity
SELECTION_GRANULARITY_CHARACTER selectionGranularity
ACTION_POLICY_CANCEL handleurl (Event)
ACTION_POLICY_ALLOW handleurl (Event)
INJECTION_TIME_DOCUMENT_START addUserScript.injectionTime
INJECTION_TIME_DOCUMENT_END addUserScript.injectionTime

WebView <-> App Communication

You can send data from the Web View to your native app by posting messages like this:

window.webkit.messageHandlers.Ti.postMessage({message: 'Titanium rocks!'},'*');

Please note that you should use the Ti message handler to ensure the message event is triggered. This also ensures that your app does not receive unwanted messages by remote pages.

After sending the message from your HTML file, it will trigger the message event with the following event keys:

  • url (The url of the triggered message)
  • body (The message body. In this case: {message: 'Titanium rocks'}
  • name (The name of the message. In this case: 'Ti')
  • isMainFrame (A boolean determing if the messsage was sent from the main-frame)

For sending messages from the app to the Web View, use evalJS to call your JS methods like this:

webView.evalJS('myJSMethod();');

Check out the example file for sending and receiving message back and forth.

Note 1: Since 2.3.0, this module also supports synchronous communication via evalJSSync. Instead of evalJS, it takes only one parameter (the code to evaluate) and no callback. Instead, it returns the JavaScript evaluation result directly. While we understand there might be use-cases for this functionality, we highly recommend to use asynchronous communication instead, since synchronous method calls with block the user interface and may cause in an app-termination for long-running evaluations.

Note 2: Since 2.4.0, this modules also supports Ti.App-like events that allows the developer to fire events and add event-listeners to ease the communication between the app and the web-view. These are:

  • fireEvent
  • addEventListener
  • removeEventListener Different to the Ti.App events, these ones are fired on the top-level module instance. See this example for details:
var WK = require('ti.wkwebview');

// Fire event
WK.fireEvent('myEvent', { message: 'Titanium rocks!' });

// Listen to events
WK.addEventListener('myEvent', function(e) { ... });

The above events can be used on the JS-side as well. Here is an example on how to use them in your HTML file (ensure that there is no concurring WK variable):

<!DOCTYPE html>
<html>
    <head>
        <title>Local HTML</title>
    </head>
    <body>
        <p>Hello world!</p>
        <script type=\"text/javascript\">
            // Listen to the native Titanium event
            WK.addEventListener('testEvent', function(e) {
                // Fire back an event to the native Titanium app
                WK.fireEvent('testEventBack', {
                    message: 'It worked!'
                });
            });
        </script>
    </body>
</html>

Saving Images

If you want to allow users to browse the internet (e.g. by using a remote site), ensure to include the NSPhotoLibraryAddUsageDescription key in your tiapp.xml. Different to the UIWebView and its Ti.UI.WebView implementation, the WKWebView is more configurable but require the developer to act more carefully.

Inter-App Communication

For using the URL schemes mailto, tel, sms and itms-services you only have to set the allowedURLSchemes property. Other URL schemes (i.e. fb) additionally need the corresponding LSApplicationQueriesSchemes key in the iOS plist dictionary of your tiapp.xml:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fb</string>
</array>

Generic Property Observing

You can listen to changes in some of the native properties (see the native KVO-capability). Example:

// Start listening for changes
webView.startListeningToProperties(['title']);

// Add an event listener for the change
webView.addEventListener('title', function(e) {
    // Check for e.value
});

// Remove listening to changes (remove the event listener as well to keep it more clean)
webView.stopListeningToProperties(['title']);

Configuration

Use the configuration API to configure the initial web-view. This property can only be set when creating the webview and will be ignored when set afterwards. Example:

var WK = require('ti.wkwebview');

var config = WK.createConfiguration({
    allowsPictureInPictureMediaPlaback: true
});

var webView = WK.createWebView({
    configuration: config
});

Properties

Name Type
mediaTypesRequiringUserActionForPlayback AUDIOVISUAL_MEDIA_TYPE_*
suppressesIncrementalRendering Boolean
preferences Object
- minimumFontSize (Double)
- javaScriptEnabled (Boolean)
- javaScriptCanOpenWindowsAutomatically (Boolean)
allowsInlineMediaPlayback Boolean
allowsAirPlayMediaPayback Boolean
allowsPictureInPictureMediaPlaback Boolean
processPool ProcessPool

Process Pool

Use process pools to share cookies between web views. Process pools do not take arguments, just pass the same reference to multiple web views. Example:

var WK = require('ti.wkwebview');

var pool = WK.createProcessPool();

var config1 = WK.createConfiguration({
    processPool: pool
});

var config2 = WK.createConfiguration({
    processPool: pool
});

var firstWebView = WK.createWebView({
    configuration: config1
});

var secondWebView = WK.createWebView({
    configuration: config2
});

Handle custom URL-schemes

  • The custom url-scheme has to be registered in the allowedURLSchemes array-property
  • Passes the url for a custom url-scheme
  • The event is introduced because iOS 10+ causes issues for some custom url-schemes and forwarding the url  in an event is a simpler short term solution than implementing the WKURLSchemeHandler which is iOS 11+ only.
// Add an event listener to listen for a custom URL-scheme
webView.addEventListener('handleurl', function(e) {
  var handler = e.handler;

  Ti.Platform.openURL(e.url);
  handler.invoke(WK.ACTION_POLICY_CANCEL); // ACTION_POLICY_CANCEL or ACTION_POLICY_ALLOW
});

Author

Hans Knoechel (@hansemannnn / Web) for Axway Appcelerator

License

Apache 2.0

Contributing

Code contributions are greatly appreciated, please submit a new pull request!