This article is co-authored by Zoe Azhdari-Radkani (Staff Software Engineer), Merissa Silk (Principal Product Manager), and Radu Tudoran (Director of Engineering).
The Onfido Web SDK serves as an integral tool for our clients, enabling seamless identity verification directly with their end users. Designed with specific, thoughtful attention to user experience, the Onfido Web SDK offers a suite of screens and functionalities to guide users through document and biometric capture processes effortlessly.
While many of our clients integrate the SDK into their web apps using conventional web integration methods, we also cater to those who look to incorporate our web solution into their native apps on iOS or Android devices.
Understanding Webviews
Most of us are familiar with using browsers like Chrome or Safari for browsing the web. However, behind the scenes is another significant player: the Webview. These built-in browsers possess capabilities beyond merely displaying web pages within a mobile app.
Let's dive into what Webviews are and why they are so popular in the world of web and app development.
Native apps are crafted for a specific operating system, such as iOS or Android, to ensure optimal performance. They are typically coded in languages like Swift or Java, enabling deep integration with the device's system.
An application using Webviews is technically still a native app. However, instead of relying on native code for each screen, it leverages a Webview to load web content, effectively serving as the app's interface. In fact, Webviews can power entire apps by leveraging web technology within the native app container.
Advantages of Webviews in hybrid apps
So what makes these hybrid apps so appealing?
Accelerated development: Transforming an existing responsive web app into a hybrid app compatible with various devices is a relatively efficient process.
Seamless updates: Any modifications made to the web app automatically reflect across all users, courtesy of centralized content delivery from your server. Unlike native apps, which require separate builds for each platform and potential delays due to app store approvals, web apps offer unparalleled convenience in deployment and updates.
Convenient deployment and updates: By combining the agility of web apps with the robustness of native features, hybrid apps empower your web app with additional capabilities while ensuring the app size remains manageable.
These advantages underscore how Webviews unlock potent benefits, making hybrid apps an increasingly favored approach for application developers.
Native apps with Webviews vs. web apps
Before looking at integrating Onfido’s Web SDK into native apps, let's explore 2 key technical concepts: native apps with Webviews and web apps.
Understanding Webviews
Webviews are often described as embedded browsers – but what does this really mean?
Picture a browser divided into 2 components: the visible controls like the address bar and buttons, and the engine responsible for rendering web pages. A Webview essentially embodies this rendering engine, concealed within your app to display web content. That section within most apps showing a web page – It's likely a Webview in disguise!
How do Webviews work?
Think of your Webview as a discrete entity within your native app. It has the capability to fetch content from remotely hosted locations, enabling the reuse of code between your web app and the web elements within your native app.
In a typical browser, web content is isolated for security purposes. This means that if malicious code infiltrates the browser, it won’t bring down your entire app—just the browser itself.
However, with Webviews, you retain control over the content, minimizing the risk of encountering malicious code.
But there's more to it! Unlike a standard browser, Webview content can communicate with your native app's features and APIs, such as location services, cameras, and contacts. Developers achieve this seamless interaction through a mechanism known as a "bridge."
By leveraging this bridge, developers facilitate communication between the WebView and the native app, enabling a harmonious integration of web content and native features.
Setting up permissions
Now that we have a better understanding of how Webviews function, it’s time for our 2nd topic: permissions.
For security and privacy reasons, whenever an app requires access to hardware inputs such as the camera or microphone—whether it's a native app or within a browser—it must request permission. Without these permissions, enabling the camera or microphone input stream is simply not possible.
Desktop browsers typically handle permissions by presenting a clear message in pop-ups at the time access is needed. As a developer, you can use the outcome of these permission requests in your code to proceed to the next step or fallback to alternative options.
However, in native apps, you must declare these permissions in advance. This ensures that users are alerted and given the opportunity to grant system-level access permissions for the app upon installation or 1st opening.
The Onfido Web SDK uses the device's camera and, in some cases, the microphone to capture photos and videos for document and biometric identity verification. When the SDK is used in browsers, a standard permission popup appears, requesting access from the end user to their camera or microphone. If these permissions are blocked, we display a guide called permission recovery, which assists the user in enabling them.
The same principles apply when the camera and microphone are required via Webviews within a native app. However, there are some preparations you'll need to undertake to ensure your app is ready to enable communication of these permissions between the native side and the Webview component.
Now, let's briefly explore the minimum configuration required for iOS and Android to get the Onfido Web SDK up and running.
Integrating Webviews for iOS
In iOS development, the Webview component you'll be using is called WKWebView. This component uses the WebKit web rendering engine, which might not be immediately apparent, but it's the same engine powering Safari and Chrome on iOS.
In iOS apps using the WKWebView component for Webviews, you simply list the permissions you require in the Info.plist file and initiate the Webview, bootstrapping the Onfido Web SDK. WKWebView is highly efficient and behaves almost identically to the desktop Safari browser. Therefore, you don't need to perform much additional configuration to ensure the proper functioning of the Web SDK within the Webview. WKWebView handles permissions seamlessly, much like a standard browser would.
Integrating Webviews for Android
In Android development, Webviews are implemented using an extension of the View class. WebView utilizes two distinct clients: WebViewClient and WebChromeClient.
While Android WebView operates similarly to a standard Chrome browser, it doesn't inherently support all the features and functionalities that the Chrome browser does out of the box. As a result, there's a bit more groundwork required.
First, you'll need to declare all the necessary hardware permissions in your manifest file upfront using the appropriate tags. This step is crucial for acknowledging which APIs the app will need to access later.
Next, when setting up your Webview, you'll need to configure it to communicate the permissions via Webview settings. Additionally, you'll need to handle runtime permissions, providing a way to override the PermissionRequest() when accessing the camera from the Webview.
Ensuring these permissions are properly managed is essential for the seamless integration of the Onfido Web SDK within your Android app's Webview component.
Troubleshooting top challenges
Permissions and unsupported APIs in browsers are the 2 main reasons that could lead to the Onfido Web SDK failing to load in a Webview. When such errors occur, the Web SDK may trigger the onError callback with the error type "permissions_unavailable," indicating that the SDK was unable to assess or request the necessary permissions.
In cases where the native app cannot provide the permission to access hardware, it's important to have a reliable fallback option. One effective approach is to redirect the user out of the native app and into a browser window with a hosted instance as soon as the onError callback is triggered.
There are several benefits to opening a browser window following loading errors. First, permissions will be directly requested from the browser, bypassing any potential issues with native app permissions. Additionally, executing the Onfido flow in a standard browser environment ensures consistent behavior and functionality, mitigating potential compatibility issues that may arise in Webview environments.
By implementing this fallback strategy, you can enhance the quality and reliability of your integration, providing users with a seamless experience even in the face of unexpected errors.
You can find additional information and resources on how to successfully integrate Webviews here, or by watching this webinar:
Key takeaways
Here are our top 3 key takeaways to keep in mind when considering using Webviews in your integration.
Webviews: fast integration, deeper understanding required
Webviews offer an efficient and speedy integration method, but they require a solid understanding of the underlying technology to ensure seamless functionality.
Permissions handling: crucial for Webview success
Correct permissions handling is essential to the success of Webviews. Developers need to ensure that permissions can be appropriately requested across all user flows and use cases. By prioritizing permissions management, you can enhance the performance of your Webview integrations.
Fallback strategy: essential for optimal conversion rates
Implementing a fallback strategy is highly recommended, particularly if your team doesn't have complete control over the end-to-end user experience. A fallback strategy ensures that, in the event of unexpected errors or limitations, users can effortlessly transition to alternative methods, ensuring optimal conversion rates and user satisfaction.
By keeping these key takeaways in mind, you can navigate the complexities of Webview integration more effectively, ensuring a smoother and more successful implementation process.
