Tutorial: incorporar um dashboard (embed)

Embed é colocar um painel do ingestia.bi dentro de outro site (um portal do cliente, um sistema interno) via <iframe>, com um token assinado e uma allowlist de origem. Um SDK JS opcional deixa a página hospedeira ouvir eventos e empurrar filtros para o painel.

Workspace do exemplo: Comércio Aurora Ltda (aurora); origem hospedeira fictícia https://portal.example.com.

Como funciona (visão geral)#

1. Seu backend pede um token de embed (HMAC-SHA256) para um painel específico.
2. Você monta um <iframe src="/d/embed/<token>"> na página hospedeira.
3. O servidor valida Origin/Referer e a CSP frame-ancestors restringe quem pode emoldurar o iframe (allowlist).
4. (Opcional) O embed-sdk.js conecta a página ao iframe por postMessage para eventos e filtros.

Pré-requisitos#

• Painel publicado.
• A origem hospedeira (https://portal.example.com) na allowlist de embed do ambiente.
• Backend capaz de gerar o token de embed (curto e efêmero).

Segurança do token e do canal#

• Token HMAC-SHA256, verificação timing-safe, TTL 15 min (teto 12h), escopo de um painel.
• O token pode levar um escopo de linha (por exemplo, só a loja do usuário): ele só estreita o que a política do painel já permite, nunca amplia. PII sempre mascarada. Painel despublicado é recusado.
• O canal postMessage é fail-closed: mensagem fora do formato é recusada; a ponte fixa (pin) a primeira origem válida da allowlist e só aceita comandos dela; respostas usam targetOrigin explícito, nunca *.
• Nenhuma mensagem transporta linha de dado, token ou segredo — o SDK troca apenas o estado de filtros (a mesma informação que já vai na URL ?f=).

Passo a passo#

1. 1

   Peça a liberação da origem

   Em Compartilhar ▸ 2 · Embed na sua aplicação, veja a lista Sites autorizados a exibir o painel. Se https://portal.example.com não estiver nela, peça ao suporte informando o domínio.

2. 2

   Ligue o embed

   Escolha a Validade máxima do token (recomendado 15 minutos (recomendado)) e clique em Ligar o embed. Copie o segredo — "Copie o segredo agora — ele não será mostrado de novo."

3. 3

   Gere o token no backend

   Use o código de Como emitir o token no seu servidor para assinar um token por carga de página (TTL curto), com o escopo de linha do usuário, se houver.

4. 4

   Monte o iframe

   Na página hospedeira: <iframe src="https://SEU-HOST/d/embed/TOKEN" style="width:100%;height:600px;border:0"></iframe>, ou use o SDK.

5. 5

   (Opcional) Conecte o SDK

   Inclua embed-sdk.js e assine eventos (onPronto, onEstado, onErro) e envie filtros para o painel.

6. 6

   Teste

   Gerar link de teste mostra o painel antes de escrever código. Depois, abra o portal e confirme o carregamento, o recorte e os filtros.

O que o SDK oferece#

• Eventos para a página hospedeira (ex.: onErro({codigo}) com códigos como origem_nao_autorizada, timeout_carregamento).
• Empurrar/ler o estado de filtros do painel (lista, período, faixa, hierarquia, parâmetros numéricos) — nunca dados brutos.
• Ajuste de altura e handshake versionado (v: 1; outra versão é recusada).
• Layout por aparelho: dentro de um 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; para telão, use o Link de TV.

Resultado esperado#

• O painel carrega dentro do portal só quando a origem está na allowlist.
• Cada visitante vê o recorte de RLS do token que o backend emitiu.
• Filtros empurrados pela página hospedeira refletem no painel; nenhum dado sensível trafega pelo postMessage.

Erros comuns#

Limites e ressalvas#

• Allowlist de origem é global da plataforma, não por workspace (evolução → por isso Preview).
• Renderização e latência em produção são NÃO MEDIDO.
• Para compartilhamento sem embutir, use o link público.

Relacionados#

• Tutorial: publicar e compartilhar
• Exportação e distribuição
• Documentação para desenvolvedores

Última revisão: 2026-10-03.