Guía de Integración WebView de LiveForm

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:

Construir la URL de LiveForm usando el pid recibido del servidor o de la app del cliente.
Verificar los permisos de la app requeridos por LiveForm antes de abrir el WebView.
Abrir la URL de LiveForm en un WebView a pantalla completa.
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.

Plataforma	Mínimo	Recomendado	Notas
iOS	iOS 15+	iOS 16+	iOS 15+ soporta el callback de permiso de captura de medios de `WKUIDelegate` para restringir los permisos al host de LiveForm.
Android	Android 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 WebView	Android System WebView o Chrome actualizables	Android System WebView o Chrome más reciente	La 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 Native	`react-native-webview` 13.x+	Última versión estable	Las 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 correspondiente a la región del proyecto. El pid se pasa como parámetro de consulta.

Región US: https://form.argosidentity.com?pid={pid}
Región KR: https://form-kr.argosidentity.com?pid={pid}

Siempre aplica URL-encode al pid antes de insertarlo en la URL.

La app no necesita distinguir rutas de tipo de formulario más allá de los hosts por región (US y KR) — 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.

iOS
Android

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>

Añadir los siguientes permisos en AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

Si la subida de imágenes está soportada, también configurar los permisos de foto/medios de Android según el target SDK de la app y la implementación del selector de archivos.

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.

React Native
Android Nativo
iOS Nativo

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ón	Razón
`javaScriptEnabled`	LiveForm se ejecuta como aplicación web.
`domStorageEnabled`	Permite que LiveForm use el storage del navegador.
`sharedCookiesEnabled` / `thirdPartyCookiesEnabled`	Mantiene el comportamiento de cookies similar a un navegador estándar.
`allowsInlineMediaPlayback`	Permite que la interfaz de medios funcione dentro del WebView donde sea compatible.
`mediaCapturePermissionGrantType`	Habilita 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.
`onShouldStartLoadWithRequest`	Reenvía esquemas personalizados desconocidos a apps externas para que no rompan el WebView.

En una app Android nativa, configurar WebView.settings y gestionar las solicitudes de permiso de cámara y las solicitudes de subida de archivos en WebChromeClient.

import android.Manifest
import android.annotation.SuppressLint
import android.app.Activity
import android.content.ActivityNotFoundException
import android.content.Intent
import android.net.Uri
import android.os.Bundle
import android.webkit.CookieManager
import android.webkit.PermissionRequest
import android.webkit.ValueCallback
import android.webkit.WebChromeClient
import android.webkit.WebChromeClient.FileChooserParams
import android.webkit.WebResourceRequest
import android.webkit.WebSettings
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import android.content.pm.PackageManager

class LiveFormActivity : AppCompatActivity() {
    private lateinit var webView: WebView
    private var filePathCallback: ValueCallback<Array<Uri>>? = null

    private val fileChooserLauncher =
        registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
            val callback = filePathCallback
            filePathCallback = null

            if (callback == null) return@registerForActivityResult
            if (result.resultCode != Activity.RESULT_OK) {
                callback.onReceiveValue(null)
                return@registerForActivityResult
            }

            val data = result.data
            val uris = when {
                data?.clipData != null -> {
                    val clipData = data.clipData!!
                    Array(clipData.itemCount) { index -> clipData.getItemAt(index).uri }
                }
                data?.data != null -> arrayOf(data.data!!)
                else -> null
            }

            callback.onReceiveValue(uris)
        }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val liveFormUrl = intent.getStringExtra("LIVE_FORM_URL") ?: return finish()

        webView = WebView(this)
        setContentView(webView)

        CookieManager.getInstance().setAcceptCookie(true)
        CookieManager.getInstance().setAcceptThirdPartyCookies(webView, true)

        webView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            mediaPlaybackRequiresUserGesture = false
            mixedContentMode = WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE
            allowFileAccess = true
        }

        webView.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                view: WebView,
                request: WebResourceRequest,
            ): Boolean {
                val uri = request.url
                val scheme = uri.scheme

                if (scheme == "http" || scheme == "https" || scheme == "about" || scheme == "data") {
                    return false
                }

                return try {
                    startActivity(Intent(Intent.ACTION_VIEW, uri))
                    true
                } catch (_: ActivityNotFoundException) {
                    true
                }
            }
        }

        webView.webChromeClient = object : WebChromeClient() {
            override fun onPermissionRequest(request: PermissionRequest) {
                val origin = request.origin.host ?: return request.deny()
                // En los proyectos de la región KR, use "form-kr.argosidentity.com".
                val allowedHost = origin == "form.argosidentity.com"

                val cameraGranted = ContextCompat.checkSelfPermission(
                    this@LiveFormActivity,
                    Manifest.permission.CAMERA,
                ) == PackageManager.PERMISSION_GRANTED

                val resources = request.resources.filter {
                    it == PermissionRequest.RESOURCE_VIDEO_CAPTURE
                }.toTypedArray()

                if (allowedHost && cameraGranted && resources.isNotEmpty()) {
                    request.grant(resources)
                } else {
                    request.deny()
                }
            }

            override fun onShowFileChooser(
                webView: WebView,
                filePathCallback: ValueCallback<Array<Uri>>,
                fileChooserParams: FileChooserParams,
            ): Boolean {
                this@LiveFormActivity.filePathCallback?.onReceiveValue(null)
                this@LiveFormActivity.filePathCallback = filePathCallback

                return try {
                    fileChooserLauncher.launch(fileChooserParams.createIntent())
                    true
                } catch (_: ActivityNotFoundException) {
                    this@LiveFormActivity.filePathCallback = null
                    filePathCallback.onReceiveValue(null)
                    false
                }
            }
        }

        webView.loadUrl(liveFormUrl)
    }
}

Requisitos de Android

Solicitar el permiso CAMERA a nivel de app y verificar que está concedido antes de abrir el WebView.
En Android 13+, si la selección de imágenes requiere permisos, gestionar READ_MEDIA_IMAGES u otros según la implementación del selector de archivos.
En onPermissionRequest, conceder el acceso a la cámara únicamente para el host de LiveForm de la región de su proyecto. No conceder permiso de cámara a todos los orígenes.
Implementar onShowFileChooser para garantizar que las subidas basadas en <input type="file"> funcionen correctamente.

En una app iOS nativa, usar WKWebView con JavaScript y reproducción de medios en línea habilitados. En iOS 15+, usar el callback de permiso de captura de medios de WKUIDelegate para restringir los permisos al host de LiveForm.

import UIKit
import WebKit
import AVFoundation
import Photos

final class LiveFormViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
    private var webView: WKWebView!
    private let liveFormURL: URL

    init(liveFormURL: URL) {
        self.liveFormURL = liveFormURL
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        let configuration = WKWebViewConfiguration()
        configuration.allowsInlineMediaPlayback = true
        configuration.defaultWebpagePreferences.allowsContentJavaScript = true
        configuration.websiteDataStore = .default()

        webView = WKWebView(frame: .zero, configuration: configuration)
        webView.navigationDelegate = self
        webView.uiDelegate = self
        webView.translatesAutoresizingMaskIntoConstraints = false

        view.addSubview(webView)
        NSLayoutConstraint.activate([
            webView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            webView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
            webView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
            webView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
        ])

        webView.load(URLRequest(url: liveFormURL))
    }

    func webView(
        _ webView: WKWebView,
        decidePolicyFor navigationAction: WKNavigationAction,
        decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
    ) {
        guard let url = navigationAction.request.url else {
            decisionHandler(.cancel)
            return
        }

        if let scheme = url.scheme, ["http", "https", "about", "data"].contains(scheme) {
            decisionHandler(.allow)
            return
        }

        UIApplication.shared.open(url)
        decisionHandler(.cancel)
    }

    @available(iOS 15.0, *)
    func webView(
        _ webView: WKWebView,
        requestMediaCapturePermissionFor origin: WKSecurityOrigin,
        initiatedByFrame frame: WKFrameInfo,
        type: WKMediaCaptureType,
        decisionHandler: @escaping (WKPermissionDecision) -> Void
    ) {
        // En los proyectos de la región KR, use "form-kr.argosidentity.com".
        let allowedHost = origin.host == "form.argosidentity.com"

        decisionHandler(allowedHost ? .grant : .deny)
    }
}

Requisitos de iOS

NSCameraUsageDescription y NSPhotoLibraryUsageDescription deben estar configurados.
Solicitar el permiso de cámara usando AVCaptureDevice.requestAccess(for: .video) (o equivalente) antes de abrir el WebView y verificar que está concedido.
Si se usa el flujo de subida de imágenes, verificar que la política de acceso a la Biblioteca de Fotos coincide con los requisitos de UX de la app.
Conceder el permiso de captura de medios únicamente para el host de LiveForm.

Constructor de URL de LiveForm

// En los proyectos de la región KR, use 'https://form-kr.argosidentity.com'.
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.

Común (URL y Permisos)
Android
iOS WKWebView
React Native

URL y Navegación

Una URL de LiveForm en el formato https://form.argosidentity.com?pid={pid} (https://form-kr.argosidentity.com?pid={pid} en la región KR) 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.

android.permission.CAMERA está declarado en AndroidManifest.xml.
El permiso de cámara en tiempo de ejecución de Android se solicita y verifica como concedido antes de abrir el WebView.
WebChromeClient.onPermissionRequest está implementado en el código WebView nativo.
WebChromeClient.onShowFileChooser está implementado en el código WebView nativo.
Android System WebView o Chrome está actualizado.
javaScriptEnabled está activo.
domStorageEnabled está activo.
Las cookies y las cookies de terceros están permitidas.
La reproducción de medios y el acceso a la cámara no están bloqueados por la política de gestos del usuario o la configuración del WebView.
ValueCallback se llama exactamente una vez para todas las rutas del selector de archivos: éxito, cancelación y fallo.
Los resultados de subida de archivos pasados como URIs content:// se gestionan correctamente.
La implementación del selector de archivos de la app no expone URIs file:// directamente.
La interfaz de selección de archivos de LiveForm permite los tipos de archivo según el atributo accept.
La interfaz de captura de LiveForm abre la ruta de cámara según el atributo capture.
Los recursos de LiveForm no están bloqueados por política HTTPS o de contenido mixto.
La navegación a returnUrl o deep link se entrega correctamente a la app externa/navegador/app del cliente.

NSCameraUsageDescription está declarado en Info.plist.
NSPhotoLibraryUsageDescription está declarado en Info.plist.
La solicitud y verificación del permiso de cámara a nivel de app funcionan correctamente antes de abrir el WebView.
La solicitud y verificación del permiso de biblioteca de fotos a nivel de app funcionan correctamente antes de abrir el WebView.
WKUIDelegate está configurado en el WKWebView nativo.
En iOS 15+, se verifica el gestor de permisos de captura de medios de WKUIDelegate.
input type="file" funciona en WKWebView.
Los archivos seleccionados o capturados se pasan correctamente de vuelta al WebView.
La interfaz de selección de archivos de LiveForm permite los tipos de archivo según el atributo accept.
La interfaz de captura de LiveForm abre la ruta de cámara según el atributo capture.
Las imágenes HEIC se gestionan correctamente por el servidor o el flujo WebView.
La ejecución de JavaScript está habilitada.
Las solicitudes de window.open o nueva ventana se gestionan sin bloqueos, según la política de la app.
La política de cookies y data store de WKWebView no bloquea el flujo de LiveForm.
Los recursos de LiveForm no están bloqueados por política HTTPS o de contenido mixto.
La navegación a returnUrl, universal link y deep link se gestiona correctamente según la política de la app.

javaScriptEnabled está activo en react-native-webview.
domStorageEnabled está activo en react-native-webview.
sharedCookiesEnabled y thirdPartyCookiesEnabled están configurados según la política de la app.
Las props del WebView relacionadas con captura de medios no bloquean el acceso a la cámara.
allowFileAccess y la selección de archivos funcionan tanto en Android como en iOS.
La API de permisos de Expo/RN devuelve correctamente el estado de los permisos de cámara y biblioteca de fotos/medios.
La combinación de onShouldStartLoadWithRequest, onOpenWindow y Linking.openURL gestiona returnUrl/deep links de forma segura.
onError y onHttpError proporcionan orientación recuperable y un reporte de diagnóstico.

Resolución de Problemas

La cámara no se abre dentro de LiveForm

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.

La subida de imágenes no funciona

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?

El WebView muestra una pantalla en blanco

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?

Primeros Pasos

URL de Liveform

Seguridad

Guía del Desarrollador MCP

Guía de Integración WebView de LiveForm

Objetivos de Implementación

Versiones Soportadas y Requisitos Mínimos

URL de LiveForm

Permisos de la App

Flujo de Integración Requerido

Configuración del WebView

Constructor de URL de LiveForm

Ejemplo de Solicitud de Permisos (Expo/React Native)

Diseño a Pantalla Completa

Lista de Verificación

Resolución de Problemas

​Objetivos de Implementación

​Versiones Soportadas y Requisitos Mínimos

​URL de LiveForm

​Permisos de la App

​Flujo de Integración Requerido

​Configuración del WebView

​Constructor de URL de LiveForm

​Ejemplo de Solicitud de Permisos (Expo/React Native)

​Diseño a Pantalla Completa

​Lista de Verificación

​Resolución de Problemas

Objetivos de Implementación

Versiones Soportadas y Requisitos Mínimos

URL de LiveForm

Permisos de la App

Flujo de Integración Requerido

Configuración del WebView

Constructor de URL de LiveForm

Ejemplo de Solicitud de Permisos (Expo/React Native)

Diseño a Pantalla Completa

Lista de Verificación

Resolución de Problemas