Incorporar no portal do cliente

Selo de estado: Preview (teto atual do produto) · Curso ACD-340 — Publicação, distribuição, RLS e BI-as-code · Aula 8 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai incorporar com token assinado.

Vídeo#

Identificador no manifesto: acd-340-08-embed-no-portal · duração-alvo 6 min · tela do produto: /dashboards.

Roteiro (capítulos):

1. 00:00–01:00 — Embed é /d por dentro de outro site: o que muda e o que se mantém.
2. 01:00–02:30 — Ligar o embed, copiar o segredo (uma vez só) e assinar o token no servidor.
3. 02:30–04:00 — Montar o <iframe> e conectar o embed-sdk.js.
4. 04:00–05:00 — RLS no token: cada visitante com o recorte certo.
5. 05:00–06:00 — Erros comuns e encerramento.

Conteúdo#

Embed é colocar um painel do ingestia.bi dentro de outro site — o portal de um cliente, um sistema interno — por meio de um <iframe>, com um token assinado controlando quem pode ver o quê, e uma allowlist de origem controlando quem pode emoldurar o iframe. É parecido, em espírito, com o Power BI Embedded, mas sem custo de capacidade: o que você paga é só o processamento das consultas do próprio painel, como em qualquer BI nativo.

Como aparece no produto. A configuração vive na mesma tela Compartilhar das aulas anteriores, numa seção dedicada a embed. O botão Ligar o embed gera uma chave: um keyId público e um segredo que aparece uma única vez na tela — você precisa copiá-lo e guardá-lo como variável de ambiente no seu próprio servidor, porque ele nunca será mostrado de novo. A partir daí, o fluxo tem três peças. No seu servidor (nunca no navegador do usuário final), você assina um token HMAC-SHA256 de curta duração (padrão 15 minutos, teto absoluto de 12 horas), escopado a um painel específico, carregando as claims de quem vai ver — inclusive, opcionalmente, um recorte de linha que só aperta o que a RLS do painel já permite, nunca alarga. Na página hospedeira, você monta o <iframe src="…/d/embed/<token>">, e o embed-sdk.js (opcional, mas recomendado) conecta essa página ao iframe por postMessage, entregando eventos (onPronto, onEstado, onInteracao, onErro) e aceitando comandos (trocarPagina, aplicarFiltros, destruir). Para validar antes de escrever qualquer código, a própria tela de Compartilhar tem o botão Gerar link de teste.

Exemplo Aurora. A Aurora Varejo tem um portal fictício para seus próprios lojistas, https://portal.example.com. Para cada lojista que faz login nesse portal, o backend da Aurora assina um token com claims de recorte de linha, por exemplo f: { c: "loja", v: ["<id da loja daquele lojista>"] }, e monta o iframe apontando para esse token. O mesmo painel "Vendas por filial" aparece dentro do portal, mas cada lojista só vê a própria loja — o recorte vem do token, não de uma configuração separada por cliente. Um token novo é emitido a cada carregamento de página, então a janela de validade de 15 minutos nunca chega a incomodar quem está navegando normalmente.

Erros comuns. O erro mais grave é gerar o token no navegador — o segredo da chave de embed nunca pode chegar ao cliente; toda assinatura precisa acontecer no seu servidor, onde o segredo mora como variável de ambiente. O segundo é esquecer de cadastrar a origem na allowlist: sem isso, o iframe carrega em branco e dispara o evento onErro com o código origem_nao_autorizada — e como essa allowlist é configurada por fora (hoje é global por ambiente, não por workspace), é preciso pedir a inclusão do domínio com antecedência, não na hora de ir ao ar. O terceiro é achar que o canal postMessage transporta dados sensíveis — ele nunca transporta linha, token ou segredo; carrega só o estado de filtros, a mesma informação que já apareceria na URL ?f= do iframe.

Estado do produto. O protocolo do SDK (postMessage v1, fail-closed) é GA-candidato — os próprios testes automatizados funcionam como a especificação do embed-sdk.js, cobrindo o handshake, a rejeição de mensagens fora do formato e a fixação (pin) na primeira origem válida. O que mantém esta aula em Preview é que a allowlist de origem é global por ambiente, não por workspace (evolução prevista), e que a renderização e a latência em produção não são medidas hoje.

Além de ligar e desligar, a tela de Compartilhar oferece dois comandos de manutenção importantes para quem administra um embed em produção: Desativar/Reativar recusa (ou volta a aceitar) qualquer token, mesmo com assinatura válida — útil para uma pausa de emergência sem precisar trocar credencial; e o link discreto gerar segredo novo troca keyId e segredo na hora, invalidando de uma vez todo token já emitido. Despublicar o painel de origem também corta o embed junto, porque o token nunca abre um painel despublicado.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards no console):

1. Num painel publicado, abra Compartilhar e clique Ligar o embed.
2. Copie o segredo exibido e simule guardá-lo como variável de ambiente (ex.: INGESTIA_EMBED_SECRET), já que ele não volta a aparecer.
3. Use Gerar link de teste e abra o link resultante numa aba — confirme que o painel carrega.
4. Monte localmente uma página HTML simples com um <iframe> apontando para esse link de teste.
5. Inclua o embed-sdk.js na página e assine os callbacks onPronto e onErro; confirme que onPronto dispara com { dashboardId, pagina }.
6. Tente abrir o mesmo link de teste a partir de uma origem que você sabe que não está na allowlist (ou simule removendo a sua) e confirme o código de erro origem_nao_autorizada.
7. Use gerar segredo novo para rotacionar a chave e confirme que o link de teste anterior deixa de funcionar.

Você terminou quando tiver um iframe local carregando o painel de treino com o SDK conectado, e conseguir explicar por que o segredo nunca pode estar no código do navegador.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• bi/tutorial-incorporar-dashboard
• desenvolvedores/embed

Capacidades ensinadas#

C12.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".