Background: For all customers integrating DiDi BNPL H5, the container configuration must be aligned to avoid unexpected issues when launching the DiDi H5 page, which could otherwise affect the Merchant's transaction success rate.

Supported environments: iOS native and Android native only. Not applicable to web versions, Linux, or other Windows systems. The intended audience of this document is the Merchant App's web-container configuration and check methods.

What "container" means here: In this document, "container" refers to the way the Merchant App opens web pages:

Android WebView / Custom Tabs, or
iOS WKWebView / SFSafariViewController.

1. Android App Self-Check: Code and Configuration Check

Only check the Activity/Fragment that actually hosts our H5 — do not just look at the public WebView base class or template code. First confirm the container type, then check the corresponding subsection.

1.1 Confirm the Container Type First

Check item	How to check	Result
Container	Confirm whether the entry uses Android WebView or Custom Tabs	Record the container type, entry Activity/Fragment, and App version
If WebView	Continue with 1.2–1.5	The App's WebView code and configuration must be checked
If Custom Tabs	Skip to 1.6	Do not check the Merchant App's WebSettings/WebChromeClient

Note: Based on historical reports from different providers, Custom Tabs may trigger external redirection, causing flow anomalies. Custom Tabs is not recommended.

1.2 System and Web Permissions

Check item	How to check	Pass criteria
App camera permission	Inspect the final merged Manifest; check runtime permissions on Android 6 / API 23+	CAMERA is present, and its runtime state is granted in real-device testing
Web camera permission	Inspect the final WebChromeClient.onPermissionRequest; record request.getOrigin() and request.getResources() during integration testing	The actual face page origin is within the allowlist; only RESOURCE_VIDEO_CAPTURE is granted; do not unconditionally allow all resources
Microphone (only when an audio request appears)	Whether the Ali SDK uses the microphone cannot be preset; only check RECORD_AUDIO and web authorization when AUDIO_CAPTURE appears in the onPermissionRequest() resource list	Do not request the microphone when AUDIO_CAPTURE is absent; grant it only for the actual face page origin once it appears

1.3 WebView Basic Configuration

Check item	How to check	Pass criteria
JavaScript	Inspect the final WebSettings, not just the init defaults	javaScriptEnabled == true
DOM Storage	Inspect the final WebSettings	domStorageEnabled == true

Check item	How to check	Pass criteria
HTTPS address	Inspect the initial, final and redirected URLs in onPageStarted, shouldOverrideUrlLoading, onReceivedError, or via WebView remote-debugging Network	Page requests use https://; no HTTP downgrade, certificate error, or SSL error
Page navigation / resources	Check WebViewClient URL interception, resource interception, and the domain allowlist; inspect Network requests during integration testing	Do not block the face page, cross-origin iframes, HTTPS redirects, or necessary resources
IME: screen push-up	Check whether the parameter is set correctly	windowSoftInputMode="adjustUnspecified\|stateHidden"

1.5 Page Lifecycle and Version

Check item	How to check	Pass criteria
Page lifecycle	Check handling of backgrounding, back, rotation, tab switching, and exit	The WebView must not be actively refreshed, destroyed, or replaced during face verification
WebView version	Read WebView.getCurrentWebViewPackage() at runtime	Provide the provider package name, version, and Android system version

1.6 Android Custom Tabs (Not Recommended)

Custom Tabs is hosted by a browser provider; the Merchant App usually cannot read or modify the WebChromeClient, WebSettings, or media callbacks of its internal WebView.

What needs to be confirmed:

The browser/provider used, its version, and the Android system version;
System camera permission and browser permission are available;
The HTTPS page and the real face-verification flow can be completed.

Do not require Custom Tabs to provide onPermissionRequest logs of a self-built WebView.

2. iOS App Self-Check: Code and Configuration Check

Only check the ViewController/WKWebView that actually hosts our H5.

First confirm the container type, then check the corresponding subsection.

2.1 Confirm the Container Type First

Check item	How to check	Result
Container	Confirm whether the entry uses a self-built WKWebView or SFSafariViewController	Record the container type, ViewController, and App version
If WKWebView	Continue with 2.2–2.5	The App's WKWebView code and configuration must be checked
If SFSafariViewController	Skip to 2.6	Do not check the Merchant App's WKWebView internal configuration

2.2 System and Web Permissions

Check item	How to check	Pass criteria
Camera declaration	Inspect the final App's Info.plist	NSCameraUsageDescription is present with a valid description
Camera authorization	Check system settings and the first authorization result on a real device	Camera permission is allowed
Media permission callback	Check whether requestMediaCapturePermissionForOrigin (iOS 15+) is implemented	If implemented, the camera request for the actual face page origin must not be denied; must not be rejected by other interception logic
Microphone (only when an audio request appears)	Whether the Ali SDK uses the microphone cannot be preset; only check NSMicrophoneUsageDescription and system authorization when the media permission callback's request type includes microphone	Do not request the microphone when no microphone request appears; grant the actual face page's microphone only after it appears

2.3 Video Display Configuration

Check item	How to check	Pass criteria
Inline playback	Inspect the code that creates WKWebViewConfiguration	Set allowsInlineMediaPlayback = YES before creating the WKWebView

Check item	How to check	Pass criteria
HTTPS address	Inspect the initial, final and redirected URLs in WKNavigationDelegate callbacks or Safari Web Inspector	Page requests use https://; no HTTP downgrade, certificate error, or load failure
Navigation and resources	Check navigationDelegate, URL allowlist, redirect and iframe policies	Do not block the face page, HTTPS redirects, or necessary resources

2.5 Page Lifecycle and Version

Check item	How to check	Pass criteria
Page lifecycle	Check back, backgrounding, rotation, and exit handling	The WKWebView must not be actively refreshed, destroyed, or replaced during face verification
Version	Record the iOS system version and App version	Real-time camera is verified on real devices running iOS 14.3+; lower versions cannot be guaranteed

2.6 iOS SFSafariViewController

The internal page of SFSafariViewController is hosted by the system browser; the Merchant App cannot configure allowsInlineMediaPlayback, WKUIDelegate, or internal media callbacks. The Merchant only needs to provide the system version and App version and complete the real face-verification acceptance; if the screen behaves abnormally, troubleshoot by system browser/version and the actual observed behavior.

3. Merchant App JSBridge Environment Information (Suggested)

JSBridge is not a hard requirement for the H5 to open and complete authentication.

However, DiDi strongly recommends that the Merchant App implement JSBridge to provide a stable method that lets the DiDi H5 quickly read the native container parameters when a problem occurs, for fast diagnosis.

Android and iOS use the same return structure; the H5 does not need to parse two different formats.

3.1 Applicable Stage

Before face verification: the DiDi H5 obtains the Merchant App information.

The Merchant App native layer sets up JSBridge so that the DiDi H5 can obtain container-related information, enabling fast problem localization when issues occur, helping the Merchant App resolve them, and improving PSR.

H5 (DiDi)  --calls JSBridge-->  Merchant App native layer
           <--returns JSON--   (container type / system version / permission status / WebView version ...)

3.2 Unified Return Format

Android example:

{
  "code": "OK",
  "data": {
    "system": "Android",
    "systemVersion": "15",
    "appVersion": "1.1",
    "containerType": "WEBVIEW",
    "permissions": {
      "camera": {
        "native": "GRANTED",
        "web": "GRANTED"
      },
      "microphone": {
        "native": "NOT_REQUESTED",
        "web": "NOT_REQUESTED"
      }
    },
    "webView": {
      "provider": "com.google.android.webview",
      "version": "131.0.6778.81"
    },
    "webViewConfig": {
      "javaScriptEnabled": true,
      "domStorageEnabled": true,
      "allowsInlineMediaPlayback": null,
      "mediaPlaybackRequiresUserGesture": true
    }
  }
}

The same structure is used for iOS:

{
  "code": "OK",
  "data": {
    "system": "iOS",
    "systemVersion": "26.0",
    "appVersion": "1.1",
    "containerType": "WKWEBVIEW",
    "permissions": {
      "camera": {
        "native": "GRANTED",
        "web": "GRANTED"
      },
      "microphone": {
        "native": "NOT_REQUESTED",
        "web": "NOT_REQUESTED"
      }
    },
    "webView": {
      "provider": "WKWebView",
      "version": "26.0"
    },
    "webViewConfig": {
      "javaScriptEnabled": true,
      "domStorageEnabled": true,
      "allowsInlineMediaPlayback": true,
      "mediaPlaybackRequiresUserGesture": null
    }
  }
}

3.3 Fields and States

Field	Meaning
code	Bridge call result; returns OK on success, or a clear error code on failure; does not indicate camera permission result
system / systemVersion	System name and system version
appVersion	Merchant App version
containerType	WEBVIEW, WKWEBVIEW, CUSTOM_TABS, or SFSafariViewController
permissions.camera.native	App native camera permission
permissions.camera.web	Latest result of the web camera media permission
permissions.microphone.native	App native microphone permission
permissions.microphone.web	Latest result of the web microphone media permission
webView.provider / webView.version	Provider and version of the WebView or system web container
webViewConfig	The web configuration actually in effect; fields not applicable to the platform return null

Permission states uniformly use: GRANTED, DENIED, NOT_REQUESTED, UNKNOWN, NOT_APPLICABLE.

3.4 Platform Boundaries

allowsInlineMediaPlayback is an iOS WKWebView configuration; Android has no same-named configuration and returns null — do not fabricate a value.
mediaPlaybackRequiresUserGesture is mainly used on Android; on iOS where it is not applicable, return null.
For CUSTOM_TABS and SFSafariViewController, WebView configurations and web permissions that cannot be read return UNKNOWN or NOT_APPLICABLE.
The Bridge query must not actively request permissions, pop up dialogs, or invoke the camera.
The environment query in 3.2 only returns the container, version, and permission status.
The JSBridge method name, invocation method, and async callback method are agreed between the two parties during integration.

4. Final Outcome

4.1 The Final Outcome to Achieve

This section does not require reviewing code. After embedding our H5 into the merchant's App, the following outcomes must be achieved.

On-site Check	How to Check	Pass Criteria
H5 can open	Open our H5 entry point inside the third-party App	The page renders, buttons are clickable, no white screen or endless loading spinner
Page address is secure (HTTPS)	If the page has an address bar, the address starts with https://; if it is an embedded page without an address bar, the RD checks the initial address, final address, and redirect addresses per Sections 2/3	All page addresses are https://, with no pages redirecting to http://
Camera can be used	Tap "Start Face Scan" and allow the system camera permission	The live camera feed is visible
Both the feed and prompts are visible	After the camera feed appears, check whether the action prompts remain visible on the same page	No full-screen overlay blocks prompts such as "Please blink"
Result can be returned	Complete one success, one permission denial, and one manual exit respectively	The H5 can display a success or failure result, with no white screen and no infinite loop

4.2 Review of the Merchant App Container Environment's Current State

This section does not make a pass/fail judgment; it only records the actual behavior of our H5's face flow when interacting with camera permissions in the merchant's App, as a basis for subsequent troubleshooting and adaptation. Please test each item and fill it in truthfully, marking unknown items as "To be confirmed"; record iOS and Android, and different containers, separately.

Review Item	Current State to Record
Camera permission status	The permission state when entering the face flow: already authorized, not yet requested, already denied, or restricted by the system; if web permissions are involved, record the web authorization status separately
In-app handling when permission is missing	Whether the system permission dialog can be triggered, and whether it is triggered by the App, the web page, or the browser container; the prompts and subsequent actions after the user allows or denies
Handling when a jump-out is required	Whether a jump to the system settings page is needed; whether it is a button-triggered jump or a manual entry by the user; what operations the user must complete; and whether they can return to the original face page
Flow continuation after returning	After returning to the App, whether permissions are re-checked, and whether the original flow continues, re-captures, or restarts; how to prompt or exit when the user has denied and the dialog cannot be shown again, or when the system imposes a restriction

Please test the three scenarios separately — "first-time not authorized", "re-entry after denial", and "return after authorizing in the settings page" — recording the operation steps and whether the flow jumps out of the current App/container, to avoid judging the actual experience solely by "camera permission is supported".

Documentation