Todos os artigos Estúdio

Guia de publicação de mapas

Por The Kaleidr Team · Publicado 19 de agosto de 2026 · 16 min de leitura

Um mapa interativo passa da criação e revisão à publicação, ao compartilhamento independente, à incorporação em sites e à integração com produtos, com controles de produção.

A publicação de mapas transforma um mapa editável em uma experiência estável que outras pessoas podem abrir, incorporar ou usar em um produto. As principais opções são um link de compartilhamento independente, um Viewer incorporado ou uma integração mais profunda com o aplicativo. Um mapa em produção também precisa de regras de acesso, domínios permitidos, versão ativa, layout móvel, caminhos de lançamento e despublicação e medição — não apenas uma URL.

As seções abaixo abordam modelos de publicação, controles de acesso e domínio, layout da incorporação, mensagens, versionamento, análises e as superfícies do Kaleidr Studio e Viewer. O contexto do produto está no Kaleidr Studio. Para a mecânica de incorporação, consulte Como incorporar um mapa interativo. Para comparar a responsabilidade do construtor e da API, veja Construtor de mapas sem código versus API de mapas. Para montagens do SDK, consulte O que é um SDK de mapas com IA?.

Fundamentos da publicação

  • Criação ≠ publicação: Rascunhos mudam; mapas publicados precisam de uma superfície de consumo estável.
  • Escolha o acoplamento: Links são leves; incorporações ficam na página; integrações compartilham o estado do aplicativo.
  • Proteja o host: Domínios permitidos e verificações de origem fazem parte do contrato.
  • Reserve espaço: Uma incorporação recolhida é falha de layout, não do mapa.
  • Versione por trás de um ID estável: Meça, revise, publique e reverta sem reescrever cada página host.

Um mapa interativo passa da criação e revisão à publicação, ao compartilhamento independente, à incorporação em sites e à integração com produtos, com controles de produção.

O que significa publicar um mapa?

Criar e publicar um mapa são etapas diferentes. Durante a criação, a equipe pode alterar lugares, camadas, rótulos, cores, blocos, câmera, filtros, interações e fontes de dados. Publicar cria uma superfície de consumo: página independente, incorporação em site, localizador SaaS, mapa editorial ou visualização interna somente leitura. Uma ferramenta de autoria pode tolerar rascunhos. Um mapa publicado exige acesso, layout, desempenho, comportamento, versões, atribuição e monitoramento previsíveis. O Kaleidr Studio atualmente descreve a autoria como Prompt → Process → Refine → Deploy e informa que mapas concluídos podem ser publicados como páginas independentes ou incorporados como widgets (Studio).

As equipes devem compartilhar, incorporar ou integrar um mapa publicado?

Três modelos cobrem a maioria dos lançamentos. Um link é mais rápido para revisões, campanhas e guias, pois o site host quase não exige implementação. Um Viewer incorporado serve para sites, landing pages, CMS e portais de clientes quando o mapa deve aparecer ao lado do texto e de uma chamada para ação. A integração com o produto serve para SaaS, marketplaces e fluxos personalizados em que filtros, registros selecionados e estado do aplicativo permanecem sincronizados com o mapa. A escolha depende de o mapa ser principalmente conteúdo, experiência incorporada ou parte do estado do aplicativo. Ele pode começar como link e depois virar incorporação ou componente.

Modelo Melhor para Desenvolvimento no host Acoplamento ao produto
Link de compartilhamento Revisões, campanhas, guias Mínimo Baixo
Viewer incorporado Sites, CMS, portais Baixo Médio
Integração com o produto SaaS e fluxos personalizados Maior Alto

A documentação atual para desenvolvedores da Kaleidr descreve mapas publicados do Viewer como protegidos por link e identificados por um share ID, não por uma chave geral de API (Viewer Embed). Um share ID identifica uma experiência publicada; não é segredo de servidor e não deve ser tratado como tal. O Studio informa que mapas podem ser incorporados como widgets após a publicação. O Chat pode se conectar a um mapa host existente, enquanto o Viewer é projetado para uma experiência publicada (kaleidr.js).

Três modelos de publicação: link independente, mapa incorporado em um site e mapa profundamente integrado ao estado do aplicativo.

Como incorporações em produção devem lidar com layout, acesso e mensagens?

Defina o contrato antes do lançamento: acesso público ou restrito, domínios permitidos, estados rascunho, publicado ou arquivado e se a superfície ativa mostra uma captura revisada dos dados. Os controles devem usar origens simples, como https://www.example.com e https://app.example.com. A documentação atual do Viewer descreve domínios permitidos definidos pelo publicador. Uma página host protegida por login não torna automaticamente privada uma URL de mapa acessível separadamente; dados empresariais privados exigem arquitetura de autorização específica.

Reserve altura e largura para que a incorporação não recolha. A especificação HTML recomenda um title conciso no iframe para que tecnologias assistivas nomeiem o contexto de navegação aninhado (HTML Standard); o requisito normativo de um nome determinável por programa para frames está em WCAG 4.1.2. Aplique carregamento lento a incorporações fora da tela com loading="lazy"; o padrão HTML define esses atributos e o web.dev recomenda adiar iframes fora da tela para reduzir rede e trabalho inicial. Já o mapa principal visível deve carregar como parte da experiência crítica. Mantenha uma alternativa textual — nomes, endereços ou lista — para a página funcionar se o Viewer falhar.

A comunicação entre origens deve usar um canal controlado. window.postMessage() é o mecanismo padrão entre janelas e iframes (HTML Standard). Valide event.origin em mensagens recebidas e defina uma origem de destino específica nas enviadas; não use "*" por padrão. A documentação do Viewer descreve uma interface de mensagens kaleidr-embed:* para comportamentos compatíveis. Os estados do Viewer e do host devem ficar separados: o mapa publicado controla câmera e seleção no Viewer; a página host controla navegação, formulários e conversão.

// Published Viewer mount: share ID, not a server key
Kaleidr.mount("#published-map", {
  product: "viewer",
  shareId: "YOUR_SHARE_ID"
});

Arquitetura de incorporação em produção com página host, Viewer entre origens, controle de domínios, mensagens validadas, tamanho responsivo, carregamento lento e alternativa textual.

Como versionar, medir e reverter mapas publicados?

Salvar um rascunho não equivale a publicar uma versão ativa. Mantenha IDs estáveis para lugares e incorporação, evitando quebrar páginas host quando o conteúdo mudar. Versione por trás desse ID: edite novo rascunho, revise dados e layout móvel, publique, verifique a produção e reverta se falhar. Meça mais que carregamentos. Sinais úteis incluem mapa pronto, seleção de lugar, CTA e erros; trate esses nomes como recomendações editoriais, salvo se o produto os documentar como eventos automáticos. Separe análises de autoria e Viewer para os experimentos não contaminarem os funis de produção.

Teste falhas: domínio bloqueado, share ID não publicado, rede lenta e ausência de texto alternativo. Domínios de produção, Content Security Policy, atribuição e segurança dos links externos fazem parte da mesma versão. Páginas CMS precisam de contêiner reservado e captura revisada. Produtos SaaS precisam acoplar o mapa ao estado do aplicativo. Páginas de marketing precisam de conversão que não dependa só da interação com o mapa. Mapas em tempo real e 3D exigem mais desempenho e contingência; publique-os apenas se a página host suportar o custo.

Ciclo operacional em que análises do Viewer orientam novos rascunhos, versões revisadas, verificação e reversão, enquanto o identificador permanece estável.

Quais erros de publicação devem ser evitados?

Erro Risco Abordagem melhor
Tratar URL de rascunho como produção Conteúdo instável e incorporações quebradas Publicar captura revisada
Não reservar altura Mudança de layout e mapa recolhido Definir proporção ou tamanho
Carregar lentamente o mapa principal Primeira tela vazia Carregar imediatamente o mapa visível
Usar postMessage("*") Falsificação entre origens Validar e direcionar a origem
Tratar share ID como chave secreta Modelo de acesso confuso Manter chaves do servidor no backend
Ignorar domínios permitidos Reutilização inesperada Restringir origens de incorporação
Publicar linhas privadas em link público Vazamento de dados Autorizar antes de publicar
Trocar o ID em cada edição Páginas host quebradas Versionar por trás de ID estável
Medir apenas carregamentos Qualidade invisível Acompanhar pronto, seleção, CTA e erros
Não oferecer texto alternativo Página vazia se o Viewer falhar Repetir fatos importantes em HTML

Veredito final

A publicação tem sucesso quando a equipe trata o mapa ativo como superfície de produto, não exportação. Escolha compartilhar, incorporar ou integrar conforme o acoplamento necessário com o conteúdo host e o estado do aplicativo. Depois, adicione o contrato de produção: acesso, domínios permitidos, espaço reservado, mensagens com origem validada, versões, medição e reversão. O Kaleidr Studio publica páginas independentes e widgets incorporáveis; o Kaleidr Viewer identifica mapas publicados por share ID. Essa separação mantém a autoria rápida, enquanto a página host responde por conversão, acessibilidade e disciplina de lançamento.

Publique mapas com o Kaleidr Studio

Crie, revise e implante um mapa como página independente ou widget incorporável e monte incorporações publicadas do Viewer onde o site host precisar. Abra o Kaleidr Studio para publicar e consulte a documentação para desenvolvedores sobre share IDs, domínios permitidos e montagens do SDK.

Perguntas frequentes

O que é publicação de mapas?

É transformar um mapa editável em experiência estável que outras pessoas podem abrir, incorporar ou usar num produto, com controles de acesso, layout, versão e medição.

Qual é a diferença entre link e incorporação?

O link abre o mapa publicado em sua própria página. A incorporação coloca esse mapa no layout de um site ou produto host.

Quando usar integração com o produto em vez de incorporação?

Quando filtros, registros selecionados ou estado do fluxo precisam permanecer sincronizados com o mapa, em vez de apenas cercar um Viewer independente.

O Kaleidr Viewer precisa de chave de API?

A documentação atual descreve mapas publicados do Viewer como protegidos por link, não chave de API. Verifique a documentação antes da implantação, pois o modelo pode evoluir.

Share ID é igual a chave de API?

Não. O share ID identifica uma experiência publicada. Uma chave de API do servidor autoriza operações privilegiadas e deve permanecer secreta.

Devo carregar lentamente uma incorporação?

Em geral, quando estiver abaixo da dobra ou for secundária. Se o mapa for a interação principal, carregue-o na experiência crítica e otimize sua inicialização.

Como tornar um mapa iframe acessível?

Dê ao iframe um title conciso, ofereça HTML útil ao redor, suporte tarefas por teclado e disponibilize informações textuais que dispensem arrastar o mapa.

Duas páginas de origens diferentes podem se comunicar com o mapa?

Sim, se a integração permitir. window.postMessage() oferece mensagens controladas. Use origem de destino específica e valide as mensagens recebidas.

Posso publicar dados empresariais privados numa incorporação?

Somente se a arquitetura de publicação e autorização for projetada para isso. O login da página host não torna automaticamente privada uma URL independente.

Um mapa publicado deve ter versões?

Sim, se alterações puderem afetar clientes, incorporações, relatórios ou fluxos empresariais. O versionamento torna reversão e depuração muito mais seguras.

O Kaleidr Studio publica mapas sem código?

Sim. A página atual do Studio informa que autores podem criar e refinar mapas visualmente e publicá-los como páginas independentes ou widgets incorporáveis.

Referências

@misc{kaleidr_studio_publish_2026,
  title  = {Design Custom Maps, Powered by Spatial AI},
  author = {{Kaleidr}},
  note   = {Kaleidr Studio; accessed 19 August 2026},
  url    = {https://kaleidr.com/studio}
}

@misc{kaleidr_viewer_embed_2026,
  title  = {Viewer Embed},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Documentation; accessed 19 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_js_loader_2026,
  title  = {kaleidr.js Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Documentation; accessed 19 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{whatwg_iframe_2026,
  title  = {HTML Standard -- The iframe element},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-iframe-element}
}

@misc{wcag_412_2026,
  title  = {Understanding Success Criterion 4.1.2: Name, Role, Value},
  author = {{W3C}},
  note   = {WCAG 2.2; accessed 19 August 2026},
  url    = {https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html}
}

@misc{whatwg_lazy_loading_2026,
  title  = {HTML Standard -- Lazy loading attributes},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes}
}

@misc{whatwg_postmessage_2026,
  title  = {HTML Standard -- Posting messages},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/web-messaging.html#posting-messages}
}

@misc{webdev_lazy_iframe_2026,
  title  = {Lazy load images and iframe elements},
  author = {{web.dev}},
  note   = {Accessed 19 August 2026},
  url    = {https://web.dev/learn/performance/lazy-load-images-and-iframe-elements}
}

Conteúdo relacionado

Transforme seu mapa em um motor de crescimento