Using the Onfido Web SDK in a webview

Start here

Webviews may be used for displaying web content, such as the Onfido Web SDK, within mobile apps. While webviews provide a lightweight integration and simplify cross-platform development, they have limitations in terms of accessing device features such as the camera, microphone, and local files as they rely on the webview engines provided by the operating system. As such webviews don’t offer the same level of performance and user experience as the functionality of the Onfido mobile SDKs in native apps.

Where possible, Onfido recommends using its native mobile SDKs for optimal performance:

• iOS SDK
• Android SDK
• React Native SDK (integration library)
• Flutter SDK (integration library)
• Cordova SDK (integration library) - currently in Alpha, available via npm-only

Using the Onfido Web SDK in a webview

When a webview integration of the Onfido Web SDK is the only viable option, the following guide provides an overview of the requirements and considerations that are different from traditional web integrations.

Choosing the right SDK distribution channel

In the context of a webview, the Onfido Web SDK can still be imported via any of the existing distribution channels. It is recommended to use the Onfido CDN in order to benefit from the latest functionality including improvements brought to webview support.

Permissions Overview

For security and privacy reasons, whenever a native or web app requires access to the device's hardware, such as camera or microphone, distinct permissions must be requested. Without these permissions you won't be able to enable the camera or microphone input streams. Desktop browsers handle permission with a clear message with a pop-up at the time the access is needed. As a developer, you can use the outcome of this permission in your code and proceed as expected or fallback to an alternative path.

As opposed to desktop browsers, native apps using embedded webviews must can declare the device hardware permissions that are required to be accessed upfront before the webview is loaded.

The Onfido Web SDK uses the device's camera and in some cases microphone to capture photos and videos of documents and user biometrics for identity verification. When the SDK is used in a browser, a permission pop-up appears requesting permission from the end user to access the device's camera and/or microphone. In case the permissions are blocked or denied by the user, the SDK provides a screen that explains to the user why those permissions are required and how to enable them.

Managing Permissions

Depending on the steps defined in your verification flow, you will require access to the device camera on almost on all document and biometric capture steps and microphone in case of face motion capture.

It is necessary to declare and handle all permissions needed for the webview before the Onfido Web SDK is initialised.

The webview will prevent the Onfido Web SDK from requesting permissions from the user unless they have first been declared during the integration process.

Note: if you have a file upload fallback configured for any document or face capture steps, you will also need to include the permission for accessing the device's photo library.

iOS

In iOS development the webview component is called WKWebView. It uses Webkit as its rendering engine, the same engine that powers the Safari and Chrome browsers on iOS. WKWebView provides the same behaviour as the standalone Safari browser, handling permissions in a similar way.

In order to use the webview component in native iOS apps, the permissions detailed below are required in the Info.plist file before the Onfido Web SDK can be initialized:

1<key>NSCameraUsageDescription</key>
2<string>Camera Access</string>
3<key>NSLocationWhenInUseUsageDescription</key>
4<string>Location Access</string>
5<key>NSMicrophoneUsageDescription</key>
6<string>Mic Access</string>
7<key>NSPhotoLibraryUsageDescription</key>
8<string>Photo Library Access</string>

A sample iOS app is available to assist with your development.

Android

For native Android apps, webviews are an extension of the View class. Android webviews support two clients: WebViewClient and WebChromeClient.

In order to use the webviews in native Android apps, the following steps must be followed:

• All hardware permissions must be declared upfront. This is just to acknowledge which APIs the app will need to request access for at runtime.

1<uses-permission android:name="android.permission.INTERNET" />
2<uses-permission android:name="android.permission.CAMERA" />
3<uses-feature android:name="android.hardware.camera" android:required="true" />
4<uses-feature android:name="android.hardware.camera.autofocus" />
5<uses-permission android:name="android.permission.RECORD_AUDIO" />
6<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

• The runtime permissions requests provide a way to override the PermissionRequest() function while accessing camera from the webview.

You may use the sample Android app and the mainMainActivity.kt as a guide on how to:

• extend WebViewClient and WebChromeClient to bootstrap the SDK
• override the onPermissionRequest with the declared permissions required by the SDK.

Note: With Chrome webviews, the user must be prompted to grant/deny the requested permissions when the webview is initialised. If the user does not grant the requested permissions, the SDK will not be able to load and the onError callback will be triggered with the type permissions_unavailable.

Cross-platform libraries

When integrating the Onfido Web SDK in a webview within a cross-platform framework such as React Native, Flutter or Cordova, the permissions listed above for both iOS and Android must be declared.

A sample React Native app is available to assist you with your development.

Identifying webview-related errors

Permissions and unsupported custom browsers are the two main reasons that may result in the Onfido Web SDK failing to load in a webview. Such errors may result in the Web SDK triggering the onError callback to your integration with the following error type:

• permissions_unavailable will be returned if the SDK was unable to assess or request the necessary permissions.
  • Notes:
  • The error type permissions_unavailable is introduced with version 13.7.0 of the Onfido web SDK.
  • When the onError callback is triggered back to the integrating app, the user is shown a spinner. It is the responsibility of the integrating app to handle the error and redirect the user to an alternative path.

Fallback Recommendations

To ensure that the user experience is preserved after a webview-related error occurs, it is recommended to redirect the user to a new browser window with Onfido's Smart Capture Link (or self-hosted instance) as soon as the onError callback is triggered. The benefits of opening a browser window following loading errors are that permissions will be requested directly from the browser and the Onfido flow will be executed in a standard browser.

Known Issues

iPhone 14 Pro & 15 Pro models capture blur issue

The iPhone 14 Pro and iPhone 15 Pro and Pro Max models have a known blur issue that prevents the focus on items closer to 20cm. This occurs when the camera is controlled by third party apps embedded in webviews:

• The Onfido iOS SDK 28.2.0 and later fix this issue for iPhone 14/15 Pro models
• The Onfido Web SDK now works with iOS 17+ Safari.
• The issue cannot be resolved when the iPhone camera is controlled within the iOS Safari webview.

Content Security Policy and Webview

Please read the Onfido Web SDK Content Security Policy (CSP) guide for help troubleshooting most common issues.