Usar um mapa base do Kaleidr

Ao concluir este guia, sua página exibirá um mapa base interativo do Kaleidr com o estilo e a câmera escolhidos, e seu código poderá mover a câmera e trocar o estilo. Funciona em todos os planos, inclusive Free, com uma chave publicável que contenha o escopo maps, incluído por padrão nas novas chaves.

Antes de começar

Uma chave publicável (kld_pk_live_…) em kaleidr.com/api-keys. Consulte Obter uma chave de API.
A origem da página de teste, por exemplo http://localhost:3000, precisa constar nas origens permitidas da chave. Uma chave sem restrições de origem funciona em qualquer site.
Um servidor HTTP para servir a página, como npx serve .. Uma página aberta diretamente do disco não tem uma origem válida e é rejeitada por uma chave com restrições.
Caso seu site use uma Política de Segurança de Conteúdo, permita https://cdn.kaleidr.com em script-src, https://api.kaleidr.com em connect-src e https://map-embed.kaleidr.com em frame-src. Consulte Política de Segurança de Conteúdo.

Etapa 1: adicionar o mapa

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Resultado esperado: um indicador «Loading map…», seguido de um mapa base claro. Na guia Network, uma requisição POST a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions retorna 200; em seguida, há uma requisição de documento a https://map-embed.kaleidr.com/. A URL do iframe contém o ID do estilo, mas nenhuma credencial: sua chave é enviada apenas na requisição de sessão, e o token não é incluído na URL do iframe.

O elemento precisa ter altura definida; caso contrário, o mapa usa 500 pixels fixos. <kaleidr-map> tem display:block por padrão, portanto a altura é aplicada. Mantenha essa declaração no estilo: ela é inofensiva e oferece suporte ao Safari anterior à versão 16.4, em que o elemento permanece inline e ignora height. (display:block)

Etapa 2: escolher um estilo

Defina style-id com um dos estilos de uso geral:

`style-id`	Aparência
`kaleidr-morning`	Claro: fundo branco, água ciano e ruas brancas.
`kaleidr-afternoon`	Terreno em tom médio, vegetação verde e ruas cinzentas.
`kaleidr-evening`	Luz dourada: areia quente e tons de oliva.
`kaleidr-night`	Azul-marinho e carvão escuros, rodovias em âmbar.
`kaleidr-plain`	Tela branca com fronteiras e nomes de lugares. Prédios 3D aparecem a partir do zoom 15.
`kaleidr-editorial`	Paleta da tarde, sem rótulos, para mapas pequenos ou decorativos.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

Resultado esperado: a mesma região do mapa em uma paleta escura.

Sempre forneça style-id. Se ele for omitido, a incorporação usa o mapa base padrão da sua organização, se houver. Caso contrário, o iframe mostra «Couldn't find a map id in the URL.».

Os IDs de estilo são exatos. Não há abreviações: night não equivale a kaleidr-night.

Etapa 3: definir a câmera

Sem câmera definida, o mapa abre na visualização padrão do estilo, geralmente do mundo inteiro. Use center (longitude primeiro, latitude depois) e zoom para abrir sua região. pitch inclina a visualização e bearing a gira.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

Resultado esperado: centro de Londres, inclinado e girado.

zoom é ignorado sem center. pitch e bearing funcionam separadamente.

Etapa 4: mover a câmera e trocar o estilo pelo código

O elemento é a forma declarativa. Para controlar o mapa pelo JavaScript, monte-o com Kaleidr.mount e guarde o objeto de controle retornado.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

Resultado esperado: cada botão altera o mapa no lugar. O iframe não recarrega, e nenhuma nova requisição de sessão aparece na guia Network.

Pontos importantes:

setCamera e setStyle pertencem ao objeto de controle, não ao elemento.
setStyle existe somente em Tile. Em outros produtos, exibe um aviso e não faz nada.
Você pode chamar os métodos do objeto de controle a qualquer momento depois que Kaleidr.mount retornar. Chamadas feitas antes de o mapa dentro do iframe estar pronto são guardadas e aplicadas, em ordem, quando ele sinaliza que está pronto. Não é preciso esperar a mensagem kaleidr-embed:ready da etapa 6. Para definir a câmera e o estilo iniciais, use as opções de montagem.
Em um elemento já montado, alterar center, zoom, pitch ou bearing move o mapa. Alterar style-id não tem efeito.

Etapa 5: conectar um painel de chat ao mapa (opcional)

Um painel Kaleidr Chat pode usar um mapa Tile como destino: ele adiciona marcadores para os lugares citados nas respostas e enquadra a câmera para mostrá-los. Coloque o elemento Tile em um contêiner posicionado, sobreponha o elemento de chat e aponte map-target para o elemento Tile.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

Resultado esperado: o painel de chat aparece no canto superior esquerdo do mapa. Pergunte «coffee near Covent Garden» para ver os marcadores no mapa Tile.

Função dos atributos e estilos do elemento de chat:

Item	Finalidade
`map-target="#basemap"`	Seletor CSS do elemento Tile que o chat controlará.
`contained`	Ancora o painel dentro do elemento de chat. Sem isso, ele fica fixo no canto superior esquerdo da janela.
`position:absolute; inset:0`	Estende o elemento de chat sobre o mapa e coloca o painel no canto dele.
`z-index:1`	Mantém a camada de chat acima do mapa.
`pointer-events:none`	Permite arrastar e ampliar o mapa fora do painel. O painel continua clicável.

Observações:

A mesma chave funciona nos dois elementos, pois as chaves padrão têm os escopos maps e ai. O chat cria sua própria sessão e cada pergunta consome créditos de IA.
A ordem dos elementos não importa. O chat procura o mapa quando precisa dele.

As opções de tema e layout estão em Temas e layout. Consulte Recursos e limitações para saber o que o assistente pode ou não fazer.

Etapa 6: saber quando o mapa carregou (opcional)

O SDK não fornece uma promessa ready, e o elemento não dispara eventos. O iframe envia uma mensagem à página quando desenha o mapa e outra se algo não puder ser desenhado:

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

Se a requisição de sessão falhar, nenhuma mensagem será enviada, porque o iframe não é criado. O erro aparece no console. Veja Se não funcionar.

Uma página completa

Salve como index.html, insira sua chave e sirva a pasta por HTTP de uma origem permitida pela chave.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

Como funciona

Tópico	Comportamento
Sessão	O SDK troca a chave por uma sessão Tile de curta duração antes de criar o iframe e a renova enquanto o mapa estiver montado. Essa troca verifica a chave e conta um carregamento de mapa. A sessão não é enviada ao iframe, cuja URL contém apenas estilo e câmera.
Vista inicial	A câmera informada ou a vista padrão do estilo.
Rolagem	Rolar com o ponteiro sobre o mapa amplia o mapa. Com o ponteiro fora do mapa, a rolagem move a página. Em telas sensíveis ao toque, arrastar move o mapa e o gesto de pinça altera o zoom.
Altura	Usa a altura do contêiner no momento da montagem ou, caso ela não exista, 500 pixels fixos.
Carregamento	O iframe carrega sob demanda, quando se aproxima da área visível.
Remoção	`handle.destroy()` remove o iframe e interrompe as renovações da sessão. Remover o elemento `<kaleidr-map>` tem o mesmo efeito.
Reinserção	Reinserir um elemento removido, ou movê-lo para outro pai, monta novamente e cria outra sessão.

Como os carregamentos de mapa são contabilizados

Um carregamento é contado sempre que o SDK obtém uma sessão Tile:

Evento	Carregamentos de mapa
O mapa é montado	1
A sessão é renovada enquanto o mapa permanece montado	1 por renovação
Você destrói e monta novamente, ou reinsere o elemento	1
`setCamera`, `setStyle`, arrastar ou aplicar zoom	0

As sessões duram 15 minutos por padrão, e o SDK as renova 90 segundos antes da expiração, em primeiro ou segundo plano. Uma visita de poucos minutos usa um carregamento; uma página aberta por uma hora usa cerca de cinco.

Para reduzir o consumo:

Destrua a montagem quando o mapa for ocultado definitivamente: ao fechar uma caixa de diálogo, mudar de rota ou descartar uma aba.
Não recrie o elemento a cada renderização. Consulte Integração com frameworks para React, Vue e outros.
Use setStyle para mudar o estilo, em vez de remontar o mapa.

Quando a organização atinge a cota de carregamentos do período, novas sessões são recusadas com HTTP 429 e corpo {"detail":"map_load_quota_exceeded"}. Um mapa que já está visível permanece; uma nova montagem não exibe nada. Consulte Cotas e limites de taxa.

Verificar se funcionou

Na página: o mapa é interativo e os créditos cartográficos aparecem na parte inferior.
No console: nenhuma linha contém [kaleidr.
Na guia Network: kaleidr.js e tile.js de https://cdn.kaleidr.com; um POST …/sdk/sessions com status 200 e JSON com session_token e expires_in; uma requisição de documento a https://map-embed.kaleidr.com/?style=….
No listener: uma mensagem kaleidr-embed:ready com source igual a "tile".

Se não funcionar

O SDK registra falhas de montagem no console como [kaleidr:tile] …. Em uma sessão recusada, registra apenas o status HTTP. O motivo está na resposta da requisição sessions na guia Network. Um 403 coloca o código em detail, assim como map_load_quota_exceeded; um 429 rate_limited coloca o código em error.

Sintoma	Causa	Solução
Nada aparece; erro CORS em `…/sdk/sessions` e erro `[kaleidr:tile]` no console	Chave desconhecida ou revogada, ou origem não permitida; a resposta de recusa não inclui cabeçalhos CORS.	Confira a chave, adicione a origem exata (protocolo, host e porta) em kaleidr.com/api-keys, aguarde alguns minutos e recarregue. A requisição mostra 401 ou 403 na guia Network.
`[kaleidr:tile] kaleidr session exchange failed (403)`	Falta o escopo `maps` (`insufficient_scope`), a chave está limitada a outros produtos (`product_not_allowed`) ou o plano não permite a solicitação (`tier_capability_not_allowed`).	Leia `detail` na guia Network e crie uma chave com os escopos padrão.
`[kaleidr:tile] kaleidr session exchange failed (429)`	Cota esgotada (`map_load_quota_exceeded`) ou muitas solicitações (`rate_limited`).	Leia `detail` no primeiro caso e `error` no segundo. Consulte Cotas e limites de taxa.
A requisição `sessions` retorna 404	Uma substituição de `api-base` omite `/inference-api`.	Remova a substituição ou use `https://api.kaleidr.com/inference-api`.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Foi fornecida uma chave de servidor; o SDK a rejeita antes de qualquer requisição.	Use uma chave publicável. Substitua a chave de servidor caso tenha sido exposta.
`[kaleidr:tile] Kaleidr tile: invalid style "…"…`	`style-id` contém um caractere proibido, como espaço ou `?`.	Use um ID da etapa 2.
O iframe mostra «Couldn't find a map id in the URL.» e o listener recebe `code: 'no_id'` e `id: null`	Falta `style-id` e a organização não tem mapa base padrão.	Forneça `style-id`.
O iframe está vazio e `kaleidr-embed:error` tem `maplibre_error`	O estilo não existe, normalmente por erro de digitação no ID.	Use um estilo da etapa 2.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` está ausente ou incorreto.	Defina `product="tile"`.
O mapa sempre tem 500 pixels de altura	O elemento não tinha altura ao montar, usa `display:inline`, ou Safari anterior a 16.4 não tem `display:block`.	Defina altura e `display:block`. `height`
Um quadro vazio com violação de Content Security Policy no console	A política bloqueia o carregador, a sessão ou o iframe.	Permita os três hosts em Antes de começar.
`setStyle` ou `setCamera` não funciona	Foi chamado no elemento ou o mapa ainda não carregou.	Use o objeto de controle retornado por `Kaleidr.mount`, confira `kaleidr-embed:error` e o console. As chamadas antecipadas são aplicadas quando o mapa fica pronto. Se o mapa não informar que está pronto dentro da espera limitada, normalmente 10 segundos após o carregamento do iframe, a chamada ainda será enviada. O console mostrará `[kaleidr] the map frame has not reported ready`: um frame com erro não tem mapa para mover ou alterar.
Alterar `style-id` no elemento não funciona	É esperado: `style-id` só é lido na montagem.	Use `handle.setStyle` ou insira um novo elemento.

Limitações

Sua página não pode adicionar marcadores, camadas ou popups a um mapa Tile nem recebe eventos de clique ou de câmera. Um painel de chat associado pode posicionar lugares no mapa.
Não existe método para ler o estado atual da câmera.
Tile é a maneira compatível de exibir um mapa base do Kaleidr.
Um mapa Tile não é exibido se a origem da página não for permitida pela chave.

Próximos passos

Referência de Tile para todas as opções, atributos e mensagens.
Integração com frameworks para montar e desmontar com React, Next.js e Vue sem carregamentos extras.
Chat para adicionar o assistente ao mapa.
Cotas e limites de taxa para conhecer as cotas de carregamento.

Antes de começar​

Etapa 1: adicionar o mapa​

Etapa 2: escolher um estilo​

Etapa 3: definir a câmera​

Etapa 4: mover a câmera e trocar o estilo pelo código​

Etapa 5: conectar um painel de chat ao mapa (opcional)​

Etapa 6: saber quando o mapa carregou (opcional)​

Uma página completa​

Como funciona​

Como os carregamentos de mapa são contabilizados​

Verificar se funcionou​

Se não funcionar​

Limitações​

Próximos passos​