Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

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:

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.

Managing Permissions

Even if a given verification flow may not require the use of file or microphone access, it is required to declare all the permissions listed in the following sections before the Onfido Web SDK is initialised.

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

iOS

On iOS, the camera, microphone, photo library and location access permissions must be declared in the Info.plist file:

<key>NSCameraUsageDescription</key>
<string>Camera Access</string>
<key>NSMicrophoneUsageDescription</key>
<string>Mic Access</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo Library Access</string>

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

Note: With Safari webviews, the user will be prompted to grant/deny the requested permissions when those are needed (unlike Android that requires permissions to be granted when the webview is loaded).

Android

On Android, the camera, microphone and audio settings management permissions must be declared upfront:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

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

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.

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

Our solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2022. All rights reserved.
Company Registration Number: 07479524.