Adicionar Kaleidr Chat a um mapa Google

Ao final deste guia, você terá uma página com mapa Google e painel de chat encaixado nele. O visitante faz uma pergunta, a resposta aparece em tempo real no painel e os locais são marcados no Google Maps enquanto a câmera se ajusta. Funciona em qualquer plano, inclusive Free, usando uma chave publicável. Perguntas consomem créditos de IA da organização.

Sua chave do Google Maps e a chave Kaleidr são separadas. O Google cobra pelo mapa; a Kaleidr cobra pelas perguntas. A Kaleidr nunca recebe sua chave Google.

Antes de começar

Chave publicável Kaleidr (kld_pk_live_…) obtida em kaleidr.com/api-keys. Novas chaves incluem o escopo ai necessário ao Chat. Veja Obter uma chave de API.
Origem da página entre as origens permitidas da chave, quando houver restrições. Para trabalho local, adicione por exemplo http://localhost:8080.
Chave da API JavaScript do Google Maps no projeto Google Cloud, com a API habilitada e a origem autorizada nas restrições de referenciador.
Servidor HTTP, como npx serve ou python -m http.server 8080. Abrir o arquivo diretamente do disco não funciona.
Caso haja Content Security Policy, autorize os hosts em Content Security Policy, além dos exigidos pelo Google Maps.

A API JavaScript do Google Maps sempre define o global google.maps; não é necessário expor a biblioteca de outra forma ao bundle de chat.

Etapa 1: organizar o mapa e a camada de chat

Coloque o mapa e o destino de montagem do chat em um único contêiner posicionado. A camada de chat fica sobre o mapa, mas permite a passagem de eventos do ponteiro.

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:relative; height:100%; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

O elemento do mapa ocupa o contêiner com height:100%. position:relative e z-index:0 mantêm as camadas do Google dentro dele, atrás da camada de chat.

Resultado esperado: apenas um bloco vazio de 520 px de altura.

Etapa 3: carregar `kaleidr.js`

Carregue o loader Kaleidr por uma tag script comum, de modo que Kaleidr exista quando o callback do mapa for executado.

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

Resultado esperado: nenhuma mudança visual. No console, Kaleidr.version retorna uma string de versão.

Etapa 3: defina o callback que cria o mapa e monta o painel

O script Google Maps chama a função nomeada quando termina de carregar. Crie o mapa e monte o painel dentro dela, porque google.maps ainda não existe antes disso.

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

    Kaleidr.mount('#chat', {
      product: 'chat',
      publishableKey: 'kld_pk_live_…',
      map,
      contained: true,
    });
  }
</script>

Resultado esperado: ainda nada. A função está definida, mas não foi chamada.

Etapa 4: carregue o script do Google Maps após o callback

Coloque a tag do Google abaixo do script que define initMap.

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

A ordem é importante. O script Google usa async e chama initMap assim que termina de baixar. Se a tag vier antes da definição, poderá terminar antes de o navegador encontrar a função, gerando “initMap is not a function”. Definir o callback primeiro elimina essa condição de corrida. (initMap; initMap)

Resultado esperado: um mapa do centro de Londres com campo Ask Kaleidr no canto superior esquerdo.

A página completa

Salve como index.html, substitua as duas chaves e sirva a pasta por HTTP.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

        Kaleidr.mount('#chat', {
          product: 'chat',
          publishableKey: 'kld_pk_live_…',
          map,
          contained: true,
        });
      }
    </script>

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

Como funciona

Visitante	Painel	Seu mapa Google
Envia pergunta	Abre janela de chat; resposta chega em streaming.	Sem mudança inicial.
Aguarda	Exibe cartão para cada local.	Pinos surgem à medida que são localizados. Um local: o mapa se desloca e altera o zoom; vários: enquadra-os com margem de 56 px.
Clica em pino ou resultado	Abre cartão com descrição, fotos e direções.	Ao clicar no resultado, move até o local.
Solicita rota	Mostra distância e duração.	Traça e enquadra a linha de rota.
Faz nova pergunta	Continua na mesma conversa.	Acrescenta pinos, preservando os anteriores.
Fecha chat	Retorna ao campo inicial e encerra a conversa.	Remove pinos e rota.

Aspectos específicos do Google Maps:

Pinos são elementos HTML desenhados em overlay personalizado. Isso dispensa Map ID. Se a página carrega a biblioteca marker, o bundle usa marcadores avançados e o Google exige mapId.
Mover para um local é deslocamento seguido de alteração de zoom, não um voo animado único.
O enquadramento usa margem de 56 px em todos os lados. Não compensa a área do painel; algum resultado pode ficar coberto, e o visitante pode deslocar o mapa ou minimizar o chat.
A rota usa duas polilinhas: contorno branco sob linha colorida.
O mapa é tratado como plano e orientado ao norte. O assistente não altera direção ou inclinação.
A sessão é renovada automaticamente enquanto o painel estiver montado. Você não gerencia tokens.

Verificar se funcionou

Na página

A barra Ask Kaleidr aparece sobre o canto superior esquerdo do mapa.
Digite Show me three museums in London e pressione Enter. O texto aparece progressivamente, três marcadores são exibidos e o mapa os enquadra.

No console

Nenhum erro ou aviso contendo [kaleidr nem erro da API Google Maps.

Na guia Network

Requisição	Resultado esperado
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200, com corpo JSON como no exemplo seguinte
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (após uma pergunta)	200, `content-type: text/event-stream`

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat" }

Se não funcionar

O SDK registra uma mensagem breve sem repetir o motivo do servidor. Se uma requisição falhar, abra-a em Network e leia a resposta JSON. Um 403 ou 404 traz o código em detail; um 429 o traz em error, com uma frase em detail.

Sintoma	Causa	Correção
Sem mapa, Google indica `initMap is not a function`	Script Google executado antes da definição de `initMap`.	Mova a tag Google para depois do callback (etapa 4).
Mapa cinza ou erro Google	Problema na chave Google: API desativada, faturamento pendente ou origem bloqueada.	Corrija no Google Cloud, independentemente da Kaleidr.
`Kaleidr is not defined` dentro de `initMap`	`kaleidr.js` usa `async`/`defer` ou carrega depois do Google.	Carregue-o primeiro sem esses atributos. `kaleidr.js`
Mapa aparece, painel não; erro CORS `…/sdk/sessions`	Chave Kaleidr desconhecida/revogada ou origem não autorizada.	Verifique a chave e a origem exata em kaleidr.com/api-keys. `[kaleidr:chat]`
`[kaleidr:chat] kaleidr session exchange failed (403)`	Falta escopo `ai`, `product_not_allowed` ou `tier_capability_not_allowed`.	Use chave com `ai` e produto `chat`. `detail` `insufficient_scope`
Aviso de server key kld_sk_…	Chave de servidor exposta no navegador.	Use `kld_pk_live_…` e revogue a chave de servidor publicada. `[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`
Falha em carregar https://cdn.kaleidr.com/embed/v1/chat.js	CSP ou bloqueador de anúncios.	Autorize `https://cdn.kaleidr.com` em `script-src`. `[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`
Painel no canto da janela, não do mapa	Falta `contained` ou posicionamento de `#chat`.	Use `contained: true` e estilos da etapa 1.
Painel atrás do mapa	Falta contexto de empilhamento no mapa.	Use `z-index:0` em `#map` e `z-index:1` em `#chat`.
Resposta sem pinos ou movimento	Objeto passado como `map` não é `google.maps.Map`.	Passe a instância de `new google.maps.Map(…)`. Veja Mapas compatíveis.
Mapa move sem pinos	Biblioteca `marker` carregada sem `mapId`.	Adicione `mapId` ou não carregue `marker`.
Mensagem “Sorry — that didn't go through. Please try again.”	Sessão inválida por chave revogada ou origens alteradas.	Confira a chave e recarregue.
“You've reached your usage limit for now.”	429: créditos de IA ou limite de taxa da chave esgotados.	Veja Cotas e limites de taxa.

Mais sintomas estão em Resolução de problemas.

Limitações

A página não recebe callbacks ou eventos do painel; não pode reagir programaticamente a perguntas, respostas ou cliques.
O assistente não vê seus overlays, marcadores ou área exibida, apenas o zoom enviado nas perguntas.
Não é possível fornecer instruções ou dados próprios pelo painel.
Idioma da resposta, título e placeholder são opções lang, title, placeholder, veja Referência do Chat. Os outros rótulos permanecem em inglês.
O enquadramento do Google Maps não evita a área do painel.
handle.setCamera() não funciona em Chat; gera aviso. Mova com a API do Google.
Em SPA, chame handle.destroy() ao remover a visualização e remonte quando retornar.

A lista completa está em Recursos e limitações.

Próximos passos

Tema e layout: adapte o painel ao seu site.
Mapas compatíveis: recursos de Chat no Google Maps.
Referência do Chat: opções, handle e erros.
Checklist de produção: verificações antes do lançamento.

Antes de começar​

Etapa 1: organizar o mapa e a camada de chat​

Etapa 3: carregar kaleidr.js​

Etapa 3: defina o callback que cria o mapa e monta o painel​

Etapa 4: carregue o script do Google Maps após o callback​

A página completa​

Como funciona​

Verificar se funcionou​

Se não funcionar​

Limitações​

Próximos passos​