iOS WebView Integration
Introduction
TrustX is not only supported in browser flows but also allows for integration through WebView objects such that users can implement the TrustX flow directly through their native applications. This document will cover the integration requirements for iOS devices.
WKWebView Configuration
The iOS WKWebView is a standard framework component located in the WebKit framework. For more details, please refer to Apple's developer documentation.
Initial WKWebView integration
This code snipped represents a basic WKWebView integration in any app:
import UIKitimport WebKitclass WebViewController: UIViewController, WKUIDelegate { var webView: WKWebView! override func loadView() { let webConfiguration = WKWebViewConfiguration() webView = WKWebView(frame: .zero, configuration: webConfiguration) webView.uiDelegate = self view = webView } override func viewDidLoad() { super.viewDidLoad() // the default display language can be specified by apending the 'lang' query string param to the 'redirectUrl' e.g., // redirectUrl + "&lang=<ISO language code>" let myURL = URL(string:redirectUrl) let myRequest = URLRequest(url: myURL!) webView.load(myRequest) }}After the initial integration of the WKWebView through StoryBoard or code, additional configurations are required.
Camera Permissions
To add a camera usage description to the application, add NSCameraUsageDescription to the application 'info.plist' file. This is a message that informs the end-user why the app is requesting access to the device's camera. More info: https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription
To follow the camera permission settings of the application, implement the WKUIDelegate method. This feature is available starting from iOS 15; before that version, users will need to use prompts from the web application.
Code sample:
optional func webView( _ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin, initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType, decisionHandler: @escaping (WKPermissionDecision) -> Void)For more information, see webView(_:requestMediaCapturePermissionFor:initiatedByFrame:type:decisionHandler:)
WKScriptMessageHandler
To listen for any web event from TrustX, utilize the WKScriptMessageHandler. The userContentController(_:didReceive:)method can be used to inform the handler that a webpage has sent a script message.
func userContentController( _ userContentController: WKUserContentController, didReceive message: WKScriptMessage)For more information, see userContentController(_:didReceive:)
The following table details all event that can be received from TrustX. The returned value from the listed events will be the event name.
| Event Name | Description |
|---|---|
webLoaded | A safety feature to ensure that only the TrustX web app can be loaded. |
webCompleted | indicates the completion of the TrustX flow. |
webTimeout | Indicates that an activity has expired during the TrustX flow. |
openCameraSettings | Used to notify the iOS app that the WebApp is requesting to open the application settings. |
error | Indicates an error has occurred. |
For example:
extension WebViewController: WKScriptMessageHandler { func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) { // do something with my message from the web }}WKWebViewConfiguration
After configuring the web view as desired, additional configurations must be made to ensure that the TrustX flow works as intended.
First, set the allowsInlineMediaPlayback to true which will enable inline media playback.
var allowsInlineMediaPlayback: Bool { get set }For more information, see allowsInlineMediaPlayback
To receive events inside the userContentController function, it's necessary to subscribe to each event using add(_:name:) function.
func add( _ scriptMessageHandler: WKScriptMessageHandler, name: String)For more information, see add(_:name:)
Below is an example of setting the allowsInlineMediaPlayback configuration.
myWebView.configuration.allowsInlineMediaPlayback = truemyWebView.configuration.userContentController.add(self, name: "webLoaded")Web App Navigation
In some cases of the TrustX flow, navigation is required to be implemented in the native UI. After adding a button to the UI, an action should be assigned to the button. For example, the goBack() function can be assigned to return to the 'back' item in the back-forward list.
For example:
func webBackAction() { myWebView.goBack()}For more information on this function, see goBack().
Example of Full WebView Component Configuration
Below is a code example showing how to initialise, configure and load URL into WebView component using the above implementations:
class WebViewController: UIViewController, WKUIDelegate { var webView: WKWebView! override func loadView() { let webConfiguration = WKWebViewConfiguration() webConfiguration.allowsInlineMediaPlayback = true webConfiguration.userContentController.add(self, name: "webLoaded") webConfiguration.userContentController.add(self, name: "webCompleted") webConfiguration.userContentController.add(self, name: "webTimeout") webConfiguration.userContentController.add(self, name: "error") webConfiguration.userContentController.add(self, name: "openCameraSettings") webView = WKWebView(frame: .zero, configuration: webConfiguration) webView.uiDelegate = self view = webView } override func viewDidLoad() { super.viewDidLoad() let myURL = URL(string:"...") let myRequest = URLRequest(url: myURL!) webView.load(myRequest) } // MARK: - Permission handling func webView( _ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin, initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType, decisionHandler: @escaping (WKPermissionDecision) -> Void ){ //granting the permission decisionHandler(.grant) } func webBackAction() { webView.goBack() }}extension WebViewController: WKScriptMessageHandler { func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) { // Here we handle events from the webApp, that are listed in the table above (webLoaded, webCompelted, etc.) // get eventName by calling message.name if message.name == "webCompleted" { self.dismiss(animated: true) } }}Known Issues and Limitations
WebRTC, one of the main component of TrustX, does not support camera functionality in WKWebView on iOS versions earlier than 14.3.