Integración de Aplicación Web

Esta página describe cómo funcionan las jornadas de Unico y cuáles son los modelos disponibles para integrarlas en una aplicación.

Una jornada es el conjunto de pasos que el usuario recorre para completar una verificación de identidad. Por ejemplo: capturar una foto del documento y realizar una captura facial (Detección de Vida).

Unico se encarga de toda esa experiencia. El esfuerzo de integración es mínimo: la jornada se crea a través de CreateProcess, el usuario es dirigido a ella y, al final, se recibe el resultado. Todo lo que ocurre en el camino (pantallas, instrucciones, validaciones) ya está listo y es mantenido por Unico.

Cómo elegir tu enfoque de integración

• Web SDK (paquete unico-webframe): úsalo cuando tu back-end ya controla el flujo de verificación de identidad y solo necesita el componente de captura del lado del cliente. Devuelve base64 + JWT cifrado directamente a tu callback; tú gestionas las llamadas a la API.
• Web App Integration (paquete idpay-b2b-sdk): úsalo cuando quieras que Unico orqueste toda la jornada (flujos de múltiples pasos, captura de documentos + Detección de Vida). El paquete idpay-b2b-sdk impulsa el modelo SDK de Jornadas (iFrame) integrado; el modelo Acceso directo (redirección) no necesita ninguna biblioteca.

Dos modelos de integración

Cada cliente tiene necesidades diferentes. Unico ofrece dos modelos para dirigir al usuario hacia la jornada.

Modelo	Ideal para
Acceso directo	Aplicaciones móviles que ya utilizan WebView, o flujos web donde la jornada puede ocurrir fuera de la página principal
SDK de Jornadas	Aplicaciones web que necesitan una experiencia integrada y fluida, manteniendo al usuario dentro del mismo entorno

Acceso directo

El usuario es redirigido a un enlace de Unico, donde ocurre la jornada. Al completarla, vuelve a la URL definida durante la creación del proceso (parámetro callbackUri).

Es el enfoque más sencillo de adoptar: no requiere instalación de bibliotecas y funciona bien cuando la jornada no necesita ocurrir dentro de la propia página de la aplicación. Por otro lado, llevar al usuario fuera del entorno del cliente tiende a generar más fricción y, en consecuencia, una mayor tasa de abandono.

Después de crear un proceso, la respuesta de la API incluye la URL de la jornada alojada por Unico. Hay dos formas comunes de dirigir al usuario hacia ella:

• Redirección estándar. El usuario es redirigido directamente a la URL de la jornada. Al completarla, Unico lo redirige de vuelta al callbackUri definido durante la creación del proceso.
• Nueva pestaña con window.open(). La jornada se abre en una nueva pestaña del navegador, manteniendo al usuario en un contexto separado. En este caso, se recomienda monitorear el cambio de URL hacia el callbackUri y cerrar la pestaña una vez que el proceso se complete. Consulta la documentación de MDN para más detalles sobre la API.

En aplicaciones móviles, es común utilizar una WebView para abrir la jornada directamente, sin necesidad de redirección adicional. En este caso, el callbackUri también acepta un deeplink, lo que permite que la finalización de la jornada dispare la apertura de una pantalla específica en la aplicación nativa. Basta con configurar el deeplink como destino de retorno y el propio sistema operativo se encarga de enrutar al usuario al lugar correcto.

SDK de Jornadas

La jornada ocurre dentro de la propia aplicación, sin sacar al usuario de su contexto. El SDK de Jornadas se instala en la aplicación y se utiliza para abrir la jornada cuando sea necesario.

Es el camino recomendado para una experiencia más integrada y fluida, manteniendo al usuario siempre en el mismo entorno, lo que tiende a reducir la fricción y el abandono a lo largo del flujo.

Unico proporciona una biblioteca JavaScript compatible con los navegadores modernos, que permite integrar la jornada en prácticamente cualquier aplicación con pocas líneas de código.

Compatibilidad

La biblioteca está diseñada para encajar en cualquier proyecto sin fricción, independientemente del stack utilizado:

• Cualquier aplicación web. Distribuida en formato UMD, funciona cuando se importa a través de bundlers modernos (como webpack o Vite). Compatible con cualquier framework (React, Angular, Vue) o con JavaScript puro.
• Navegadores modernos. La biblioteca ya incluye los polyfills necesarios para funcionalidades como Promises y async/await, ampliando la compatibilidad también con versiones más antiguas de los navegadores.
• APIs web estándar. La jornada se ejecuta sobre capacidades nativas del navegador, sin depender de plugins ni bibliotecas externas en el proyecto.

Cómo funciona el SDK internamente

Al abrir una jornada, el SDK inserta un iFrame en la página y toma el control de toda la experiencia visual a partir de ese momento. Las pantallas, los scripts y los assets de cada paso se ejecutan dentro de ese iFrame, desde el momento en que el usuario comienza hasta la finalización del proceso.

Esta decisión de arquitectura es intencional: el aislamiento del iFrame garantiza que la jornada de Unico no interfiera con los estilos ni con el comportamiento de la aplicación. Ningún script se filtra al contexto externo, ninguna regla de CSS colisiona con los estilos de la aplicación. El resultado es una experiencia consistente para el usuario final y un impacto mínimo en el producto del cliente.

Como Unico es responsable de crear y gestionar el iFrame, las mejoras en la jornada (ya sean de rendimiento, experiencia o validación) llegan automáticamente a todos los usuarios, sin necesidad de ningún cambio en la aplicación integrada. La integración siempre se ejecutará con las mejores optimizaciones disponibles, sin necesidad de seguir ni reaccionar a cada evolución de la plataforma.

Primeros pasos

Paso 1: Instalación

El paquete idpay-b2b-sdk se comparte entre las jornadas de pago de IDPay y las jornadas de verificación de identidad. Para casos de uso de identidad, importa la clase ByUnicoSDK como se muestra en los pasos a continuación.

  npm install idpay-b2b-sdk

La forma recomendada de instalar el SDK de Jornadas es a través de un gestor de dependencias como npm o yarn, desde el paquete disponible en el npm registry. Además de simplificar la instalación y la gestión de dependencias, este enfoque ofrece un control claro sobre la versión en uso y facilita la actualización siempre que se publique una nueva versión.

El SDK sigue el Versionado Semántico (SemVer), lo que significa que las actualizaciones de patch y minor no introducen cambios incompatibles. Es seguro configurar el proyecto para recibir estas actualizaciones automáticamente. Los cambios que puedan requerir adaptaciones en la integración se reservan para las versiones major y siempre vienen acompañados de una guía de migración.

Mantén el SDK actualizado

Mantenerse en la versión más reciente es especialmente importante por dos razones. La primera es seguridad: los parches de seguridad se publican siempre que se identifican vulnerabilidades o surgen oportunidades de fortalecer el protocolo de comunicación. Ejecutar una versión desactualizada significa renunciar a estas correcciones y exponer el flujo a riesgos innecesarios. La segunda es estabilidad: las correcciones de errores se distribuyen de la misma forma, y las versiones antiguas pueden presentar comportamientos que ya se han resuelto en versiones más recientes.

Antes de comenzar, registra tus dominios con el equipo de soporte de Unico. Todos los dominios deben usar HTTPS.

Paso 2: Llama a init(options)

Inicializa el SDK y precarga los scripts necesarios para que la jornada funcione correctamente, creando una experiencia más fluida para el usuario final. Llámalo lo antes posible en el flujo.

Parámetro	Obligatorio	Descripción
token	Sí	Token del proceso devuelto por la API de Crear Proceso
env	No	Configúralo como 'uat' solo para entornos de prueba

import { ByUnicoSDK } from 'idpay-b2b-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // solo para entornos de prueba
});

Paso 3: Llama a open(options)

Muestra el iFrame e inicia la jornada para el usuario. A partir de este punto, todo ocurre automáticamente dentro del iFrame, sin necesidad de gestionar ningún paso intermedio.

Parámetro	Obligatorio	Descripción
transactionId	Sí	ID del proceso devuelto por la API de Crear Proceso
token	Sí	Token del proceso devuelto por la API de Crear Proceso
onFinish	Sí	Callback que se ejecuta cuando la jornada termina o se cierra
onWidgetVisibilityChange	No	Callback que se ejecuta cuando cambia el estado de visibilidad del widget

La siguiente interacción con la aplicación ocurre cuando la jornada termina, ya sea porque el usuario la completó o la cerró. En ese momento, el SDK invoca el callback onFinish, pasado como parámetro en open. A partir de ahí, la aplicación puede llamar a la API getProcess para consultar el resultado, o esperar una notificación vía Webhook si se prefiere un enfoque asíncrono.

Además de consultar el resultado, se recomienda usar onFinish para gestionar el estado del front-end de la aplicación:

• Evitar bucles. Impedir la recreación inmediata e innecesaria de procesos en caso de que el usuario active de nuevo el flujo justo después de que la jornada termine.
• Gestión del flujo. Asegurar que el usuario sea dirigido al siguiente paso de la aplicación, evitando que quede atrapado en una pantalla sin salida tras el cierre de la jornada.

advertencia

El callback onFinish indica que el usuario completó la jornada, pero no garantiza la aprobación. El proceso puede haber finalizado con un rechazo en alguna de las reglas de validación de Unico. Consultar vía getProcess o recibir la notificación vía Webhook no es opcional: son las únicas fuentes del resultado real, y el comportamiento de la aplicación debe basarse en ellas. El onFinish no debe usarse de forma aislada para determinar si un usuario fue aprobado.

El callback onFinish recibe un objeto que describe cómo terminó la jornada:

Campo	Tipo	Descripción
type	string	Cómo terminó la jornada: 'FINISH' (completada) o 'CLOSE' (el usuario cerró antes de finalizar)
transaction	object | undefined	Presente cuando type es 'FINISH'; undefined cuando type es 'CLOSE'
transaction.id	string	Identificador del proceso (el mismo transactionId proporcionado)
transaction.redirectUrl	string	URL para redirigir al usuario después de la jornada

Gestionar el callback onWidgetVisibilityChange es opcional y puede no ser relevante para tu caso de uso. Se invoca siempre que cambia el estado de visibilidad del widget, y solo resulta útil en un escenario específico: algunas jornadas muestran un fondo transparente, manteniendo la página de la aplicación visible detrás de la experiencia. Las aplicaciones que muestran un modal propio durante el flujo de verificación (por ejemplo, como parte de una orquestación entre múltiples proveedores de KYC) pueden acabar mostrando ese modal detrás del widget de Unico, degradando la experiencia visual. En ese caso, el callback permite que la aplicación suprima cualquier elemento visual adicional mientras la jornada de Unico está activa, y los restaure una vez que termina. Si tu aplicación no tiene ninguna UI que pueda superponerse al widget, puedes omitirlo sin problemas.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Jornada completada (transaction = { id, redirectUrl }): continúa tu flujo aquí.
    }
    // type === 'CLOSE' → el usuario cerró antes de finalizar;
  },
  // Opcional: solo necesario si tu aplicación muestra UI que pueda superponerse al widget.
  onWidgetVisibilityChange: (visible) => {
    // suprime o restaura tu modal según la visibilidad del widget
  },
});

// Para cerrar el SDK explícitamente en cualquier momento:
ByUnicoSDK.close();

El siguiente diagrama de secuencia muestra cómo usar el SDK y el resultado de la API para configurar el iFrame:

Seguridad

Alcance de esta sección

Esta justificación de seguridad se aplica específicamente a la Web App Integration (idpay-b2b-sdk). El Web SDK (unico-webframe) utiliza un modelo diferente: se ejecuta enteramente en el contexto de la página y sí requiere un CSP. Son dos productos distintos con arquitecturas de seguridad diferentes.

La seguridad en este modelo se construye por capas, comenzando por el protocolo de comunicación entre el SDK y la aplicación que se ejecuta dentro del iFrame.

Al cargar la jornada, ambas partes realizan un handshake para establecer la comunicación. En este proceso, la aplicación de Unico valida el origen del mensaje de inyección de datos recibido vía postMessage contra una lista cerrada de dominios autorizados, segmentada por entorno (UAT y PROD). Los mensajes de orígenes no homologados se descartan de inmediato, lo que impide que la jornada se incruste en páginas no autorizadas y elimina la superficie de ataque para vulnerabilidades como el clickjacking.

Además de la validación de origen, el flujo solo avanza con un token de transacción válido: un JWT de un solo uso, emitido y firmado por el backend de Unico. Esto garantiza que incluso un origen autorizado no pueda operar con un token caducado, reutilizado o falsificado.

Tras el handshake, el token se inyecta en el iFrame y ya no circula ninguna información sensible entre ambas partes. Toda la comunicación restante sirve únicamente para el control de la interfaz (apertura, cierre y transiciones de pantalla), lo que impide que los datos del proceso sean interceptados o filtrados durante la jornada.

El aislamiento del iFrame también protege la integridad de los scripts de Unico en tiempo de ejecución. Como el código se ejecuta en un contexto separado de la página, no puede ser accedido ni modificado por scripts externos, lo que garantiza que la jornada se ejecute exactamente como fue construida, sin interferencias.

Por diseño, no se adopta CSP en este modelo de integración. Los dominios autorizados forman parte de la configuración de seguridad de cada cliente, y su exposición pública en cabeceras podría facilitar el mapeo de la infraestructura por parte de actores malintencionados. Como la identificación del cliente solo ocurre en el momento del init, no es posible inyectar estos dominios dinámicamente en las cabeceras antes de ese punto, lo que hace inviable el CSP sin renunciar a esta privacidad. Todas las garantías de seguridad las proporciona el protocolo de handshake descrito anteriormente.

Solución de problemas específica del SDK

Esta sección reúne los problemas más comunes encontrados durante la integración y las formas recomendadas de investigarlos.

Comportamiento inesperado o flujo interrumpido

Comprueba si algún script de la aplicación está manipulando directamente el iFrame en el DOM. El SDK crea y gestiona el iFrame en el body de la página, y cualquier modificación externa (de alcance, posición o atributos) puede interferir en el ciclo de vida de la jornada y provocar comportamientos impredecibles.

Experiencia visual diferente de la esperada

Comprueba si alguna hoja de estilos global de la aplicación está sobrescribiendo propiedades dentro del iFrame. El SDK crea el iFrame y todos sus elementos internos con IDs dinámicos y clases prefijadas con unico, lo que reduce significativamente el riesgo de conflicto por selectores de ID o de clase. Aun así, reglas CSS de alcance amplio (como los selectores de etiqueta) pueden alcanzar elementos dentro del iFrame y alterar la experiencia visual entregada al usuario.

Archivos de la biblioteca del SDK modificados directamente

Comprueba si algún archivo de la biblioteca ha sido modificado fuera del gestor de dependencias. La biblioteca debe gestionarse exclusivamente vía npm o yarn, sin ediciones directas en los archivos instalados. Las modificaciones manuales pueden producir comportamientos anómalos difíciles de reproducir e impiden la asistencia por parte del soporte de Unico.

No mantengas las DevTools abiertas durante las pruebas de captura

La aplicación de Unico usa el Capture SDK (unico-webframe) para la captura facial, que detecta las DevTools abiertas como una posible señal de fraude y bloquea el envío. Cierra las DevTools antes de ejecutar pruebas de captura de extremo a extremo.

Integraciones no soportadas

Los modelos descritos en esta documentación (acceso directo y SDK de Jornadas) son las únicas formas de integración oficialmente soportadas por Unico. Las integraciones que se desvíen de estos estándares pueden provocar comportamientos inesperados, fallos en el flujo de seguridad e interrupciones en la jornada, y no estarán cubiertas por el soporte de Unico.

Algunos ejemplos de enfoques no soportados:

• Incrustar el SDK dentro de una WebView en aplicaciones móviles. En estos casos, el enfoque correcto es utilizar el modelo de acceso directo, abriendo el enlace de la jornada directamente en la WebView, sin involucrar el SDK de Jornadas.
• Cargar el iFrame directamente mediante una etiqueta HTML <iframe>, sin pasar por el SDK de Jornadas. El iFrame es un detalle de implementación interno del SDK y no debe instanciarse manualmente. El enfoque correcto es utilizar el SDK de Jornadas, que gestiona el ciclo de vida del iFrame de forma segura y dentro de los estándares esperados.

Si tienes alguna duda sobre si un enfoque está dentro del estándar soportado, consulta la documentación o ponte en contacto con el soporte antes de avanzar con la implementación.