Incorporar ou ejetar

"Coloque meu painel dentro do meu próprio app" tem duas respostas aqui, e elas são de fato dois produtos diferentes, não duas configurações de um só.

• Incorporar — nós renderizamos o painel; você o coloca em um <iframe>. Você não escreve código de painel e não é dono de nenhum build. Incorporando um painel.
• Ejetar — nós entregamos o código-fonte React e SQL; você o renderiza. Saímos inteiramente do caminho de renderização e ficamos apenas com o motor de dados por baixo. Ejete seu painel.

As duas mantêm a metade de plataforma — conexões, conjuntos de dados, atualizações, agendamentos, o mecanismo de consultas, a governança — mantida do nosso lado. A única pergunta é quem desenha os pixels.

A resposta curta

Incorpore se você precisa de filtragem por linha para cada visualizador, ou se quer que publicar seja todo o deploy. Ejete se o painel precisa se parecer e se comportar como o resto do seu app, ou se ele precisa rodar onde nós não chegamos.

Lado a lado

	Incorporar	Ejetar
Quem renderiza	nós	você
O que você integra	uma URL (mais um token de curta duração na via protegida)	uma árvore de código que você constrói e hospeda
Quem publica uma mudança	ninguém — republique e o frame já a serve	você, no seu próprio build e na sua própria release
Filtragem por linha para cada visualizador	sim, aplicada no servidor a partir de um token assinado — é o único lugar em que ela existe	não na via sem credenciais; exige um servidor seu no caminho
Controle visual e de interação	o nosso renderizador, a nossa moldura	completo — são os seus componentes
Estado dos filtros compartilhado com a sua própria interface	não, em nenhuma das duas direções	sim, é o seu estado
Roteamento, autenticação, integração de layout	a fronteira do iframe	nativa no seu app
Credencial que você precisa guardar	nenhuma na via pública; uma chave de API no seu backend para a via protegida	nenhuma na via sem credenciais; uma chave de API no seu servidor para a via backend
Precisa de um backend seu	só para a via protegida, para emitir os tokens	só se você quiser recorte por linha ou consultas ao vivo
Frescor dos dados	consultas ao vivo a cada carregamento	ao vivo na via backend; o snapshot publicado na via sem credenciais

Escolha incorporar quando

• Visualizadores diferentes precisam ver linhas diferentes. Esse é o critério decisivo. A filtragem em nível de linha vive na via de incorporação com token assinado e em nenhum outro lugar: seu backend emite um token de curta duração carregando os filtros, a plataforma reescreve cada referência a um conjunto de dados como uma relação filtrada, e a página só pode estreitar mais. Nada que você construa sobre uma árvore ejetada reproduz isso sem colocar um servidor seu na frente de cada consulta.
• Você quer que publicar seja o deploy. Uma republicação muda o que toda incorporação serve. Nenhuma release do seu lado, nenhuma versão do painel fixada dentro do seu bundle.
• Você não quer ser dono de código de painel. Sem build, sem atualizações de dependências, sem o vai e vem das bibliotecas de gráficos.
• O painel é um quadro dentro do produto, não o produto. Uma aba de relatórios, um extrato para o cliente, uma visão administrativa.

Escolha ejetar quando

• Precisa se parecer com o seu app. Seu design system, sua tipografia, seus estados vazios, seus esqueletos de carregamento. Um iframe é um retângulo com a moldura de outra pessoa dentro.
• Precisa interagir com o seu app. Seus filtros conduzindo os gráficos dele, as seleções dele conduzindo a sua página. A via de incorporação não passa o estado dos filtros em nenhuma das duas direções, então o filtro cruzado entre um painel e a sua própria interface não está disponível ali.
• Você precisa do seu próprio roteamento, autenticação ou layout. Links diretos para um bloco, a sua sessão, a sua casca de aplicação, as suas trilhas de navegação.
• Precisa rodar onde nós não estamos. Sua própria hospedagem, sua própria VPC, uma CDN que você controla. O código-fonte é React e SQL puros e se constrói com npm install && npm run dev. Note que ejetar move a renderização para a sua infraestrutura, não os dados: um painel ejetado continua alcançando pela rede o mecanismo de consultas desta conta ou o seu extrato Parquet. Se o requisito é que nenhum dado saia do seu ambiente, isso é Vibedasher Server, não ejeção.
• Você não quer credencial nenhuma nem backend nenhum. Um painel público e publicado é ejetado sobre uma via que baixa um extrato Parquet e executa cada consulta no navegador do visitante — sem chave, sem token, nada seu para rodar ou pagar. Leia o que isso sacrifica em a via de consulta wasm.

Três diferenças difíceis de desfazer

Sobre tudo o que está acima você pode mudar de ideia barato. Estas três convém decidir antes de construir.

Recorte por linha é uma escolha de arquitetura, não um botão

Se você publicar um painel ejetado na via sem credenciais e depois precisar que o visualizador A veja menos linhas que o visualizador B, não existe nenhuma configuração para ligar. O extrato no navegador é o conjunto de dados inteiro, então cada visitante já tem todas as linhas. Recuperar o recorte significa colocar um servidor seu entre o visualizador e os dados e reescrever contra ele a via de consulta do painel — ou mudar para a via de incorporação, que é outra integração. Veja quem pode ver o quê.

Assim que você edita uma árvore ejetada, o app deixa de ser a fonte da verdade

Ejetar é um fork de verdade, e é exatamente esse o ponto. Você pode empurrar uma árvore editada de volta para o branch de rascunho e continuar trabalhando no ciclo, mas se levar o código-fonte para o seu próprio repositório e começar a mudá-lo lá, as mudanças feitas depois no app não chegam à sua cópia e as suas não voltam. Decida qual lado é dono do código.

As escolhas de visibilidade na via de incorporação não são simétricas

A via protegida exige que a visibilidade do painel seja protected, e recusa de saída um painel public — para que você não possa acreditar que tem filtros por linha quando não tem. Um painel private não é incorporável por nenhuma das duas vias. E tornar um painel legível pelo mundo inteiro é o único passo irreversível do fluxo de publicação; veja publique e compartilhe.

Você pode fazer as duas coisas

Elas não são exclusivas, e uma forma comum usa cada uma para o que ela faz bem: incorporar a visão voltada ao cliente, onde a filtragem por linha é todo o requisito, e ejetar a visão interna que precisa ficar dentro da sua própria casca administrativa. Os mesmos conjuntos de dados, as mesmas atualizações, a mesma governança por baixo.

Próximo

• Incorporando um painel — as duas vias de incorporação, o ciclo de renovação de token, as mensagens que a sua página de fato recebe, e onde fica a fronteira do frame.
• Ejete seu painel — as três chamadas, o contrato de paginação, e como religar os dados.