Saltar al contenido principal
Esta guía explica cómo integrar LiveForm como un WebView en la app móvil del cliente. Audiencia: Ingenieros móviles que integran LiveForm en una app iOS o Android existente.

Objetivos de Implementación

La app del cliente debe implementar el siguiente flujo:
  1. Construir la URL de LiveForm usando el pid recibido del servidor o de la app del cliente.
  2. Verificar los permisos de la app requeridos por LiveForm antes de abrir el WebView.
  3. Abrir la URL de LiveForm en un WebView a pantalla completa.
  4. Configurar el WebView para soportar captura de cámara, subida de imágenes, cookies y navegación a enlaces externos.

Versiones Soportadas y Requisitos Mínimos

LiveForm es una aplicación web basada en HTTPS. El WebView de la app debe soportar completamente las funciones modernas del navegador, permisos de cámara, selección de archivos y cookie/storage.
PlataformaMínimoRecomendadoNotas
iOSiOS 15+iOS 16+iOS 15+ soporta el callback de permiso de captura de medios de WKUIDelegate para restringir los permisos al host de LiveForm.
AndroidAndroid 9, API 28+Android 10, API 29+Usar la versión más reciente de Android System WebView o Chrome para mayor estabilidad en selección de archivos y captura con cámara.
Android WebViewAndroid System WebView o Chrome actualizablesAndroid System WebView o Chrome más recienteLa selección de archivos, captura con cámara y el comportamiento de cookies/storage pueden verse afectados por la versión de WebView/Chrome.
React Nativereact-native-webview 13.x+Última versión estableLas apps nativas pueden implementar la misma funcionalidad directamente usando WKWebView/Android WebView.
Alcance de las pruebas en dispositivos reales:
  • Verificar el flujo completo en Android 9 (API 28)+: instalación de la app, carga del WebView, selección de archivos, captura con cámara, cookie/storage.
  • Verificar el flujo completo en iOS 15+: selección de archivos en WKWebView, captura con cámara, cookie/storage.
  • La aprobación final requiere completar un envío real de LiveForm — captura con cámara, subida, envío y navegación a returnUrl/deep link.

URL de LiveForm

La app del cliente utiliza únicamente el host de producción de LiveForm. El pid se pasa como parámetro de consulta.
https://form.argosidentity.com?pid={pid}
Siempre aplica URL-encode al pid antes de insertarlo en la URL.
La app no necesita distinguir entre hosts ni rutas de tipo de formulario — el pid identifica de forma única la sesión de LiveForm.

Permisos de la App

LiveForm utiliza la cámara y la función de subida de imágenes dentro del WebView. Al ejecutar LiveForm como WebView en una app móvil, la app del cliente debe obtener los permisos de acceso a la cámara y a los archivos antes de abrir el WebView — permisos que normalmente gestiona el navegador.
Solicitar y verificar los permisos de cámara y de la biblioteca de fotos (o medios) a nivel de app antes de abrir el WebView es obligatorio. Si los permisos requeridos no están concedidos, la captura con cámara o la subida de imágenes de LiveForm puede no funcionar — no abrir el WebView en ese estado.
Añadir las siguientes descripciones de uso en Info.plist:
<key>NSCameraUsageDescription</key>
<string>Se requiere acceso a la cámara para la captura de documentos de identidad en LiveForm.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Se requiere acceso a la biblioteca de fotos para subir imágenes en LiveForm.</string>

Flujo de Integración Requerido

Acción del usuario
  └─ La app del cliente inicia LiveForm
      └─ Construir URL de LiveForm a partir del pid

Antes de abrir el WebView
  ├─ Verificar permiso de cámara
  ├─ Verificar permiso de biblioteca de fotos/medios
  └─ Abrir WebView a pantalla completa

Dentro del WebView
  ├─ Permitir JavaScript y DOM storage
  ├─ Permitir cookies
  ├─ Permitir reproducción de medios en línea y captura de medios
  ├─ Cargar URLs http/https/data/about dentro del WebView
  └─ Reenviar esquemas personalizados a apps externas
No abrir el WebView si la URL no es válida o las verificaciones de permisos no han finalizado.

Configuración del WebView

El WebView debe permitir JavaScript, storage, cookies, reproducción de medios y captura de medios.
Al usar react-native-webview, los detalles del WebChromeClient (Android) y WKUIDelegate (iOS) subyacentes son gestionados por la capa nativa de la librería. Configurar las props del WebView indicadas a continuación y verificar las listas de verificación de Android e iOS por separado en dispositivos reales.
import { Linking } from 'react-native';
import { WebView } from 'react-native-webview';

function openExternalUrl(url: string) {
  Linking.canOpenURL(url)
    .then((supported) => {
      if (supported) return Linking.openURL(url);
      return undefined;
    })
    .catch(() => undefined);
}

export function LiveFormWebView({ url }: { url: string }) {
  return (
    <WebView
      source={{ uri: url }}
      originWhitelist={['*']}
      javaScriptEnabled
      domStorageEnabled
      sharedCookiesEnabled
      thirdPartyCookiesEnabled
      allowsInlineMediaPlayback
      mediaPlaybackRequiresUserAction={false}
      mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
      allowsFullscreenVideo
      allowFileAccess
      mixedContentMode="compatibility"
      setSupportMultipleWindows={false}
      onOpenWindow={({ nativeEvent }) => {
        if (nativeEvent.targetUrl) openExternalUrl(nativeEvent.targetUrl);
      }}
      onShouldStartLoadWithRequest={({ url: nextUrl }) => {
        if (
          nextUrl === 'about:blank' ||
          nextUrl.startsWith('about:') ||
          nextUrl.startsWith('data:') ||
          nextUrl.startsWith('http://') ||
          nextUrl.startsWith('https://')
        ) {
          return true;
        }

        openExternalUrl(nextUrl);
        return false;
      }}
    />
  );
}
Referencia de Configuraciones Clave
ConfiguraciónRazón
javaScriptEnabledLiveForm se ejecuta como aplicación web.
domStorageEnabledPermite que LiveForm use el storage del navegador.
sharedCookiesEnabled / thirdPartyCookiesEnabledMantiene el comportamiento de cookies similar a un navegador estándar.
allowsInlineMediaPlaybackPermite que la interfaz de medios funcione dentro del WebView donde sea compatible.
mediaCapturePermissionGrantTypeHabilita el manejo de permisos de captura de medios para el host de LiveForm.
setSupportMultipleWindows={false}Mantiene los flujos de nueva ventana dentro de la ruta WebView controlada por la app.
onShouldStartLoadWithRequestReenvía esquemas personalizados desconocidos a apps externas para que no rompan el WebView.

Constructor de URL de LiveForm

const LIVE_FORM_ORIGIN = 'https://form.argosidentity.com';

export function buildLiveFormUrl(pid: string) {
  return `${LIVE_FORM_ORIGIN}?pid=${encodeURIComponent(pid.trim())}`;
}

Ejemplo de Solicitud de Permisos (Expo/React Native)

import * as ImagePicker from 'expo-image-picker';

export async function requestLiveFormPermissions() {
  const camera = await ImagePicker.requestCameraPermissionsAsync();
  const mediaLibrary = await ImagePicker.requestMediaLibraryPermissionsAsync();

  return {
    granted: camera.granted && mediaLibrary.granted,
    camera,
    mediaLibrary,
  };
}
Si el permiso es denegado:
  • No abrir el WebView.
  • Mostrar un mensaje explicando que se requieren permisos de cámara y biblioteca de fotos para la captura y subida de LiveForm.
  • Proporcionar un botón para navegar a la pantalla de configuración de la app.

Diseño a Pantalla Completa

LiveForm funciona mejor cuando ocupa la mayor parte posible de la pantalla. Recomendaciones:
  • Ocultar el header nativo en la ruta del WebView.
  • Aplicar insets de área segura para evitar el notch y el indicador de inicio.
  • Si se oculta el header, proporcionar un pequeño botón de retroceso a nivel de app.
  • No incrustar el WebView dentro de una tarjeta o modal — dejar que ocupe la pantalla directamente.
┌──────────────────────────┐
│  back                    │
│ ┌──────────────────────┐ │
│ │                      │ │
│ │      LiveForm        │ │
│ │      WebView         │ │
│ │                      │ │
│ └──────────────────────┘ │
└──────────────────────────┘

Lista de Verificación

Verificar tanto en iOS como en Android.
Enfoque de verificaciónLa app del cliente debe implementar su propia pantalla WebView basándose en el código de ejemplo proporcionado, y luego verificar la URL real de LiveForm y una página de prueba de permisos/funciones por separado.
  • Modo URL de LiveForm: Verificar el flujo de envío real en el host de producción de LiveForm.
  • Página de prueba de permisos/funciones: Verificar el storage/cookie, fetch, input de archivo y captura con cámara del WebView en un único flujo secuencial, independientemente del estado de LiveForm.
Pasar las pruebas de permisos/funciones confirma que el mecanismo del WebView funciona, pero no garantiza un envío exitoso de LiveForm. La aprobación final requiere pasar ambos modos.
URL y Navegación
  • Una URL de LiveForm en el formato https://form.argosidentity.com?pid={pid} se abre correctamente.
  • El pid está codificado en URL antes de ser pasado.
  • Los esquemas personalizados externos se abren en una app externa o fallan de forma segura.
Permisos
  • El permiso de cámara se verifica antes de entrar al WebView en el primer lanzamiento.
  • El permiso de biblioteca de fotos/medios se verifica antes de entrar al WebView en el primer lanzamiento.
  • Se muestra un mensaje recuperable si el permiso es denegado.
  • El botón “Abrir Configuración” navega a la pantalla de configuración de la app.
Comportamiento del WebView
  • LiveForm se carga con JavaScript habilitado.
  • La interfaz de cámara se abre al capturar un documento de identidad.
  • El selector se abre para la subida de imágenes.
  • Las cookies y el storage persisten durante la navegación normal del WebView.
  • Se muestra un estado de carga mientras la página se carga.
  • Se muestra un mensaje de error recuperable ante error de carga del WebView o error HTTP.

Resolución de Problemas

Verificar:
  • ¿Se solicitó y concedió el permiso de cámara a nivel de app antes de abrir el WebView?
  • ¿Está configurado NSCameraUsageDescription en iOS?
  • ¿Está configurado android.permission.CAMERA en Android?
  • ¿Están habilitadas las configuraciones de captura de medios en el WebView?
Si el bloqueo de cámara persiste en un entorno de navegador integrado (WebView), consultar Resolución de Problemas de Cámara en Android y WebView.
Verificar:
  • ¿Se solicitó y concedió el permiso de biblioteca de fotos o medios?
  • ¿Está configurado NSPhotoLibraryUsageDescription en iOS?
  • ¿Están configurados correctamente los permisos de medios de Android según el target SDK y la implementación del selector?
Verificar:
  • ¿La URL incluye un pid válido?
  • ¿El dispositivo está conectado a una red?
  • ¿Están habilitados JavaScript y DOM storage?
  • ¿El callback del WebView recibió un error HTTP o de red?