Saltar al contenido principal

Flujo de Integración

Esta guía explica cómo integrar Boufin Connect mediante un iframe utilizando la librería IframeEmbed, con autenticación por Token OTP y comunicación bidireccional mediante postMessage. Además, detalla el proceso para obtener el consentId, un paso clave en el flujo de integración.

Requisitos previos​

Para la integración se requiere:

  • Token OTP válido, obtenido desde el backend siguiendo la guía de Token OTP.
  • URL de Boufin Connect.
  • URL de la librería de embedding.
  • Acceso a una página HTML o aplicación frontend donde integrar el iframe.
  • Protocolo HTTPS habilitado.

Pasos para la integración​

1. Incluir la librería de embedding​

Agrega este script en el HTML o aplicación frontend del cliente para inicializar la clase IframeEmbed:

<script src="https://iframe-embed.boufin.com/embed.js"></script>
info

Este script expondrá el constructor window.IframeEmbed.

2. Crear el contenedor del Iframe​

Define un <div> donde se montará el iframe:

<div id="iframe-container" style="height: 80vh; border: 1px solid #ccc;"></div>
info

Es posible personalizar el style según las necesidades específicas.

3. Inicializar y montar el Iframe​

Utiliza JavaScript para crear una instancia de IframeEmbed y montarla en el DOM:

const embed = new window.IframeEmbed({
  containerId: 'iframe-container',
  appUrl: 'https://localhost', // Reemplaza con la URL de Boufin Connect
  iframeId: 'boufin-connect-iframe',
  title: 'Boufin Connect'
});
embed.mount();
info

En la función mount() es posible ajustar el número de reintentos (retries) y el intervalo entre ellos (delay) según las necesidades de la aplicación. Por defecto es retries = 3 y delay = 200 (en milisegundos).

4. Enviar el token de autenticación (OTP)​

Una vez montado el iframe, envía el Token OTP al iframe para autenticar al usuario:

embed.sendMessage({
  type: 'AUTH_TOKEN',
  payload: {
    token: 'TOKEN_OTP_AQUI'
  }
});
info

En este punto, el Token OTP se envía mediante comunicación bidireccional usando postMessage, lo que permite establecer una sesión segura entre la aplicación y Boufin Connect dentro del Iframe.

5. Obtener el consentId​

Cuando el usuario completa el flujo de autorización dentro del iframe, Boufin Connect envía un mensaje con el consentId. Configura un listener para manejar este evento:

embed.onMessage((data, event) => {
  console.log('[Boufin Embed] Mensaje recibido:', data);

  if (data.type === 'WIDGET_CONSENT') {
    alert('Consentimiento recibido! ID: ' + data.payload.consentId);
  }
});
info

La función onMessage recibe dos parámetros:

  • data: un objeto con la estructura { type: string; payload: any }
  • event: el objeto original del tipo MessageEvent :::

Manejo de mensajes desde el Iframe​

Boufin Connect puede enviar diferentes tipos de mensajes al frontend mediante postMessage. Es importante manejar estos mensajes para garantizar una integración robusta.

Tipos de mensajes enviados por el Iframe​

  1. WIDGET CONSENT: Se envía cuando el proceso de conexión se completa exitosamente. Contiene el ID del consentimiento generado tras la validación exitosa.

    {
      "type": "WIDGET_CONSENT",
      "payload": {
        "consentId": "consent-abc123xyz"
      }
    }

  2. WIDGET CLOSE: Se envía cuando el usuario solicita cerrar el widget.

    {
      "type": "WIDGET_CLOSE"
    }

  3. WIDGET ERROR: Se envía cuando ocurre un error crítico en Boufin Connect. Contiene información detallada del error.

    {
      "type": "WIDGET_ERROR",
      "payload": {
        "error": "NO_LINK_TOKEN: No link token received from parent"
      }
    }

Ejemplo completo de integración​

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>Boufin Connect Embed</title>
  </head>
  <body>
    <h2>Boufin Portal Web</h2>
    <div
      id="iframe-container"
      style="height: 80vh; border: 1px solid #ccc;"
    ></div>

    <!-- Incluir el script que contiene la clase IframeEmbed -->
    <script src="https://iframe-embed.boufin.com/embed.js"></script>

    <!-- Script de inicialización -->
    <script>
      const embed = new window.IframeEmbed({
        containerId: 'iframe-container',
        appUrl: 'https://localhost', // Reemplaza con la URL de Boufin Connect
        iframeId: 'boufin-connect-iframe',
        title: 'Boufin Connect'
      });

      embed.mount();

      embed.sendMessage({
        type: 'AUTH_TOKEN',
        payload: {
          token: 'TOKEN_OTP_AQUI'
        }
      });

      embed.onMessage((data, event) => {
        console.log('[Boufin Embed] Mensaje recibido:', data);
      });
    </script>
  </body>
</html>

Notas importantes​

  • Los mensajes enviados antes de que el iframe esté listo se encolan y se envían automáticamente cuando el iframe se carga.
  • Usa onReady para asegurarte de que el iframe está listo antes de enviar mensajes críticos.
  • El ciclo de vida está automatizado: el iframe se desmonta automáticamente si el contenedor desaparece.