Mobile WebView implementations

Use this guide when your application opens an ID.me OAuth 2.0 verification workflow inside a native Android app, native iOS app, embedded WebView, or iframe. This page is especially relevant for integrations that use ID.me web or native platform SDKs for document capture, selfie capture, liveness checks, or other camera-based verification steps.

The OAuth parameters, redirect URI, token exchange, and attribute retrieval are the same as a standard OAuth 2.0 Authorization Code integration. The difference is that document upload, selfie capture, and liveness checks require platform-specific permission handling before the user can continue.

It is possible to require live camera capture and prevent users from selecting an existing image from their photo gallery. If your ID.me policy requires live capture, your integration must handle camera permissions correctly on every platform you support.

ID.me pages may check camera access before opening camera capture so that a denied permission does not crash the host app. That site-side guard does not replace native permission handling. Your Android or iOS app must still provide a way for the user to enable camera access and continue.

Platform guides

Use the guide for the platform shell that hosts the ID.me verification workflow:

• Android WebView Requirements
• iOS WKWebView Requirements
• iframe Implementations

Requirements

Before launching an ID.me verification workflow in a mobile WebView, make sure your app supports:

• HTTPS OAuth authorization URLs and the same client_id, redirect_uri, scope, state, and PKCE behavior used by your standard OAuth integration.
• Camera permissions for document capture, selfie capture, and liveness checks.
• File chooser callbacks for document upload in WebViews.
• A native settings path for users who have denied camera access.
• An optional WebView-to-native bridge for ID.me pages to request app settings when camera access is blocked.
• Return URL handling after the user completes the OAuth redirect.
• A fallback path if the device does not support camera capture or the user cannot grant camera access.

Camera permission recovery

When camera access is denied, keep the user in a recoverable state. The native app should show clear guidance and, when possible, provide an Open Settings button that opens the host app’s operating-system settings page.

Use this behavior every time the user starts document capture, selfie capture, liveness capture, or any SDK step that requires the camera. Do not only check permission during app launch or the first verification session.

• If camera permission is granted, continue to the requested capture step.
• If permission has not been requested, request it before starting capture.
• If permission is denied but can be requested again, show an explanation and request permission on retry.
• If permission is permanently denied or restricted, show an explanation and open app settings.
• If the user returns from settings, re-check camera permission before launching capture.

Web content cannot reliably open Android or iOS app settings on its own. If your WebView host wants an ID.me page to show an Open Settings action, expose a native bridge that the page can call. Native apps should also handle this state independently because browser and WebView support varies by platform.

1
function openNativeCameraSettings() {
2
  if (window.IDmeNative?.openAppSettings) {
3
    window.IDmeNative.openAppSettings("camera");
4
    return true;
5
  }
6
7
  if (window.webkit?.messageHandlers?.idmeNative) {
8
    window.webkit.messageHandlers.idmeNative.postMessage({
9
      action: "openAppSettings",
10
      permission: "camera"
11
    });
12
    return true;
13
  }
14
15
  return false;
16
}

Verification stages and permissions

Each camera-based verification stage should request or confirm permission before starting capture.

Document upload behavior

Document upload may ask the user to capture the front and back of an identity document. Depending on the ID.me policy, the verification workflow either allows current-device upload or requires live capture.

When current-device upload is allowed:

• The user may take a new photo or select an existing image, depending on the platform file chooser.
• Your native app must still handle WebView file chooser callbacks.

When live capture is required:

• Request camera permission before opening the camera.
• Prefer the rear-facing camera for document capture.
• Do not intentionally present the photo gallery as the primary path.
• Keep the user in the verification workflow after a denied permission and provide a retry or settings path.

QA checklist

Test each supported platform and app shell before launch:

• Android WebView with camera permission granted.
• Android WebView with camera permission denied once, then granted on retry.
• Android WebView with camera permission permanently denied and app settings opened.
• Android WebView with camera permission disabled in app settings, then re-checked before the next capture attempt.
• Android WebView document capture with output URI read and write grants.
• Android WebView liveness or selfie capture with permission granted and denied.
• iOS WebView with camera permission granted.
• iOS WebView with camera permission denied and app settings opened.
• iOS WebView with camera permission disabled in app settings, then re-checked before the next capture attempt.
• iOS WebView document file input opened directly from a user tap.
• iOS WebView liveness or selfie capture with permission granted and denied.
• Browser iframe with allow="camera; microphone; fullscreen".
• Browser iframe with a restrictive Permissions-Policy header tested and corrected.
• Document upload policies that require live camera capture.
• Document upload policies that allow current-device upload.
• Final OAuth redirect handling after verification completes.