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)#
- Tu backend pide un token de embed (HMAC-SHA256) para un panel específico.
- Armas un
<iframe src="/d/embed/<token>">en la página anfitriona. - El servidor valida Origin/Referer y la CSP
frame-ancestorsrestringe quién puede enmarcar el iframe (allowlist). - (Opcional)
embed-sdk.jsconecta la página con el iframe porpostMessagepara 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
postMessagees 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 usantargetOriginexplí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#
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.comno está en ella, pídelo al soporte indicando el dominio.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."
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.
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.(Opcional) Conecta el SDK
Incluye
embed-sdk.js, suscríbete a eventos (onPronto,onEstado,onErro) y envía filtros al panel.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 comoorigem_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íntoma | Causa | Qué hacer |
|---|---|---|
Iframe en blanco / origem_nao_autorizada | origen fuera de la allowlist | pide al soporte que habilite https://portal.example.com |
| Todos los tokens dejaron de valer | alguien hizo clic en generar secreto nuevo o Desactivar | actualiza el secreto en el servidor / Reactivar |
| "Token vencido" | el TTL de 15 min se agotó | genera un token nuevo por sesión/carga |
| Filtros ignorados | origen no "fijado" correctamente | asegú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.