Integración de Aplicación Web
Esta página describe cómo funcionan los journeys de Unico y los modelos de integración disponibles para incorporarlos en una aplicación.
Un journey es el conjunto de pasos que el usuario recorre para completar una verificación de identidad. Por ejemplo: capturar una foto de documento y realizar una captura facial (liveness).
Unico gestiona toda la experiencia. El esfuerzo de integración es mínimo: el journey se crea a través de CreateProcess, el usuario es dirigido a él y el resultado se recibe al final. Todo lo intermedio — pantallas, instrucciones, validaciones — ya está construido y mantenido por Unico.
Dos modelos de integración
Cada cliente tiene necesidades diferentes. Unico ofrece dos modelos para dirigir al usuario al journey.
| Modelo | Ideal para |
|---|---|
| Acceso directo | Aplicaciones móviles que ya usan WebView, o flujos web donde el journey puede ocurrir fuera de la página principal |
| Journeys SDK | Aplicaciones web que necesitan una experiencia integrada y fluida, manteniendo al usuario en el mismo entorno |
- Acceso directo
- Journeys SDK
El usuario es redirigido a un enlace alojado por Unico, donde ocurre el journey. Al completarlo,
es devuelto a la URL definida durante la creación del proceso (el parámetro callbackUri).
Este es el enfoque más sencillo de adoptar: no requiere instalación de bibliotecas y funciona bien cuando el journey 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 introducir 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 del journey alojado por Unico. Hay dos formas comunes de dirigir al usuario:
- Redirección estándar. El usuario es redirigido directamente a la URL del journey. Al completarlo,
Unico lo redirige de vuelta a la
callbackUridefinida durante la creación del proceso. - Nueva pestaña con
window.open(). El journey se abre en una nueva pestaña del navegador, manteniendo al usuario en un contexto separado. En este caso, se recomienda monitorear un cambio de URL hacia lacallbackUriy cerrar la pestaña una vez que el proceso se complete. Consulta la documentación de MDN para detalles sobre la API.
En aplicaciones móviles, es común usar una WebView para abrir el journey directamente, sin necesidad de
redirección adicional. En este caso, callbackUri también acepta un deeplink, permitiendo
que la finalización del journey active la apertura de una pantalla específica en la aplicación nativa.
Simplemente configura el deeplink como destino de retorno y el sistema operativo se encarga de dirigir
al usuario al lugar correcto.
El journey ocurre dentro de la propia aplicación, sin sacar al usuario de su contexto. El Journeys SDK se instala en la aplicación y se usa para abrir el journey cuando sea necesario.
Este es el camino recomendado para una experiencia más integrada y fluida, manteniendo al usuario en el mismo entorno durante todo el proceso, lo que tiende a reducir la fricción y el abandono en el flujo.
Unico proporciona una biblioteca JavaScript compatible con navegadores modernos, que permite integrar el journey en prácticamente cualquier aplicación con solo unas pocas líneas de código.
Compatibilidad
La biblioteca está diseñada para adaptarse a cualquier proyecto sin fricción, independientemente del stack en uso:
- Cualquier aplicación web. Distribuida en formato UMD, funciona al importarla a través de bundlers modernos (como webpack o Vite). Compatible con cualquier framework (React, Angular, Vue) o JavaScript puro.
- Navegadores modernos. La biblioteca ya incluye los polyfills necesarios para características como
Promises y
async/await, extendiendo la compatibilidad también a versiones de navegadores más antiguas. - APIs web estándar. El journey se ejecuta sobre capacidades nativas del navegador, sin dependencia de plugins o bibliotecas externas en el proyecto.
Cómo funciona internamente el SDK
Cuando se abre un journey, el SDK inserta un iFrame en la página y toma el control de toda la experiencia visual a partir de ese punto. Las pantallas, scripts y recursos de cada paso se ejecutan dentro de este iFrame, desde el momento en que el usuario comienza hasta la finalización del proceso.
Esta decisión arquitectónica es intencional: el aislamiento del iFrame asegura que el journey de Unico no interfiera con los estilos o el comportamiento de la aplicación. Ningún script se filtra al contexto externo, ninguna regla CSS colisiona con los propios 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.
Dado que Unico es responsable de crear y gestionar el iFrame, las mejoras del journey — ya sea en rendimiento, experiencia o validación — se entregan automáticamente a todos los usuarios, sin necesidad de cambios en la aplicación integrada. La integración siempre se ejecutará con las mejores optimizaciones disponibles, sin necesidad de rastrear o reaccionar a cada actualización de la plataforma.
Primeros pasos
Paso 1 — Instalación
El paquete idpay-b2b-sdk se comparte entre los journeys de pago de IDPay y los journeys de verificación
de identidad. Para casos de uso de identidad, importa la clase ByUnicoSDK como se muestra en los pasos siguientes.
npm install idpay-b2b-sdk
La forma recomendada de instalar el Journeys SDK es a través de un gestor de paquetes 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 proporciona un control claro sobre la versión en uso y facilita la actualización cuando se publica una nueva versión.
El SDK sigue Semantic Versioning (SemVer), lo que significa que las actualizaciones de parche y menores no introducen cambios disruptivos. Es seguro configurar el proyecto para recibir estas actualizaciones automáticamente. Los cambios que puedan requerir actualizaciones de integración están reservados para versiones mayores y siempre incluyen una guía de migración.
Mantenerse en la última versión es especialmente importante por dos razones. La primera es la seguridad: los parches de seguridad se publican cuando se identifican vulnerabilidades u oportunidades para fortalecer el protocolo de comunicación. Ejecutar una versión desactualizada significa perder estas correcciones y exponer el flujo a riesgos innecesarios. La segunda es la estabilidad: las correcciones de errores se distribuyen de la misma manera, y las versiones anteriores 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 — Configurar CSP y Permissions-Policy
Si tu página ya envía headers Content-Security-Policy o Permissions-Policy, agrega las siguientes directivas para que el iFrame, scripts y acceso a la cámara del SDK funcionen correctamente.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Si tu página no envía headers CSP o Permissions-Policy, puedes omitir este paso — el navegador no aplica restricciones por defecto.
Paso 3 — Llamar a init(options)
Inicializa el SDK y precarga los scripts necesarios para que el journey funcione correctamente, creando una experiencia más fluida para el usuario final. Llama a esto lo antes posible en el flujo.
| Parámetro | Requerido | Descripción |
|---|---|---|
token | Sí | Token del proceso devuelto por la API Create Process |
env | No | Establecer a 'uat' solo para entornos de prueba |
import { ByUnicoSDK } from 'idpay-b2b-sdk';
ByUnicoSDK.init({
token,
// env: 'uat' // only for test environments
});
Paso 4 — Llamar a open(options)
Muestra el iFrame e inicia el journey 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 | Requerido | Descripción |
|---|---|---|
transactionId | Sí | ID del proceso devuelto por la API Create Process |
token | Sí | Token del proceso devuelto por la API Create Process |
onFinish | Sí | Callback ejecutado cuando el journey termina o se cierra |
onWidgetVisibilityChange | No | Callback ejecutado cuando cambia el estado de visibilidad del widget |
La siguiente interacción con la aplicación ocurre cuando el journey termina, ya sea que el usuario
lo haya completado o cerrado. En ese momento, el SDK invoca el callback onFinish, pasado como
parámetro en open. Desde ahí, la aplicación puede llamar a la API getProcess para verificar el
resultado, o esperar una notificación de Webhook si se prefiere un enfoque asíncrono.
Además de consultar el resultado, se recomienda usar onFinish para manejar el
estado del frontend de la aplicación:
- Evitar bucles. Prevenir la recreación inmediata e innecesaria de procesos en caso de que el usuario active el flujo nuevamente justo después de que termine el journey.
- Gestión del flujo. Asegurar que el usuario sea dirigido al siguiente paso de la aplicación, evitando una pantalla sin salida después de que se cierre el journey.
El callback onFinish señala que el usuario ha completado el journey, pero no garantiza
la aprobación. El proceso puede haber terminado con un fallo en una de las reglas de validación de Unico.
Consultar a través de getProcess o recibir la notificación de Webhook no es opcional: estas son las
únicas fuentes del resultado real, y el comportamiento de la aplicación debe basarse en ellas. 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ó el journey:
| Campo | Tipo | Descripci ón |
|---|---|---|
type | string | Cómo terminó el journey: 'FINISH' (completado) o 'CLOSE' (el usuario cerró antes de terminar) |
transaction | object | undefined | Presente cuando type es 'FINISH'; undefined cuando type es 'CLOSE' |
transaction.id | string | Identificador del proceso (igual que el transactionId proporcionado) |
transaction.redirectUrl | string | URL para redirigir al usuario después del journey |
Manejar el callback onWidgetVisibilityChange es opcional y puede no ser relevante para tu
caso de uso. Se invoca cuando cambia el estado de visibilidad del widget, y es útil solo en un
escenario específico: algunos journeys muestran un fondo transparente, manteniendo la página de la aplicación
visible detrás de la experiencia. Las aplicaciones que muestran un modal personalizado durante el flujo de verificación
(por ejemplo, como parte de una orquestación entre múltiples proveedores de KYC) pueden terminar mostrando
ese modal detrás del widget de Unico, degradando la experiencia visual. En ese caso, el callback
permite a la aplicación suprimir cualquier elemento visual adicional mientras el journey de Unico está activo,
y restaurarlos una vez que termine. Si tu aplicación no tiene UI que pueda superponerse al widget, puedes
omitirlo con seguridad.
ByUnicoSDK.open({
transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
onFinish: ({ transaction, type }) => {
if (type === 'FINISH') {
// Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
}
// type === 'CLOSE' → user closed before finishing;
},
// Optional: only needed if your app shows UI that could overlap the widget.
onWidgetVisibilityChange: (visible) => {
// suppress or restore your modal based on widget visibility
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
El diagrama de secuencia a continuación demuestra cómo usar el SDK y el resultado de la API para configurar el iFrame:
Aplicaciones de ejemplo
| Lenguaje / Framework | Descripción | Repositorio |
|---|---|---|
| Angular | PoC en Angular que implementa el Journeys SDK | GitHub — unico-cbu-poc-angular |
| JS Vanilla | PoC en JS Vanilla que implementa el Journeys SDK | GitHub — unico-cbu-poc-js |
| React | PoC en React que implementa el Journeys SDK | GitHub — unico-cbu-poc-react |
| Vue JS | PoC en Vue JS que implementa el Journeys SDK | GitHub — unico-cbu-poc-vuejs |
Seguridad
La seguridad en este modelo está construida en capas, comenzando con el protocolo de comunicación entre el SDK y la aplicación que se ejecuta dentro del iFrame.
Cuando se carga el journey, 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 a través de postMessage
contra una lista cerrada de dominios autorizados, segmentados por entorno (UAT y PROD). Los mensajes
de orígenes no aprobados se descartan inmediatamente, evitando que el journey se incruste en
páginas no autorizadas y eliminando la superficie de ataque para vulnerabilidades como clickjacking.
Además de la validación del origen, el flujo solo procede con un token de transacción válido: un JWT de un solo uso, emitido y firmado por el backend de Unico. Esto asegura que incluso un origen autorizado no pueda operar con un token expirado, reutilizado o falsificado.
Después del handshake, el token se inyecta en el iFrame y no fluye información sensible entre las dos partes. Toda la comunicación restante sirve solo para el control de la interfaz — apertura, cierre y transiciones de pantalla — evitando que los datos del proceso sean interceptados o filtrados durante el journey.
El aislamiento del iFrame también protege la integridad de los scripts de Unico en tiempo de ejecución. Dado que el código se ejecuta en un contexto separado de la página, no puede ser accedido o modificado por scripts externos, asegurando que el journey se ejecute exactamente como fue construido, sin interferencias.
CSP y Permissions-Policy
Si tu página envía headers Content-Security-Policy o Permissions-Policy, asegúrate de que las siguientes directivas estén presentes para que el iFrame, scripts y acceso a la cámara del SDK funcionen correctamente.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Si tu página no envía estos headers, el navegador no aplica restricciones por defecto y no se necesita ninguna configuración.
Solución de problemas específicos del SDK
Esta sección cubre los problemas más comunes encontrados durante la integración y las formas recomendadas de investigarlos.
Comportamiento inesperado o flujo interrumpido
Verifica 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 — ya sea al
alcance, posicionamiento o atributos — puede interferir con el ciclo de vida del journey y causar
comportamiento impredecible.
Experiencia visual diferente de lo esperado
Verifica si alguna hoja de estilos global de la aplicación está sobreescribiendo 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 a través de selectores de ID o clase. Aún así,
reglas CSS amplias — como 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
Verifica si algún archivo de la biblioteca fue modificado fuera del gestor de paquetes. La biblioteca debe ser gestionada exclusivamente a través de npm o yarn, sin ediciones directas a los archivos instalados. Las modificaciones manuales pueden producir comportamiento anómalo que es difícil de reproducir e impedirán que el soporte de Unico pueda asistir.
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 señal potencial de fraude y bloquea el envío. Cierra las DevTools antes de ejecutar pruebas de captura de extremo a extremo.
Los modelos descritos en esta documentación — acceso directo y Journeys SDK — son los únicos enfoques de integración oficialmente soportados por Unico. Las integraciones que se desvíen de estos estándares pueden causar comportamiento inesperado, fallos en flujos de seguridad e interrupciones del journey, y no serán cubiertas por el soporte de Unico.
Ejemplos de enfoques no soportados:
- Incrustar el SDK dentro de una WebView en aplicaciones móviles. En estos casos, el enfoque correcto es usar el modelo de acceso directo, abriendo el enlace del journey directamente en la WebView sin involucrar el Journeys SDK.
- Cargar el iFrame directamente a través de una etiqueta HTML
<iframe>, sin pasar por el Journeys SDK. El iFrame es un detalle de implementación interna del SDK y no debe ser instanciado manualmente. El enfoque correcto es usar el Journeys SDK, que gestiona el ciclo de vida del iFrame de forma segura y dentro de los estándares esperados.
Si hay alguna duda sobre si un enfoque está dentro del estándar soportado, consulta la documentación o contacta al soporte antes de proceder con la implementación.