Embed SDK — painel dentro do seu sistema

Selo de estado: Preview — funciona e é documentado, sem SLA. A allowlist de origens é global da instância hoje (por-workspace está no Roadmap). Atualizado em 2026-10-03.

Exiba um painel publicado do ingestia.io dentro da sua aplicação, com token assinado (validade e escopo), eventos (carregou, filtrou, trocou de página) e filtros programáticos — no espírito do Power BI Embedded, sem custo de capacidade.

As peças:

Disponibilidade#

• Estado operacional: Preview — sem SLA.
• Onde ligar: no painel, Mais ações ▸ compartilhar ▸ cartão 2 · Embed na sua aplicação.
• Região: Brasil (São Paulo).

Permissões#

• Ligar embed, rotacionar segredo e desativar são ações do workspace (registradas na auditoria).
• O token só abre um painel (o do dashboardId assinado) — nunca outro.
• Escopo de linha opcional nas claims (f) só aperta o que a política do painel já permite; nunca alarga. PII sempre mascarada.

Configuração (passo a passo)#

1. Confira Sites autorizados a exibir o painel. Se o domínio da sua aplicação não estiver na lista, peça ao suporte.
2. Escolha a Validade máxima do token (5 minutos, 15 minutos (recomendado), 1 hora ou 8 horas (turno inteiro)) e clique em Ligar o embed.
3. Copie o segredo — "Copie o segredo agora — ele não será mostrado de novo." Guarde como variável de ambiente do seu servidor (ex.: INGESTIA_EMBED_SECRET). O keyId é público. O código pronto, com o seu keyId, está em Como emitir o token no seu servidor (botão copiar código).
4. Assine o token no seu servidor (nunca no navegador):

// Node.js — RODE NO SEU SERVIDOR. O segredo nunca vai ao 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"] }, // escopo de linha (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. Incorpore com o 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 } — só estado, nunca linhas */ },
    onInteracao: function (i) { /* { tipo: "pagina" | "drill", resumo } */ },
    onErro: function (err) { /* { codigo } — token expirado: emita outro */ },
  });
  // Comandos: painel.trocarPagina(1); painel.aplicarFiltros({...}); painel.destruir();
</script>

Validação (como confirmar que funcionou)#

• O callback onPronto dispara com { dashboardId, pagina } quando a ponte responde — sinal de que o token foi aceito e o painel renderizou.
• Token com assinatura inválida, expirado, painel despublicado ou origem fora da allowlist → o painel recusa (tela de recusa / onErro).
• Gerar link de teste, na tela Compartilhar, abre o painel com um token de teste para validar o iframe antes de escrever código.
• Num iframe estreito (celular, tablet), o painel usa o layout que o dono arrumou para aquele aparelho. O modo TV (?tv=1) não vale no embed.

Exemplo#

Sua aplicação SaaS mostra, para cada cliente logado, o painel dele com f: { c: "loja", v: ["<id da loja do cliente>"] } nas claims — o mesmo painel, recortado por linha, com token de 15 min emitido a cada carga de página.

Custo#

• Embed não tem custo de capacidade (diferente do Power BI Embedded). O custo é o do processamento das consultas do próprio painel, como no BI nativo.

Segurança#

• Assinatura HMAC-SHA256 conferida em tempo constante antes de qualquer outra regra; não existe token eterno (exp - iat acima do teto → recusa).
• Allowlist de origens via CSP frame-ancestors + verificação de Origin/Referer no servidor; a ponte trava na primeira origem válida do handshake.
• O canal postMessage nunca carrega linhas de dados, token ou segredo — apenas o estado de filtros (o mesmo já visível no ?f= da URL do iframe).
• Nunca gere o token no navegador: o segredo não pode chegar ao cliente.

Limites#

• Validade: padrão 15 min; teto por chave; teto absoluto 12 h.
• Allowlist de origens é global da plataforma hoje (configurada por nós); allowlist por workspace está no Roadmap. Peça ao suporte para incluir o domínio da sua aplicação.
• aplicarFiltros com estado não-vazio recarrega o iframe (o pipeline lê o ?f= na montagem); aplique logo após onPronto. trocarPagina e aplicarFiltros(null) não recarregam.
• Eventos de cross-filter (clique em barra/fatia) ainda não são emitidos (Roadmap).

Rotação e revogação (na UI)#

• gerar segredo novo — pede confirmação (Gerar novo) e troca keyId e secret na hora; todo token emitido para de valer. Atualize INGESTIA_EMBED_SECRET no seu servidor.
• Desativar — recusa qualquer token, mesmo com assinatura válida. Reativar volta.
• Despublicar o painel — corta o embed junto.

Troubleshooting#

Próximos passos: Autenticação · Erros e limites · Suporte (para allowlist de origem).

Estado & evidência: SDK JS de embed = Preview (rotulado conservadoramente; limite atual do produto é Preview). Fonte: matriz de estados do produto.