Contexto: Para todos los clientes que integren DiDi BNPL H5, es necesario alinear la configuración del contenedor a fin de evitar problemas imprevistos al abrir la página H5 de DiDi, que podrían afectar la tasa de éxito de las transacciones del Merchant.

Entornos soportados: Solo iOS nativo y Android nativo. No aplica a la versión web, Linux u otros sistemas Windows. Este documento está dirigido a la configuración del contenedor web de la Merchant App y a sus métodos de verificación.

Qué significa "contenedor" aquí: En este documento, "contenedor" se refiere a la forma en que la Merchant App abre páginas web:

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

1. Autocomprobación de la App Android: verificación de código y configuración

Verifique únicamente el Activity/Fragment que realmente aloja nuestro H5; no revise solo la clase base o el código de plantilla del WebView público. Primero confirme el tipo de contenedor y luego verifique la subsección correspondiente.

1.1 Confirmar primero el tipo de contenedor

Elemento a verificar	Cómo verificar	Resultado
Contenedor	Confirme si la entrada utiliza Android WebView o Custom Tabs	Registre el tipo de contenedor, el Activity/Fragment de entrada y la versión de la App
Si es WebView	Continúe con 1.2–1.5	Se debe verificar el código y la configuración del WebView de la App
Si es Custom Tabs	Salte a 1.6	No verifique el WebSettings/WebChromeClient de la Merchant App

Nota: Según el historial reportado por distintos proveedores, Custom Tabs puede provocar redirección externa y causar anomalías en el flujo; no se recomienda usar Custom Tabs.

1.2 Permisos del sistema y de la web

Elemento a verificar	Cómo verificar	Criterio de aprobación
Permiso de cámara de la App	Revise el Manifest final combinado; verifique los permisos en tiempo de ejecución en Android 6 / API 23+	CAMERA está presente y su estado en pruebas reales es granted
Permiso de cámara web	Revise el WebChromeClient.onPermissionRequest final; registre request.getOrigin() y request.getResources() durante la integración	El origin real de la página facial está dentro del rango permitido; solo se concede RESOURCE_VIDEO_CAPTURE; no se deben autorizar todos los recursos incondicionalmente
Micrófono (solo cuando aparece una solicitud de audio)	No se puede presuponer si el SDK de Ali usa el micrófono; solo verifique RECORD_AUDIO y la autorización web cuando AUDIO_CAPTURE aparezca en la lista de recursos de onPermissionRequest()	No solicite el micrófono cuando AUDIO_CAPTURE está ausente; concédalo solo para el origin real de la página facial una vez que aparezca

1.3 Configuración básica del WebView

Elemento a verificar	Cómo verificar	Criterio de aprobación
JavaScript	Revise el WebSettings final, no solo los valores por defecto de inicialización	javaScriptEnabled == true
DOM Storage	Revise el WebSettings final	domStorageEnabled == true

1.4 URL de la página, navegación y funciones

Elemento a verificar	Cómo verificar	Criterio de aprobación
Dirección HTTPS	Revise las URL inicial, final y redirigida en onPageStarted, shouldOverrideUrlLoading, onReceivedError o en Network de la depuración remota del WebView	Las solicitudes de la página usan https://; sin degradación a HTTP, error de certificado o error SSL
Navegación / recursos de la página	Verifique la interceptación de URL, la interceptación de recursos y la lista blanca de dominios de WebViewClient; revise las solicitudes de Network durante la integración	No bloquee la página facial, los iframes de origen cruzado, las redirecciones HTTPS ni los recursos necesarios
IME: empuje de pantalla	Verifique si el parámetro está configurado correctamente	windowSoftInputMode="adjustUnspecified\|stateHidden"

1.5 Ciclo de vida de la página y versión

Elemento a verificar	Cómo verificar	Criterio de aprobación
Ciclo de vida de la página	Verifique el manejo al pasar a segundo plano, retroceder, rotar, cambiar de pestaña y salir	El WebView no debe ser actualizado, destruido ni reemplazado activamente durante la verificación facial
Versión del WebView	Lea WebView.getCurrentWebViewPackage() en tiempo de ejecución	Proporcione el nombre del paquete del proveedor, la versión y la versión del sistema Android

1.6 Android Custom Tabs (no recomendado)

Custom Tabs está alojado por un proveedor de navegador; la Merchant App normalmente no puede leer ni modificar el WebChromeClient, el WebSettings ni las devoluciones de llamada de medios de su WebView interno.

Lo que debe confirmarse:

El navegador/proveedor utilizado, su versión y la versión del sistema Android;
El permiso de cámara del sistema y el permiso del navegador están disponibles;
La página HTTPS y el flujo real de verificación facial pueden completarse.

No exija que Custom Tabs proporcione registros onPermissionRequest de un WebView propio.

2. Autocomprobación de la App iOS: verificación de código y configuración

Verifique únicamente el ViewController/WKWebView que realmente aloja nuestro H5.

Primero confirme el tipo de contenedor y luego verifique la subsección correspondiente.

2.1 Confirmar primero el tipo de contenedor

Elemento a verificar	Cómo verificar	Resultado
Contenedor	Confirme si la entrada utiliza un WKWebView propio o SFSafariViewController	Registre el tipo de contenedor, el ViewController y la versión de la App
Si es WKWebView	Continúe con 2.2–2.5	Se debe verificar el código y la configuración del WKWebView de la App
Si es SFSafariViewController	Salte a 2.6	No verifique la configuración interna del WKWebView de la Merchant App

2.2 Permisos del sistema y de la web

Elemento a verificar	Cómo verificar	Criterio de aprobación
Declaración de cámara	Revise el Info.plist final de la App	NSCameraUsageDescription está presente con un texto válido
Autorización de cámara	Verifique la configuración del sistema y el primer resultado de autorización en un dispositivo real	El permiso de cámara está permitido
Devolución de llamada de permiso de medios	Verifique si se implementa requestMediaCapturePermissionForOrigin (iOS 15+)	Si está implementada, la solicitud de cámara del origin real de la página facial no debe ser denegada; no debe rechazarse mediante otra lógica de interceptación
Micrófono (solo cuando aparece una solicitud de audio)	No se puede presuponer si el SDK de Ali usa el micrófono; solo verifique NSMicrophoneUsageDescription y la autorización del sistema cuando el tipo de solicitud de la devolución de llamada de permiso de medios incluya microphone	No solicite el micrófono cuando no aparece ninguna solicitud; conceda el micrófono de la página facial real solo después de que aparezca

2.3 Configuración de visualización de video

Elemento a verificar	Cómo verificar	Criterio de aprobación
Reproducción en línea	Revise el código que crea WKWebViewConfiguration	Configure allowsInlineMediaPlayback = YES antes de crear el WKWebView

2.4 URL de la página, navegación y recursos

Elemento a verificar	Cómo verificar	Criterio de aprobación
Dirección HTTPS	Revise las URL inicial, final y redirigida en las devoluciones de llamada de WKNavigationDelegate o en Safari Web Inspector	Las solicitudes de la página usan https://; sin degradación a HTTP, error de certificado o fallo de carga
Navegación y recursos	Verifique navigationDelegate, la lista blanca de URL, las políticas de redirección e iframe	No bloquee la página facial, las redirecciones HTTPS ni los recursos necesarios

2.5 Ciclo de vida de la página y versión

Elemento a verificar	Cómo verificar	Criterio de aprobación
Ciclo de vida de la página	Verifique el manejo de retroceso, segundo plano, rotación y salida	El WKWebView no debe ser actualizado, destruido ni reemplazado activamente durante la verificación facial
Versión	Registre la versión del sistema iOS y la versión de la App	La cámara en tiempo real se verifica en dispositivos reales con iOS 14.3+; no se puede garantizar el soporte de versiones inferiores

2.6 iOS SFSafariViewController

La página interna de SFSafariViewController está alojada por el navegador del sistema; la Merchant App no puede configurar allowsInlineMediaPlayback, WKUIDelegate ni las devoluciones de llamada de medios internas. El Merchant solo necesita proporcionar la versión del sistema y la versión de la App y completar la aceptación de la verificación facial real; si la pantalla se comporta de forma anómala, investigue según el navegador/versión del sistema y el comportamiento observado.

3. Información de entorno JSBridge de la Merchant App (sugerida)

JSBridge no es un requisito obligatorio para que el H5 se abra y complete la autenticación.

Sin embargo, DiDi recomienda encarecidamente que la Merchant App implemente JSBridge para proporcionar un método estable que permita al H5 de DiDi leer rápidamente los parámetros del contenedor nativo cuando ocurra un problema, para un diagnóstico rápido.

Android e iOS usan la misma estructura de retorno; el H5 no necesita analizar dos formatos distintos.

3.1 Etapa aplicable

Antes de la verificación facial: el H5 de DiDi obtiene la información de la Merchant App.

La capa nativa de la Merchant App configura JSBridge para que el H5 de DiDi pueda obtener la información relacionada con el contenedor, lo que permite una localización rápida de problemas cuando surjan, ayuda a la Merchant App a resolverlos y mejora el PSR.

H5 (DiDi)  --llama a JSBridge-->  Capa nativa de la Merchant App
           <--devuelve JSON--    (tipo de contenedor / versión del sistema / estado de permisos / versión del WebView ...)

3.2 Formato de retorno unificado

Ejemplo de 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
    }
  }
}

La misma estructura se usa para 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 Campos y estados

Campo	Significado
code	Resultado de la llamada del Bridge; devuelve OK en caso de éxito, o un código de error claro en caso de fallo; no indica el resultado del permiso de cámara
system / systemVersion	Nombre y versión del sistema
appVersion	Versión de la Merchant App
containerType	WEBVIEW, WKWEBVIEW, CUSTOM_TABS o SFSafariViewController
permissions.camera.native	Permiso de cámara nativo de la App
permissions.camera.web	Último resultado del permiso de medios de cámara web
permissions.microphone.native	Permiso de micrófono nativo de la App
permissions.microphone.web	Último resultado del permiso de medios de micrófono web
webView.provider / webView.version	Proveedor y versión del WebView o del contenedor web del sistema
webViewConfig	La configuración web realmente en vigor; los campos no aplicables a la plataforma devuelven null

Los estados de permisos usan uniformemente: GRANTED, DENIED, NOT_REQUESTED, UNKNOWN, NOT_APPLICABLE.

3.4 Límites de plataforma

allowsInlineMediaPlayback es una configuración del WKWebView de iOS; Android no tiene una configuración con el mismo nombre y devuelve null — no fabrique un valor.
mediaPlaybackRequiresUserGesture se usa principalmente en Android; en iOS, donde no aplica, devuelva null.
Para CUSTOM_TABS y SFSafariViewController, las configuraciones del WebView y los permisos web que no se puedan leer devuelven UNKNOWN o NOT_APPLICABLE.
La consulta del Bridge no debe solicitar permisos activamente, mostrar diálogos ni invocar la cámara.
La consulta de entorno de 3.2 solo devuelve el contenedor, la versión y el estado de los permisos.
El nombre del método JSBridge, la forma de invocación y la forma de devolución de llamada asíncrona se acuerdan entre ambas partes durante la integración.

4. Resultado final

4.1 El resultado final que se debe lograr

Esta sección no requiere revisar el código. Después de integrar nuestro H5 en la App del comercio, se deben lograr los siguientes resultados.

Comprobación in situ	Cómo verificarlo	Criterio de aprobación
El H5 se puede abrir	Abrir el punto de entrada de nuestro H5 dentro de la App de terceros	La página se muestra, los botones se pueden pulsar, no hay pantalla en blanco ni carga infinita
Dirección de página segura (HTTPS)	Si la página tiene barra de direcciones, la dirección empieza por https://; si es una página embebida sin barra de direcciones, el RD revisa la dirección inicial, la dirección final y las direcciones de redirección según las secciones 2/3	Todas las direcciones de página son https://, sin páginas que redirijan a http://
Se puede usar la cámara	Pulsar "Iniciar reconocimiento facial" y conceder el permiso de cámara del sistema	Se ve la imagen de la cámara en tiempo real
La imagen y los avisos son visibles	Tras aparecer la imagen de la cámara, observar si los avisos de acción siguen visibles en la misma página	Ningún elemento a pantalla completa tapa avisos como "Por favor, parpadee"
El resultado se puede devolver	Completar respectivamente un caso de éxito, uno de permiso denegado y uno de salida manual	El H5 puede mostrar el resultado de éxito o fracaso, sin pantalla en blanco ni bucle infinito

4.2 Análisis del estado actual del entorno del contenedor de la App del comercio

Esta sección no emite un juicio de aprobado/no aprobado; solo registra el comportamiento real del flujo facial de nuestro H5 al interactuar con los permisos de cámara en la App del comercio, como base para la posterior resolución de problemas y adaptación. Por favor, pruebe cada punto y regístrelo con veracidad, marcando los puntos desconocidos como "Por confirmar"; registre iOS y Android, y los distintos contenedores, por separado.

Punto a analizar	Estado actual a registrar
Estado del permiso de cámara	El estado del permiso al entrar en el flujo facial: ya autorizado, aún no solicitado, ya denegado o restringido por el sistema; si implica permisos web, registrar por separado el estado de autorización web
Gestión en la App cuando falta el permiso	Si se puede invocar el cuadro de diálogo de permisos del sistema, y si lo activa la App, la página web o el contenedor del navegador; los avisos y acciones posteriores después de que el usuario permita o deniegue
Gestión cuando se requiere salir	Si es necesario saltar a la página de ajustes del sistema; si el salto se activa con un botón o el usuario entra manualmente; qué operaciones debe completar el usuario; y si puede volver a la página facial original
Continuación del flujo tras volver	Después de volver a la App, si se vuelven a comprobar los permisos, y si el flujo original continúa, vuelve a capturar o se reinicia; cómo avisar o salir cuando el usuario ha denegado y el cuadro de diálogo no puede mostrarse de nuevo, o cuando el sistema impone una restricción

Por favor, pruebe por separado los tres escenarios — "sin autorizar por primera vez", "reingreso tras la denegación" y "regreso tras autorizar en la página de ajustes" — registrando los pasos de la operación y si el flujo sale de la App/contenedor actual, para evitar juzgar la experiencia real basándose únicamente en que "el permiso de cámara es compatible".

Documentos