Skip to end of metadata
Go to start of metadata

Overview

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

Requirements

  • Titanium SDK
  • iOS 9+
  • Xcode 7+

Titanium SDK 8.0.0 release

Icon

With Titanium SDK 8.0.0, we now use WKWebView to implement Ti.UI.WebView (as Apple has deprecated UIWebView). 

Adding the following to your HTML will make a WKWebView scale its content the same was as the old UIWebView.

WKWebView scaling

WKWebView also has few restriction specially with local file accessing. For supporting custom-fonts with WKWebView a little modification is required in the HTML files:

Installation

Download the stable release, unpack the module, and place it inside the modules/iphone directory of your project. Edit the iOS and modules section of your tiapp.xml file to include this module:

tiapp.xml update

Features

API's

NameExample
WebViewWK.createWebView(args)
ProcessPoolWK.createProcessPool()
ConfigurationWK.createConfiguration()

WebView

Properties

NameType
disableBounceBoolean
scalesPageToFitBoolean
disableZoomBoolean
allowsBackForwardNavigationGesturesBoolean
allowsLinkPreviewBoolean
scrollsToTopBoolean
disableContextMenuBoolean
userAgentString
urlString
dataTi.Blob, Ti.File
htmlString
titleString
progressNumber
backForwardListObject
ignoreSslErrorBoolean
basicAuhenticationObject
  • username (String)
  • password (String)
  • persistence (CREDENTIAL_PERSISTENCE_*)
cachePolicyCACHE_POLICY_*
timeoutNumber
selectionGranularitySELECTION_GRANULARITY_*
allowedURLSchemesArray<String>
touchEnabledBoolean
willHandleTouchesBoolean
requestHeadersObject<String, Any>
zoomLevelNumber
keyboardDisplayRequiresUserActionBoolean

Methods

NameParameterReturn
stopLoading-Void
setHtmlhtml, 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) 
startListeningToPropertiesArrayVoid
stopListeningToPropertiesArrayVoid
fireEventName (String), Payload (Object)Void
addEventListenerName (String), Callback (Function)Void
removeEventListenerName (String), Callback (Function)Void
takeSnapshot *Callback (Function)Void
addUserScriptObject: source (String), injectionTime (INJECTION_TIME_*), mainFrameOnly (Boolean)Void
removeAllUserScripts-Void
addScriptMessageHandlerName (String)Void
removeScriptMessageHandlerName (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, use the asynchronous solution:

Events

NameProperties
messagename, body, url, isMainFrame
progressvalue, url
beforeloadurl, navigationType, title
loadurl, title
redirecturl, title
errorsuccess, url, error, code
sslerrorurl
handleurlurl
blacklisturlurl

Constants

NameProperty
CREDENTIAL_PERSISTENCE_NONEbasicAuthentication.persistence
CREDENTIAL_PERSISTENCE_FOR_SESSIONbasicAuthentication.persistence
CREDENTIAL_PERSISTENCE_PERMANENTbasicAuthentication.persistence
CREDENTIAL_PERSISTENCE_SYNCHRONIZABLEbasicAuthentication.persistence
AUDIOVISUAL_MEDIA_TYPE_NONEmediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_AUDIOmediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_VIDEOmediaTypesRequiringUserActionForPlayback
AUDIOVISUAL_MEDIA_TYPE_ALLmediaTypesRequiringUserActionForPlayback
CACHE_POLICY_USE_PROTOCOL_CACHE_POLICYcachePolicy
CACHE_POLICY_RELOAD_IGNORING_LOCAL_CACHE_DATAcachePolicy
CACHE_POLICY_RETURN_CACHE_DATA_ELSE_LOADcachePolicy
CACHE_POLICY_RETURN_CACHE_DATA_DONT_LOADcachePolicy
SELECTION_GRANULARITY_AUTOMATICselectionGranularity
SELECTION_GRANULARITY_CHARACTERselectionGranularity
ACTION_POLICY_CANCELhandleurl (Event)
ACTION_POLICY_ALLOWhandleurl (Event)
INJECTION_TIME_DOCUMENT_STARTaddUserScript.injectionTime
INJECTION_TIME_DOCUMENT_ENDaddUserScript.injectionTime

WebView <-> App Communication

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

Send data from the Web View

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 determine if the message 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:

Send messages from the app to the Web View

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 using 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.

Ti.App events

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

Ti.App events in 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 tiapp.xml. Different to the UIWebView and its Ti.UI.WebViewimplementation, the WKWebView is more configurable but require the developer to act more carefully.

Inter-App Communication

For using the URL schemes mailtotelsms 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:

iOS plist dictionary

Generic Property Observing

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

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.

Configuration API

Properties

NameType

mediaTypesRequiringUserActionForPlayback

AUDIOVISUAL_MEDIA_TYPE_*
suppressesIncrementalRenderingBoolean
preferencesObject
  • minimumFontSize (Double)
  • javaScriptEnabled (Boolean)
  • javaScriptCanOpenWindowsAutomatically (Boolean)
allowsInlineMediaPlaybackBoolean
allowsAirPlayMediaPaybackBoolean
allowsPictureInPictureMediaPlabackBoolean
processPoolProcessPool

Process pool

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

Process pools

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 was 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.