La allowlist de orígenes vale para toda la instancia hoy (todavía no por workspace).
Muestra un panel publicado de ingestia.io dentro de tu aplicación, con token firmado (validez y alcance), eventos (cargó, filtró, cambió de página) y filtros programáticos — en el espíritu de Power BI Embedded, sin costo de capacidad.
Las piezas:
| Pieza | Dónde corre | Qué hace |
|---|---|---|
| Clave de embed | ingestia.io (UI) | keyId público + secret que solo tu servidor conoce |
| Token | tu servidor | prueba firmada de que ESTE usuario ve ESTE panel durante N minutos |
embed-sdk.js | navegador de tu usuario | crea el iframe, entrega eventos y comandos |
Disponibilidad#
- Estado: disponible. La disponibilidad sigue el SLA de su plan (99,5% mensual a partir de Growth).
- Dónde activarlo: en el panel, Más acciones ▸ compartir ▸ tarjeta 2 · Embed en tu aplicación.
- Región: Brasil (São Paulo).
Permisos#
- Activar el embed, rotar el secreto y desactivarlo son acciones del workspace (registradas en la auditoría).
- El token solo abre un panel (el del
dashboardIdfirmado) — nunca otro. - El alcance de fila opcional en las claims (
f) solo restringe lo que la política del panel ya permite; nunca lo amplía. PII siempre enmascarada.
Configuración (paso a paso)#
- Revisa Sitios autorizados a mostrar el panel. Si el dominio de tu aplicación no está en la lista, pídelo al soporte.
- Elige la Validez máxima del token (5 minutos, 15 minutos (recomendado), 1 hora u 8 horas (turno completo)) y haz clic en Activar el embed.
- Copia el secreto — "Copia el secreto ahora: no se mostrará de
nuevo." Guárdalo como variable de entorno de tu servidor (ej.:
INGESTIA_EMBED_SECRET). ElkeyIdes público. El código listo, con tukeyId, está en Cómo emitir el token en tu servidor (botón copiar código). - Firma el token en tu servidor (nunca en el navegador):
// Node.js — EJECÚTALO EN TU SERVIDOR. El secreto nunca va al navegador.
import { createHmac, randomBytes } from "node:crypto";
const SEGREDO = process.env.INGESTIA_EMBED_SECRET;
const claims = {
k: "SEU_KEY_ID", w: "SEU_WORKSPACE_ID", d: "SEU_DASHBOARD_ID",
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 900, // 15 min
n: randomBytes(16).toString("base64url"),
// f: { c: "loja", v: ["12"] }, // alcance de fila (opcional)
};
const corpo = "v1." + claims.k + "." + Buffer.from(JSON.stringify(claims)).toString("base64url");
const token = corpo + "." + createHmac("sha256", SEGREDO).update(corpo).digest("base64url");
const urlDoEmbed = `https://ingestia.io/d/embed/${token}`;- Incrústalo con el SDK:
<div id="painel"></div>
<script src="https://ingestia.io/embed-sdk.js"></script>
<script>
var painel = IngestiaEmbed.criar({
container: "#painel",
url: urlDoEmbedVindaDoSeuServidor, // /d/embed/<token>
autoAltura: true,
onPronto: function (p) { /* { dashboardId, pagina } */ },
onEstado: function (e) { /* { f, filtros } — solo estado, nunca filas */ },
onInteracao: function (i) { /* { tipo: "pagina" | "drill", resumo } */ },
onErro: function (err) { /* { codigo } — token vencido: emite otro */ },
});
// Comandos: painel.trocarPagina(1); painel.aplicarFiltros({...}); painel.destruir();
</script>Validación (cómo confirmar que funcionó)#
- El callback
onProntose dispara con{ dashboardId, pagina }cuando el puente responde — señal de que el token fue aceptado y el panel se renderizó. - Token con firma inválida, vencido, panel despublicado u origen fuera de la
allowlist → el panel rechaza (pantalla de rechazo /
onErro). - Generar enlace de prueba, en la pantalla Compartir, abre el panel con un token de prueba para validar el iframe antes de escribir código.
- En un iframe estrecho (celular, tablet), el panel usa el layout que el dueño
organizó para ese dispositivo. El modo TV (
?tv=1) no aplica en el embed.
Ejemplo#
Tu aplicación SaaS muestra, a cada cliente que inicia sesión, su panel con
f: { c: "loja", v: ["<id da loja do cliente>"] } en las claims — el mismo panel,
recortado por fila, con un token de 15 min emitido en cada carga de página.
Costo#
- El embed no tiene costo de capacidad (a diferencia de Power BI Embedded). El costo es el del procesamiento de las consultas del propio panel, como en el BI nativo.
Seguridad#
- Firma HMAC-SHA256 verificada en tiempo constante antes de cualquier
otra regla; no existe token eterno (
exp - iatpor encima del tope → rechazo). - Allowlist de orígenes vía CSP
frame-ancestors+ verificación deOrigin/Refereren el servidor; el puente se fija en el primer origen válido del handshake. - El canal
postMessagenunca lleva filas de datos, token ni secreto — solo el estado de los filtros (el mismo que ya es visible en el?f=de la URL del iframe). - Nunca generes el token en el navegador: el secreto no puede llegar al cliente.
Límites#
- Validez: predeterminada 15 min; tope por clave; tope absoluto 12 h.
- La allowlist de orígenes es global de la plataforma hoy (configurada por nosotros);
la allowlist por workspace está en el
Roadmap. Pide al soporte que incluya el dominio de tu aplicación. aplicarFiltroscon estado no vacío recarga el iframe (el pipeline lee el?f=al montarse); aplícalo justo después deonPronto.trocarPaginayaplicarFiltros(null)no recargan.- Los eventos de cross-filter (clic en barra/porción) todavía no se emiten
(
Roadmap).
Rotación y revocación (en la UI)#
- generar secreto nuevo — pide confirmación (Generar nuevo) y cambia
keyIdysecretal instante; todo token emitido deja de valer. ActualizaINGESTIA_EMBED_SECRETen tu servidor. - Desactivar — rechaza cualquier token, incluso con firma válida. Reactivar lo vuelve a habilitar.
- Despublicar el panel — corta el embed junto con él.
Troubleshooting#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
Pantalla de rechazo / onErro apenas abre | token vencido u origen fuera de la allowlist | emite un token nuevo; pide al soporte que incluya el dominio |
| Los filtros no se aplican | aplicarFiltros antes del onPronto | aplícalo dentro/después de onPronto |
filtros_invalidos | estructura de filtro inválida | usa los ids del editor; lee el onEstado para descubrirlos |
| Todos los tokens dejaron de valer | se rotó el secreto | actualiza INGESTIA_EMBED_SECRET |
Próximos pasos: Autenticación · Errores y límites · Soporte (para la allowlist de origen).