Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-10-03

Tutorial: incorporar un dashboard (embed)

Incrustar un panel en un portal de terceros con token HMAC, lista de orígenes permitidos y el SDK de eventos y filtros.

En esta página (9)

Embed es poner un panel de ingestia.bi dentro de otro sitio (un portal del cliente, un sistema interno) mediante <iframe>, con un token firmado y una lista de orígenes permitidos (allowlist). Un SDK JS opcional permite que la página anfitriona escuche eventos y envíe filtros al panel.

Workspace del ejemplo: Comércio Aurora Ltda (aurora); origen anfitrión ficticio https://portal.example.com.

Cómo funciona (visión general)#

  1. Tu backend pide un token de embed (HMAC-SHA256) para un panel específico.
  2. Armas un <iframe src="/d/embed/<token>"> en la página anfitriona.
  3. El servidor valida Origin/Referer y la CSP frame-ancestors restringe quién puede enmarcar el iframe (allowlist).
  4. (Opcional) embed-sdk.js conecta la página con el iframe por postMessage para eventos y filtros.

Requisitos previos#

  • Panel publicado.
  • El origen anfitrión (https://portal.example.com) en la allowlist de embed del entorno.
  • Un backend capaz de generar el token de embed (corto y efímero).

Seguridad del token y del canal#

  • Token HMAC-SHA256, verificación timing-safe, TTL de 15 min (tope de 12 h), alcance de un panel.
  • El token puede llevar un alcance de fila (por ejemplo, solo la tienda del usuario): solo reduce lo que la política del panel ya permite, nunca lo amplía. PII siempre enmascarada. Un panel despublicado se rechaza.
  • El canal postMessage es fail-closed: un mensaje fuera de formato se rechaza; el puente fija (pin) el primer origen válido de la allowlist y solo acepta comandos de él; las respuestas usan targetOrigin explícito, nunca *.
  • Ningún mensaje transporta filas de datos, tokens ni secretos — el SDK intercambia solo el estado de los filtros (la misma información que ya va en la URL ?f=).

Paso a paso#

  1. Pide que se habilite el origen

    En Compartir ▸ 2 · Embed en tu aplicación, mira la lista Sitios autorizados a mostrar el panel. Si https://portal.example.com no está en ella, pídelo al soporte indicando el dominio.

  2. Activa el embed

    Elige la Validez máxima del token (recomendado 15 minutos (recomendado)) y haz clic en Activar el embed. Copia el secreto — "Copia el secreto ahora: no se mostrará de nuevo."

  3. Genera el token en el backend

    Usa el código de Cómo emitir el token en tu servidor para firmar un token por carga de página (TTL corto), con el alcance de fila del usuario, si lo hay.

  4. Arma el iframe

    En la página anfitriona: <iframe src="https://SEU-HOST/d/embed/TOKEN" style="width:100%;height:600px;border:0"></iframe>, o usa el SDK.

  5. (Opcional) Conecta el SDK

    Incluye embed-sdk.js, suscríbete a eventos (onPronto, onEstado, onErro) y envía filtros al panel.

  6. Prueba

    Generar enlace de prueba muestra el panel antes de escribir código. Después, abre el portal y confirma la carga, el recorte y los filtros.

Qué ofrece el SDK#

  • Eventos para la página anfitriona (p. ej., onErro({codigo}) con códigos como origem_nao_autorizada, timeout_carregamento).
  • Enviar/leer el estado de filtros del panel (lista, período, rango, jerarquía, parámetros numéricos) — nunca datos en bruto.
  • Ajuste de altura y handshake versionado (v: 1; otra versión se rechaza).
  • Diseño por dispositivo: dentro de un iframe angosto (celular, tablet), el panel usa el diseño que el dueño preparó para ese dispositivo.
  • El modo TV (?tv=1) no se aplica en el embed; para pantalla grande, usa el Enlace de TV.

Resultado esperado#

  • El panel se carga dentro del portal solo cuando el origen está en la allowlist.
  • Cada visitante ve el recorte de RLS del token que emitió el backend.
  • Los filtros enviados por la página anfitriona se reflejan en el panel; ningún dato sensible viaja por postMessage.

Errores comunes#

SíntomaCausaQué hacer
Iframe en blanco / origem_nao_autorizadaorigen fuera de la allowlistpide al soporte que habilite https://portal.example.com
Todos los tokens dejaron de valeralguien hizo clic en generar secreto nuevo o Desactivaractualiza el secreto en el servidor / Reactivar
"Token vencido"el TTL de 15 min se agotógenera un token nuevo por sesión/carga
Filtros ignoradosorigen no "fijado" correctamenteasegúrate de que los comandos vengan del origen de la allowlist

Límites y salvedades#

  • La allowlist de orígenes es global de la plataforma, no por workspace.
  • Para compartir sin incrustar, usa el enlace público.

Relacionados#


Última revisión: 2026-10-03.

Enlaces relacionados