背景说明:对于所有接入DiDI BNPL H5的客户,都需要对齐容器的配置,以免在唤起DiDi H5页面的时候出现不可预计的问题,影响Merchant的交易成功率。
适配环境:仅仅适配iOS原生和Android 原生,不适用于网页版、Linux系统、或者其他Windows系统。本文档的使用对象,Merchant App 只提供的网页承载配置和检查方法。
"容器"的说明:本文所说的"容器",就是Merchant App 内打开网页的方式:
- Android WebView/Custom Tabs,或
- iOS WKWebView/SFSafariViewController。
1. Android APP 自检:代码和配置检查
只检查实际承载我方 H5 的 Activity/Fragment,不要只看公共 WebView 基类或模板代码。先确认容器类型,再按对应小节检查。
1.1 先确认容器类型
注:根据不同供应商反应的历史,Custom Tabs存在外跳的情况,导致流程异常,不建议适用Custom Tabs。
1.2 系统和网页权限
1.3 WebView 基础配置
1.4 页面地址、跳转和功能
1.5 页面生命周期和版本
1.6 Android Custom Tabs(不推荐)
Custom Tabs 由浏览器 provider 承载,Merchant App 通常不能读取或修改其内部 WebView 的 WebChromeClient、WebSettings 或媒体回调。
需要确认:
- 使用的浏览器/provider、版本和 Android 系统版本;
- 系统相机权限和浏览器权限可用;
- HTTPS 页面和真实人脸流程可完成。
不要要求 Custom Tabs 提供自建 WebView 的 onPermissionRequest 日志。
2. iOS APP 自检:代码和配置检查
只检查实际承载我方 H5 的 ViewController/WKWebView。
先确认容器类型,再按对应小节检查。
2.1 先确认容器类型
2.2 系统和网页权限
2.3 视频显示配置
2.4 页面地址、跳转和资源
2.5 页面生命周期和版本
2.6 iOS SFSafariViewController
SFSafariViewController 的内部页面由系统浏览器承载,Merchant App 不能配置 allowsInlineMediaPlayback、WKUIDelegate 或内部媒体回调。Merchant只需提供系统版本、App 版本并完成真实人脸验收;若画面异常,按系统浏览器/版本和真实现象排查。
3. Merchant App JSBridge 环境信息(Suggested)
JSBridge 不是 H5 正常打开和完成认证的硬性条件。
但DiDi侧强烈建议Merchant App 完成JSBridge,提供一个稳定的方法,让 DiDi H5 在出现问题,可快速读取原生容器参数,进行问题的快速诊断。
Android 和 iOS 使用同一套返回结构,H5 不需要分别解析两种格式。
3.1 适用环节说明
人脸验证之前:DiDi H5获取Merchant APP信息。
Merchant APP原生层设定JSBridge,用于DiDi H5获得容器的相关信息,以便在出现问题时进行快速问题定位,协助Merchant APP解决问题,并提升PSR。
H5 (DiDi) --调用 JSBridge--> Merchant App 原生层
<--返回 JSON-- (容器类型/系统版本/权限状态/WebView版本...)
3.2 统一返回格式
Android 示例:
{
"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
}
}
}
同一结构用于 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 字段和状态
权限状态统一使用:GRANTED、DENIED、NOT_REQUESTED、UNKNOWN、NOT_APPLICABLE。
3.4 平台边界
allowsInlineMediaPlayback是 iOS WKWebView 配置;Android 没有同名配置,返回null,不要伪造值。mediaPlaybackRequiresUserGesture主要用于 Android;iOS 不适用时返回null。CUSTOM_TABS和SFSafariViewController无法读取的 WebView 配置和网页权限返回UNKNOWN或NOT_APPLICABLE。- Bridge 查询不得主动申请权限、弹窗或调用摄像头。
- 3.2 的环境查询只返回容器、版本和权限状态;
- JSBridge 方法名、调用方式和异步回调方式由双方接入时约定。
4. 最终效果
4.1 最终要达到的效果
这一节不需要看代码。把我方 H5 放进商户的 App 后，需要达到如下的效果。
4.2 商户APP容器环境现状梳理
本节不做通过/不通过判定，只记录我方 H5 的人脸流程在该商户 App 中与相机权限交互的真实表现，作为后续排错与适配的依据。请逐项实测并如实填写,未知项标记"待确认";iOS 与 Android、不同容器分别记录。
请分别实测"首次未授权""拒绝后再次进入""设置页授权后返回"三种场景,记录操作步骤及是否跳出当前 App/容器,避免仅凭"支持相机权限"判断实际体验。