Início rápido

Esta página apresenta as três integrações funcionais mais simples, pela ordem em que a maioria das equipas precisa delas:

Chat num mapa que já utiliza. Um painel que responde a perguntas sobre lugares e mostra as respostas no seu mapa com marcadores, movimentos de câmara e percursos.
Um mapa publicado. Um mapa criado no Kaleidr Studio e incorporado na sua página.
Um mapa base. Um mapa base desenhado pela Kaleidr, pronto a utilizar na sua página.

Cada opção usa um único ficheiro HTML. As três funcionam no plano Free.

Opção	Produto	Chave necessária	Apresentação
Chat no seu mapa	`chat`	Chave publicável	Na página, sobre o seu mapa
Mapa publicado	`viewer`	Nenhuma	Num iframe Kaleidr
Mapa base	`tile`	Chave publicável	Num iframe Kaleidr

Se preferir compreender primeiro o modelo, leia Como funciona a Kaleidr. Se não sabe qual o produto adequado, consulte Escolha o seu caminho.

Antes de começar

Uma conta Kaleidr. Registe-se em kaleidr.com. O plano Free é suficiente para todos os exemplos desta página.
Uma chave publicável para as opções Chat e mapa base. Crie-a em kaleidr.com/api-keys; começa por kld_pk_live_. Obter uma chave de API explica o formulário. A opção de mapa publicado não precisa de chave.
Um servidor web para a página. Sirva o ficheiro por HTTP, mesmo localmente. Na pasta onde está guardado, pode usar qualquer um destes métodos:
```
python -m http.server 8000
# or
npx serve -l 8000
```
Depois abra http://localhost:8000/your-file.html. Não abra diretamente o ficheiro do disco: uma página file:// não tem uma origem que possa ser adicionada às origens permitidas da chave.
A origem da sua página na lista da chave, se esta tiver uma. Uma chave sem origens permitidas definidas funciona em qualquer site. Se houver lista, funciona apenas nos endereços indicados; adicione http://localhost:8000 durante os testes.
Uma Política de Segurança de Conteúdos que permita carregar a Kaleidr, caso o seu site utilize uma. Sem cabeçalho Content-Security-Policy não é preciso configurar nada. Caso contrário, consulte Política de Segurança de Conteúdos.

As três opções começam com a mesma etiqueta script. É o único ficheiro que carrega diretamente; ele obtém o código de cada produto quando este é montado.

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

Chat no seu mapa

No final terá um mapa MapLibre GL JS com um painel de chat acoplado. Ao perguntar «Onde posso comer ramen perto do Bryant Park?», a resposta chega em fluxo ao painel, coloca marcadores nos locais e move a câmara para os mostrar.

Este exemplo usa MapLibre GL JS. O Chat também se liga a Mapbox GL JS, Google Maps JavaScript API e Leaflet; veja Mapas suportados.

1. Criar a página

Guarde o ficheiro como chat.html e substitua kld_pk_live_… pela sua chave publicável.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

Há três detalhes importantes neste ficheiro:

A biblioteca de mapas é global na página. O chat encontra MapLibre em window.maplibregl. Carregar MapLibre com uma etiqueta script cria essa variável global. Se a importar do npm, atribua-a antes da montagem: window.maplibregl = maplibregl.
map é o objeto do mapa. Passe a instância criada, não um seletor CSS.
contained: true precisa de um contentor posicionado e com altura. O painel aparece dentro do destino de montagem. Sem contained, fica como janela fixa no canto superior esquerdo do navegador.

O estilo de demonstração é um mapa mundial de baixo detalhe. Os marcadores aparecem nas coordenadas corretas, mas utilize o seu estilo para ver ruas.

2. Servir e fazer uma pergunta

Inicie um servidor local na pasta do ficheiro e abra http://localhost:8000/chat.html.

O que deverá ver:

O mapa ocupa a janela, com um painel de chat e uma caixa de texto no canto superior esquerdo.
No separador Rede do navegador, um pedido a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions devolve 200: o SDK trocou a chave por uma sessão temporária.
Escreva uma pergunta sobre lugares, por exemplo Where can I get ramen near Bryant Park?. A resposta chega ao painel em texto, surge um marcador por local e a câmara ajusta-se. O separador Rede mostra um pedido a …/b2b/v1/chat/control/stream que permanece aberto enquanto a resposta chega.
A consola não contém linhas com [kaleidr.

3. Se não funcionar

O que vê	Causa	Solução
Não aparece o painel e a consola mostra um erro CORS para `…/sdk/sessions`, seguido de um erro `[kaleidr:chat]`	A chave está errada, foi revogada ou a origem da página não consta das origens permitidas. A API responde sem cabeçalhos CORS e o navegador apresenta uma falha CORS.	Confirme a chave. Adicione a origem exata, incluindo a porta, em kaleidr.com/api-keys, ou esvazie a lista durante os testes.
O painel surge no canto superior esquerdo do navegador, fora do mapa	Falta `contained: true` ou o destino de montagem não está posicionado	Passe `contained: true` e atribua ao destino `position: relative` e uma altura.
O painel responde, mas não aparecem marcadores	A biblioteca de mapas não é global na página, por isso o chat não cria marcadores	Carregue a biblioteca por script ou defina `window.maplibregl` antes de `Kaleidr.mount`.

Resolução de problemas cobre cada sintoma com as mensagens exatas da consola.

Próximo passo: Ligar o Chat ao MapLibre oferece o guia completo; Capacidades e limites explica o que o painel faz e não faz.

Um mapa publicado

No final terá na sua página um mapa criado no Kaleidr Studio. Não precisa de chave de API: basta o identificador público do mapa.

1. Publicar e copiar o identificador

Abra o mapa em Kaleidr Studio e escolha Publicar.
Na página Publicar e incorporar, escolha Ativar publicação.
Em Código de incorporação, copie o excerto. O identificador é a última parte do endereço: em https://map-embed.kaleidr.com/embed/abc123, é abc123.

O que deverá ver: o estado do projeto mostra live e a pré-visualização sob o código de incorporação mostra o mapa como os visitantes o verão.

2. Criar a página

Guarde como map.html e substitua YOUR_SHARE_ID pelo identificador copiado.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

O elemento precisa de altura; sem ela, o mapa assume 500 píxeis. Um elemento <kaleidr-map> tem display:block por predefinição, pelo que a altura se aplica. O exemplo também usa display:block para Safari anterior à versão 16.4, onde o elemento permanece inline e a altura não tem efeito.

Se não conseguir acrescentar um script à página (por exemplo, num construtor de sites ou campo CMS), use o iframe normal fornecido pelo separador iFrame do Studio. Não precisa de carregador:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. Servir a página

Abra http://localhost:8000/map.html.

O que deverá ver:

O seu mapa com 480 píxeis de altura e a largura da página, aberto na vista guardada no Studio.
Deslocar com o ponteiro sobre o mapa amplia-o. Com o ponteiro ao lado do mapa, o deslocamento move a página.
No painel Elementos, um <iframe> dentro do elemento <kaleidr-map> cujo endereço começa por https://map-embed.kaleidr.com/embed/.

Se a frame mostrar "This map isn't available — it may have been unpublished, paused, or the link is incorrect.", o identificador está errado ou o mapa não está publicado. Se mostrar "This map isn't allowed to render on this site. Please contact the map owner.", a visualização está limitada a outros domínios.

Para continuar: Incorporar um mapa explica como restringir os domínios, e Chat num mapa publicado permite aos visitantes conversar sem chave.

Um mapa base

No final terá um mapa base desenhado pela Kaleidr: um mapa interativo pronto a usar, sem biblioteca de mapas para instalar nem estilos para escrever.

1. Criar a página

Guarde como basemap.html e substitua kld_pk_live_… pela sua chave publicável.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

style-id identifica o mapa base. Defina-o sempre. kaleidr-morning é um dos estilos gerais; Tile enumera os restantes.
center usa longitude,latitude. Indique center sempre que definir zoom: um zoom sem center é ignorado.

2. Servir a página

Abra http://localhost:8000/basemap.html.

O que deverá ver:

O mapa base centrado em Midtown Manhattan, com 480 píxeis de altura.
No separador Rede, um pedido a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions devolve 200, seguido de um iframe carregado a partir de https://map-embed.kaleidr.com.
Deslocar com o ponteiro sobre o mapa amplia-o.

Se nada aparecer e a consola mostrar um erro CORS para …/sdk/sessions, a chave está errada ou a origem não está na lista, tal como na opção de chat.

Cada sessão Tile conta como um carregamento de mapa do saldo mensal da sua organização. Consulte Cotas e limites de frequência.

Para continuar: Usar Tile explica como trocar estilos durante a execução e controlar a câmara.

O que foi carregado

As três opções utilizaram os mesmos dois componentes:

Kaleidr.mount(target, options) monta um produto a partir de JavaScript e devolve imediatamente um handle. O código do produto carrega em segundo plano; as chamadas feitas antes de estar pronto são guardadas e aplicadas depois.
<kaleidr-map> faz o mesmo em HTML. Os atributos são as opções de montagem com hífenes (share-id, style-id, publishable-key), salvo duas exceções: enabled corresponde ao atributo flag, e title do chat ao atributo chat-title.

Use Kaleidr.mount para adicionar Chat ao seu próprio mapa, pois exige o objeto de mapa ativo. Para os restantes produtos pode usar qualquer uma das duas formas.

Todos os produtos têm destroy() no handle. Os restantes métodos dependem do produto: por exemplo, setCamera funciona em viewer, tile e editor, mas não em chat, onde o assistente move o mapa e pode continuar a utilizar os métodos de câmara da sua biblioteca. Consulte a matriz em Elemento <kaleidr-map>.

Limites importantes

O Chat adiciona os seus próprios marcadores, percursos e movimentos de câmara. Não altera as suas camadas ou marcadores nem os envia para a Kaleidr, e a sua página não recebe eventos do painel. Consulte Capacidades e limites.
Viewer e Tile funcionam em iframe. Não pode adicionar-lhes camadas ou marcadores. Se precisar deles, mantenha o seu mapa e ligue-lhe o Chat.
Os mapas base Kaleidr são mostrados através de Tile. Não é suportado carregar estilos ou mosaicos Kaleidr na sua biblioteca de mapas.
O SDK destina-se a páginas web. Não existe pacote npm nem SDK móvel nativo. Os backends utilizam a API de servidor.
Montagens com chave consomem o saldo. As respostas de Chat gastam créditos de IA da organização e cada sessão Tile gasta um carregamento de mapa. Consulte Como funciona a Kaleidr.

Qual o próximo passo

Pretende	Consulte
Ligar Chat ao Mapbox GL JS	Ligar Chat ao Mapbox
Ligar Chat ao MapLibre GL JS	Ligar Chat ao MapLibre
Ligar Chat ao Google Maps	Ligar Chat ao Google Maps
Ligar Chat ao Leaflet	Ligar Chat ao Leaflet
Posicionar o painel e adaptar as cores da marca	Temas e disposição
Permitir chat a visitantes num mapa publicado	Chat num mapa publicado
Incorporar um mapa e restringi-lo aos seus domínios	Incorporar um mapa
Mostrar um mapa base e trocar o estilo	Usar Tile
Inserir um editor de mapas na página	Ligar o editor
Utilizar o SDK em React, Next.js ou Vue	Frameworks
Chamar a Kaleidr a partir do seu backend	Início rápido de servidor
Responder usando os seus dados empresariais	Os seus dados
Publicar em produção	Lista de verificação de produção

Antes de começar​

Chat no seu mapa​

1. Criar a página​

2. Servir e fazer uma pergunta​

3. Se não funcionar​

Um mapa publicado​

1. Publicar e copiar o identificador​

2. Criar a página​

3. Servir a página​

Um mapa base​

1. Criar a página​

2. Servir a página​

O que foi carregado​

Limites importantes​

Qual o próximo passo​

Antes de começar

Chat no seu mapa

1. Criar a página

2. Servir e fazer uma pergunta

3. Se não funcionar

Um mapa publicado

1. Publicar e copiar o identificador

2. Criar a página

3. Servir a página

Um mapa base

1. Criar a página

2. Servir a página

O que foi carregado

Limites importantes

Qual o próximo passo