Biometric Authentication API (Face ID / Touch ID)
Protect your iOS app with Face ID or Touch ID and verify users biometrically from your web app.
This is an independent, more powerful, yet more complicated alternative to our simple Config.swift-based enableBioMetricAuth option. This API allows you to use biometric authentication in your app and return result via JavaScript to your website. Biometric authentication includes Face ID (in newer iPhone designs) and Touch ID (in older iPhone designs) with code as fallback. By calling the "bioauth://" URL command, you can trigger the biometric authentication natively in your app. Once the process is complete, WebViewGold will report the results back to your web app by calling one of the following functions:
- onBioAuthSuccess()
- Called when the authentication process was successful.
- onBioAuthFailure(errorCode, errorMessage)
- Called when the authentication process fails and provides error information.
- onBioAuthUnavailable()
- Called when biometric authentication is found to be unavailable on the device.
To use this API, first, you must add the privacy key for Face ID biometric authentication in your Info.plist file. This is done by opening Info.plist, hovering over an exisiting key, clicking the (+) symbol to add a new key below your currently selected one and selecting the "Privacy - Face ID Usage Description" key option. Without this key, the app will not support Face ID. The value for this key is a description that is presented to the user the first time your app attempts to use Face ID. This description should clearly explain why your app needs to use Face ID. See below for an example description for this key:
Next, you must define the following functions (in JavaScript) in your web app to handle the results of a biometric authentication:
<script>
function onBioAuthSuccess() {
alert("Bio Authentication Succeeded");
}
function onBioAuthFailure(errorCode, errorMessage) {
// errorCode = Int, errorMessage = String
alert(`Bio Authentication Failed, ${errorMessage} (code ${errorCode})`);
}
function onBioAuthUnavailable() {
alert("Bio Authentication Unavailable");
}
</script>
Then, load this kind of URL to trigger the biometric authentication process in your web app:<script> window.location.href = "bioauth://"; </script>
Security Notice: It should be noted that malicious users may be able to cause the onBioAuthSuccess() function to be called without completing the authentication process. Since authentication is a sensitive process, it is recommended to add an extra layer of security in your web app, such as a cookie or geolocation check, to help ensure the integrity of the authentication. Please consult your website cybersecurity expert for tailored guidance for your web app's needs.
SDK-style implementation notes
Treat this feature as a native capability exposed to your web layer: keep your production website or PWA as the source of truth, then use the documented WebViewGold configuration flags, URL commands, and JavaScript bridge calls to opt in to native iOS behavior only where it adds value. This approach keeps your codebase maintainable because the same web application can serve browsers, WebViewGold for iOS, and the other WebViewGold platforms with minimal conditional logic.
For reliable results, prefer HTTPS endpoints, stable route names, explicit success/error states in your UI, and small JavaScript helper functions that wrap native calls. For example, a web app built with jQuery Mobile, Lovable, Base44, Bolt, WordPress, Bubble, a custom React/Vue/Angular stack, or static HTML can expose a single button or event handler that triggers the native WebViewGold API while still showing a graceful browser fallback.
- Recommended integration pattern: detect the app context, call the WebViewGold API, then update your web UI after the native callback or route change.
- Testing checklist: validate the feature on a real device or packaged build, verify permissions and store review text, and confirm that browser-only users still receive a useful fallback.
- SEO benefit: keep feature pages, route titles, and structured content indexable on your website while WebViewGold delivers the native app shell for iOS users.