Incorporar um mapa interativo em um site

Você pode incorporar uma experiência de mapa interativo em um site com um iframe direto, um componente web reutilizável ou um SDK JavaScript conectado a um mapa ao vivo. Use um iframe para um mapa publicado e autônomo, um componente web para HTML simples com uma camada mantida e um SDK quando a página hospedeira precisar controlar câmera, ciclo de vida ou ações do produto. Uma incorporação em produção também exige dimensões definidas, controles de domínio, acessibilidade, texto rastreável e análise de ações.

As seções a seguir abordam a escolha do método, a configuração do Kaleidr Viewer, contêineres responsivos, segurança, acessibilidade, SEO e erros comuns. Para conectar uma conversa a um renderizador ao vivo, consulte Como adicionar chat com IA a um mapa. Para entender a categoria de SDK, consulte O que é um SDK de mapas com IA?.

Elementos essenciais da incorporação

• Primeiro, o método: Escolha iframe, componente web, SDK ou biblioteca cartográfica nativa conforme o controle exigido pela página hospedeira, não pelo tamanho do exemplo de código.
• Reserve a altura: Defina explicitamente a altura do contêiner antes do carregamento para evitar colapso e deslocamento de layout.
• Viewer publicado: O Kaleidr Viewer usa product="viewer" e um ID de compartilhamento; o acesso depende do link compartilhado e dos domínios permitidos pelo editor.
• Texto fora da tela: Títulos, resumos e listas de locais mantêm a página útil para usuários de teclado, tecnologias assistivas e mecanismos de busca.
• Meça tarefas: Acompanhe carregamentos, seleções, rotas e conversões, não apenas visualizações do mapa.

Como incorporar experiências de mapa interativo?

Este guia cria uma seção de mapa responsiva para um site de marketing, guia de destinos, página de imóveis, localizador de lojas, artigo ou produto de software. A experiência final inclui um mapa interativo publicado, um contêiner que funciona em computadores e celulares, título claro e resumo textual fora do mapa, controle opcional da câmera pela página hospedeira, restrições de domínio ou credenciais, estados de carregamento e falha, alternativas acessíveis às informações exclusivas do mapa e eventos para medir o engajamento. Os exemplos usam o Kaleidr Viewer, que incorpora um mapa publicado com um carregador e um elemento personalizado. O mesmo critério de decisão se aplica a um iframe do provedor, um componente web cartográfico ou uma implementação própria com Mapbox, Google Maps, MapLibre ou Leaflet.

Como escolher o método de incorporação correto?

A primeira decisão é quanto controle o site do host precisa.Um mapa publicado em uma página de conteúdo geralmente não precisa da mesma arquitetura que um mapa dentro de um fluxo de trabalho SaaS, portanto, evite escolher o método mais complexo por padrão.

Use um iframe direto quando o mapa estiver auto-suficiente, a página de host só precisa exibi-lo e o trabalho mínimo de engenharia é a prioridade.O HTML iframe elemento cria um contexto de navegação incorporado separado – isolamento útil, mas outro ambiente de documento com seus próprios recursos e considerações de acessibilidade.Use um componente da Web quando a equipe quiser um elemento HTML declarativo, atributos como ID de mapa ou câmera são suficientes e o provedor mantém a implementação interna; elementos personalizados pode esconder carga e mensagens por trás de um contrato público estável.Use um SDK JavaScript quando o host deve reter uma alça, atualizar a câmera ou o tema, destruir o mapa em alterações de rota, anexar a um renderizador ao vivo ou coordenar a autenticação do navegador, eventos ou fluxos de trabalho de IA.

Como funciona a incorporação do Kaleidr Viewer?

O Kaleidr Viewer incorpora um mapa Kaleidr publicado por meio do ID de compartilhamento. O Viewer gerencia o próprio mapa e funciona por uma fronteira iframe dentro do componente <kaleidr-map>; a página hospedeira pode controlar os comportamentos compatíveis por meio do identificador do SDK e da interface de mensagens documentada. O contrato atual tem quatro propriedades importantes: product="viewer" seleciona o Viewer do mapa publicado; share-id identifica o mapa; o acesso depende do link compartilhado e não exige chave de API; e os domínios permitidos pelo editor continuam válidos. O Viewer difere do Kaleidr Chat: o Viewer gerencia seu mapa, enquanto o Chat pode se conectar a uma instância ativa do Mapbox, Google Maps, MapLibre ou Leaflet já executada no aplicativo hospedeiro.

Carregue uma única vez o carregador versionado de https://cdn.kaleidr.com/embed/v1/kaleidr.js antes de montar um produto. Ele define <kaleidr-map>, instala window.Kaleidr e carrega sob demanda o pacote do produto selecionado. Uma incorporação mínima de um mapa publicado posiciona o elemento personalizado com altura explícita:

<kaleidr-map
  product="viewer"
  share-id="abcd1234"
  style="display:block; height:520px;">
</kaleidr-map>

O exemplo segue o guia de início rápido, a referência de <kaleidr-map> e a documentação de incorporação do Viewer atuais. Substitua abcd1234 pelo ID de compartilhamento do mapa publicado. O mapa deve estar publicado e autorizado a renderizar no domínio hospedeiro. Use o componente documentado em vez de construir uma URL interna do Viewer que não faça parte do contrato público.

Como criar uma página de mapa responsiva e acessível?

Um mapa incorporado precisa de uma altura explícita.Sem um, o contêiner pode entrar em colapso, produzir um layout instável ou voltar a um padrão específico do provedor.Enrole o elemento em um shell que reserva espaço antes que o mapa carregue – largura total, uma altura mínima e, muitas vezes, uma proporção de 16:9 na área de trabalho com um mínimo fixo mais alto em telefones estreitos.Reservar espaço reduz o movimento de layout inesperado; incorporações sem dimensões definidas são uma causa comum de deslocamento de layout cumulativo (web.dev orientação do CLS).Teste o mapa real em vez de depender apenas da proporção: um mapa widescreen raso geralmente funciona na área de trabalho, mas torna-se difícil de usar em um telefone.

O elemento Visualizador observa center, zoom, pitch, bearing, e theme quando apoiado; center usa a longitude, ordem de latitude.Escolha a câmera de abertura para que o propósito do mapa seja claro - distrito, desenvolvimento e trânsito, ou uma visão nacional mais ampla com uma pesquisa ou filtro óbvio.Quando a página do host precisar de uma alça, monte com a API imperativa depois que o carregador estiver presente:

const viewer = Kaleidr.mount("#featured-map", {
  product: "viewer",
  shareId: "abcd1234",
  center: [-0.12, 51.5],
  zoom: 11
});

// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
  viewer.destroy();
});

Kaleidr.mount() retorna um identificador de forma síncrona enquanto o pacote do produto é carregado; chamadas feitas antes de ele estar pronto entram em uma fila. O identificador sempre fornece destroy() e pode oferecer setCamera() ou setTheme() quando o produto selecionado é compatível. Aplicativos de página única devem vincular a desmontagem ao ciclo de vida da rota para que a navegação repetida não crie incorporações duplicadas.

Um mapa interativo não pode ser a única forma de aceder a informações essenciais. WCAG 2.2 fornece a estrutura para conteúdo da Web acessível: dê ao mapa um título significativo e uma região rotulada, publique uma lista de localização equivalente com nomes, endereços, categorias e ações, confirme que os usuários do teclado podem alcançar e deixar o mapa sem armadilhas e evitar marcadores somente para cores.Para um iframe bruto, inclua um atributo title descritivo em vez de um rótulo genérico como “mapa”.

Como as equipes devem tratar domínios, desempenho e SEO?

Um ID de compartilhamento não constitui um modelo de permissão pública irrestrita. O Kaleidr Viewer é protegido pelo link compartilhado e os domínios permitidos pelo editor continuam válidos: um mapa restrito a sites aprovados não será renderizado em outro lugar apenas porque alguém conhece o ID. Planeje a lista de domínios para produção, variantes com www quando ambas forem usadas, homologação e desenvolvimento local quando houver suporte. Os preços atuais do Kaleidr incluem suporte a incorporações nos planos Pro e Enterprise. O Viewer não exige chave de API, mas as equipes devem confirmar o plano, a franquia de carregamentos do mapa e os controles de publicação antes da produção (preços).

Trate o mapa como uma superfície de aplicação significativa.Reserve dimensões antes do carregamento.Preguiçoso-carregue ou adie mapas abaixo da dobra quando eles não são essenciais para a viewport inicial – nativo loading="lazy" aplica-se a iframes crus, enquanto um componente personalizado pode precisar de um Observador de Interseção do lado do host ou da fachada click-to-load.Não atrase um mapa que seja a principal experiência acima da dobra da página.Evite carregar pilhas de mapas duplicadas em uma página e meça o tempo do carregador, o tempo até a transferência interativa de azulejos e a memória móvel em dispositivos reais.

A página do host ainda precisa de texto descritivo e rastreável.Declare o que o mapa contém perto do topo, publique lugares ou conclusões importantes em HTML, use títulos descritivos e adicione dados estruturados apenas quando corresponder ao conteúdo visível.Documentos do Google que a renderização de JavaScript introduz estágios adicionais para sistemas de pesquisa (JavaScript SEO básico).Coloque a incorporação dentro de uma página canônica estável, em vez de muitas URLs quase idênticas que diferem apenas pelo centro de mapas.Criação e publicação de mapas antes da etapa de incorporação são cobertas AI Interactive Map Builder.

Veredicto final

Use um iframe direto quando bastar um mapa autônomo do provedor. Escolha um componente web para uma incorporação declarativa limpa com contrato público mantido. Use um SDK JavaScript quando o aplicativo hospedeiro precisar de controle da câmera, gerenciamento do ciclo de vida, interação com IA, autenticação ou integração mais profunda do produto. O Kaleidr Viewer foi criado para mapas publicados que devem aparecer de forma consistente em diferentes sites sem chave de API no navegador: a página hospedeira carrega kaleidr.js, fornece o ID de compartilhamento, reserva um contêiner responsivo e respeita os domínios permitidos. Uma boa incorporação deve carregar de forma confiável, explicar sua finalidade, permanecer utilizável no celular e pelo teclado, apresentar informações essenciais fora do mapa e ajudar o visitante a concluir uma tarefa mensurável.

Incorporar um mapa publicado do Kaleidr

Publique um mapa no Kaleidr Studio, copie o ID de compartilhamento e adicione o Viewer por meio do carregador JavaScript versionado. A documentação de incorporação do Viewer descreve o contrato do componente e das mensagens. Consulte Chat, Editor, Tiles, autenticação e Platform API na documentação para desenvolvedores quando o mapa precisar integrar um fluxo de produto mais amplo.

Perguntas frequentes

Como incorporar um mapa interativo em um site?

Escolha um mapa ou provedor publicado, adicione seu iframe, componente web ou JavaScript SDK à página, reserve um contêiner responsivo, configure o acesso e forneça texto acessível fora do mapa.

Um iframe é a forma mais fácil de incorporar um mapa?

Normalmente.Um iframe se encaixa quando o mapa é auto-suficiente e a página precisa de pouco controle.Um componente da Web ou SDK é melhor quando o host precisa de um contrato de produto estável, atualizações da câmera, controle do ciclo de vida, eventos ou interação de IA.

O Kaleidr Viewer exige uma chave de API?

Não. Não.O Visualizador atual é fechado em link de compartilhamento e usa o ID de compartilhamento do mapa publicado.As restrições de domínio permitidas definidas pelo editor ainda se aplicam.

Como tornar um mapa incorporado responsivo?

Dê ao invólucro e mapee dimensões explícitas, use largura total, reserve uma altura mínima e ajuste a altura ou o layout para telas estreitas.Teste os controles reais e painéis de informações no celular.

Posso controlar um mapa Kaleidr incorporado com JavaScript?

Sim. Sim.A integração visualizadora imperativa retorna uma alça que pode suportar atualizações da câmera e sempre fornece destroy() para demolição.

Referências

• Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
• Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
• Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
• Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
• MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
• MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
• web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls

@misc{kaleidr_viewer_embed,
  title  = {Viewer -- Embed a Published Map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{mdn_iframe,
  title  = {iframe: The Inline Frame Element},
  author = {{MDN Web Docs}},
  note   = {Accessed 2 August 2026},
  url    = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}

@misc{w3c_wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 2 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}

@misc{google_javascript_seo,
  title  = {Understand JavaScript SEO Basics},
  author = {{Google}},
  note   = {Google Search Central; accessed 2 August 2026},
  url    = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}