--- 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/dual-api/developers/sdks-and-tools/web/web-integration/ locale: es generated_by: markdown-export --- 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. :::tip[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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) para más 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 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. ```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 ``` ### 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. ```bash 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. :::tip[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 | ```javascript 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. :::warning 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. ```javascript 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: ```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 muestra | Lenguaje / Framework | Descripción | Repositorio | | --------------------- | ------------ | ---------- | | Angular | PoC en Angular que implementa el SDK de Jornadas | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC en JS Vanilla que implementa el SDK de Jornadas | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC en React que implementa el SDK de Jornadas | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC en Vue JS que implementa el SDK de Jornadas | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Seguridad :::note[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](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). 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. :::warning[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 `