--- title: Integración de Aplicación Web description: Cómo integrar el contrato Web & SDK del lado del cliente — flujos de redirección y configuración del SDK de iFrame. canonical: https://developer.unico.io/es/human-token/integrations/web/web-integration/ locale: es generated_by: markdown-export --- 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 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 `callbackUri` definida 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 la `callbackUri` y cerrar la pestaña una vez que el proceso se complete. Consulta la [documentación de MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) para detalles sobre la API. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### Journeys SDK 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. ```bash 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. :::tip[Mantener el SDK actualizado] 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"); ``` :::info 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 | ```javascript 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. :::warning 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. ```javascript 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: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Aplicaciones de ejemplo | Lenguaje / Framework | Descripción | Repositorio | | --------------------- | ------------ | ---------- | | Angular | PoC en Angular que implementa el Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC en JS Vanilla que implementa el Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC en React que implementa el Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC en Vue JS que implementa el Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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. :::warning[Integraciones no soportadas] 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 `