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

Embed SDK — el panel dentro de tu sistema

Muestra un panel publicado dentro de tu aplicación con un token firmado en tu servidor, iframe y el embed-sdk.js para eventos y filtros — con el paso a paso de la pantalla Compartir.

En esta página (10)

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:

PiezaDónde correQué hace
Clave de embedingestia.io (UI)keyId público + secret que solo tu servidor conoce
Tokentu servidorprueba firmada de que ESTE usuario ve ESTE panel durante N minutos
embed-sdk.jsnavegador de tu usuariocrea 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 dashboardId firmado) — 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)#

  1. Revisa Sitios autorizados a mostrar el panel. Si el dominio de tu aplicación no está en la lista, pídelo al soporte.
  2. 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.
  3. 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). El keyId es público. El código listo, con tu keyId, está en Cómo emitir el token en tu servidor (botón copiar código).
  4. Firma el token en tu servidor (nunca en el navegador):
js
// 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}`;
  1. Incrústalo con el SDK:
html
<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 onPronto se 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 - iat por encima del tope → rechazo).
  • Allowlist de orígenes vía CSP frame-ancestors + verificación de Origin/Referer en el servidor; el puente se fija en el primer origen válido del handshake.
  • El canal postMessage nunca 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.
  • aplicarFiltros con estado no vacío recarga el iframe (el pipeline lee el ?f= al montarse); aplícalo justo después de onPronto. trocarPagina y aplicarFiltros(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 keyId y secret al instante; todo token emitido deja de valer. Actualiza INGESTIA_EMBED_SECRET en 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íntomaCausa probableQué hacer
Pantalla de rechazo / onErro apenas abretoken vencido u origen fuera de la allowlistemite un token nuevo; pide al soporte que incluya el dominio
Los filtros no se aplicanaplicarFiltros antes del onProntoaplícalo dentro/después de onPronto
filtros_invalidosestructura de filtro inválidausa los ids del editor; lee el onEstado para descubrirlos
Todos los tokens dejaron de valerse rotó el secretoactualiza INGESTIA_EMBED_SECRET

Próximos pasos: Autenticación · Errores y límites · Soporte (para la allowlist de origen).

Enlaces relacionados