Como adicionar chat com IA a um mapa

Você pode adicionar chat com IA a um mapa que já utiliza Mapbox, Google Maps ou MapLibre sem substituir o renderizador. O aplicativo host mantém a interface, as permissões, a lógica de negócios e a conta do provedor, enquanto a Kaleidr fornece apenas a camada de conversação. Essa camada interpreta perguntas de localização, transmite dados de lugares e ações, plota os locais resolvidos e movimenta o mapa em tempo real à medida que a resposta é construída.

Adicionar o assistente não transfere todas as responsabilidades do produto para o modelo. Uma integração de produção ainda precisa de uma chave de navegador restrita por origem, dados de fontes fundamentados, tratamento do ciclo de vida específico de cada provedor, estados de erro, acessibilidade e análise. As seções a seguir abordam, em ordem, a montagem do SDK, a configuração por provedor, a segurança das chaves, a fundamentação, a experiência do usuário, os testes e as métricas que mostram se o assistente ajuda em uma tarefa real. Use este artigo como referência de arquitetura e integração, não apenas como uma visão geral de recursos. Para testar o mapa conversacional antes de conectar o SDK, comece pelo Kaleidr AI. Para entender a diferença em relação a mapas personalizados criados manualmente, consulte Kaleidr versus Google My Maps.

O que você vai criar

A experiência finalizada coordena duas superfícies que permanecem em sincronia: um mapa interativo já em execução em seu aplicativo e um painel de bate-papo de IA que o Kaleidr monta ao lado ou sobre esse mapa. Um usuário expressa um objetivo em linguagem natural, e o assistente responde em prosa e no estado do mapa ao mesmo tempo. Nenhuma superfície conduz a outra, porque o valor vem de lê-los juntos. Um pedido representativo se parece com este:

Mostra lugares familiares perto da orla que estão abertos esta tarde.

O assistente resolve a intenção geográfica, retorna os lugares relevantes, adiciona pinos ao mapa em tempo real, enquadra a área de resultado e apresenta uma resposta que o leitor pode refinar com uma pergunta de acompanhamento. O anexo de bate-papo do Kaleidr é construído exatamente em torno desse loop: a integração do product: "chat" monta a Torre de Controle do Kaleidr sobre um mapa que seu aplicativo já renderiza, detecta o renderizador, plota locais resolvidos e atualiza a câmera à medida que a conversa se move entre os locais. A documentação atual lista Mapbox, Google Maps, MapLibre e Leaflet entre instâncias de live-map suportadas — consulte a referência de anexo de bate-papo do Kaleidr e desenvolvedor quickstart. Um mapa de conversação se adequa a perguntas contextuais que resistem a filtros fixos, mas uma caixa de pesquisa convencional ainda pode ser a melhor interface para tarefas determinísticas, como localizar um ID de loja conhecido, selecionar uma categoria fixa ou exibir uma rota predefinida.

Como a arquitetura funciona

A adição de IA conversacional não transfere todas as responsabilidades para o modelo; uma implementação confiável mantém o aplicativo, o renderizador, a camada de IA, os sistemas de origem e os limites de segurança distintos. Cada camada possui um trabalho que os outros não devem executar, e essa separação é o que mantém as respostas fundamentadas e as permissões aplicáveis. O diagrama abaixo traça como uma pergunta flui através dessas camadas, e a tabela que segue nomeia cada responsabilidade.

O modelo de idioma não deve se tornar a fonte autorizada para endereços, horário de funcionamento, inventário, elegibilidade, rotas, status da propriedade ou fatos comerciais internos. A camada de IA interpreta a solicitação e coordena as ações suportadas, enquanto os serviços autorizados validam os fatos dos que a resposta depende. O contrato de streaming de Kaleidr reflete essa separação: a prosa chega de forma incremental, os lugares resolvidos chegam como eventos place estruturados, as operações de mapa podem chegar ao early_actions, as informações de origem podem chegar ao grounding e o evento final do end carrega o texto, os lugares e as ações completos. Os desenvolvedores que usam o kaleidr.js nunca analisam esses eventos manualmente, e as equipes que constroem um cliente personalizado podem seguir a referência de contrato de fio da SSE.

O que você precisa antes de começar

Antes de montar o painel de bate-papo, confirme uma pequena lista de pré-requisitos para que a integração falhe em voz alta na configuração, em vez de silenciosamente, no tempo de execução. A maioria dos problemas neste estágio remonta a um item ausente – uma origem não definida, um mapa sem altura ou uma chave sem o escopo certo. Alguns minutos gastos aqui salva uma sessão de depuração contra um erro que o navegador relata apenas indiretamente. Confirme cada um dos seguintes:

• uma instância de Mapbox, Google Maps ou MapLibre de trabalho;
• uma organização Kaleidr com acesso a API de chat;
• uma chave de navegador publicável Kaleidr que carrega o escopo ai;
• pelo menos uma origem permitida do navegador para a chave publicável ao vivo;
• o carregador kaleidr.js atual;
• um recipiente de mapa com uma altura explícita;
• um contêiner de bate-papo ou elemento personalizado suportado;
• a credencial do provedor exigida pela Mapbox ou pelo Google Maps;
• questões representativas extraídas do fluxo de trabalho real do usuário;
• sistemas definidos de fonte de verdade para quaisquer fatos operacionais.

O acesso completo à API do desenvolvedor – chaves publicáveis, chaves de servidor e suporte a incorporação – é fornecido com os planos Kaleidr Pro e Enterprise, enquanto o acesso gratuito pode expor apenas chaves de navegador com escopo de blocos de mapa. Verifique a pagina de preços atual do Kaleidr e documentação da tecla API antes de construir, para que o plano que você assuma corresponda às credenciais que você pode realmente cunhar. Se a Página de Chaves da API for restrita para sua conta, solicite o acesso da equipe do Kaleidr em vez de substituir uma credencial do servidor no código do navegador.

Como adicionar chat com IA a um mapa usando o SDK da Kaleidr

O carregador atual é uma única tag de script. Você o adiciona uma vez por página, à frente ou ao lado do próprio script do provedor, e é seguro armazenar em cache agressivamente. A tag instala o ponto de entrada global que cada chamada posterior neste guia depende.

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

O carregador instala o window. Kaleidr e o elemento <kaleidr-map>, e ele puxa o pacote de produtos selecionado em segundo plano apenas quando necessário; o próprio carregador não agrupa nem o MapLibre nem o React. O SDK suporta os produtos chat, viewer, editor e tile, portanto, siga o valor exato do produto mostrado na página atual para a incorporação específica que você criar. Para um mapa em tempo real que você já possui, a API imperativa é o caminho mais claro. O exemplo abaixo entrega o objeto de mapa existente diretamente para Kaleidr:

<div class="map-chat-layout">
  <div id="map" aria-label="Interactive location map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  function mountKaleidrChat(map) {
    if (!map) {
      throw new Error("A live map instance is required.");
    }

    return Kaleidr.mount("#chat", {
      product: "chat",
      publishableKey: "kld_pk_live_REPLACE_ME",
      map,
    });
  }
</script>

O Kaleidr.mount(target, options) retorna uma alça de forma síncrona enquanto o pacote de produtos é carregado em segundo plano e as chamadas enfileiradas nessa alça se aplicam assim que o carregamento é concluído. Mantenha a alça retornada para que o aplicativo host possa atualizar a câmera ou reduzir a integração durante as alterações de rota, switches de conta ou desmontagem de componentes. Os exemplos de provedores que se seguem combinam a configuração atual de cada renderizador com essa chamada de montagem; valide a versão do provedor fixa e o comportamento mais recente do Kaleidrd SDK na preparação antes de implantar na produção.

Adicionar chat com IA ao Mapbox

Mapbox GL JS cria uma instância mapboxgl. Map dentro de um contêiner do navegador, e requer um token de acesso. O Mapbox recomenda um token público com escopo apenas para o que o aplicativo cliente precisa, com restrições de URL aplicadas e operações de escopo secreto mantidas em um servidor. O exemplo abaixo combina essa orientação com a chamada de montagem documentada de Kaleidr. Carregue ambos os scripts, crie o mapa e monte o bate-papo assim que o mapa disparar seu evento load:

<link
  href="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.css"
  rel="stylesheet"
/>

<script src="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.js"></script>
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<div class="map-chat-layout">
  <div id="map" aria-label="Mapbox map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script>
  const map = new mapboxgl.Map({
    accessToken: "YOUR_MAPBOX_PUBLIC_TOKEN",
    container: "map",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("Mapbox error:", event.error ?? event);
  });
</script>

O guia do provedor da Kaleidr atualmente demonstra o Mapbox GL JS v3.0.0, enquanto o guia CDN do Mapbox documenta uma compilação posterior do v3.27.0, portanto, mantenha a versão que seu aplicativo já testou e confirme a compatibilidade antes de atualizar exclusivamente para essa integração. O token Mapbox e a chave publicável Kaleidr autenticam diferentes sistemas e conta separadamente: o token autentica os serviços de renderizador e Mapbox, e a chave publicável autentica o escopo do chat de IA através do SDK do navegador. As falhas de configuração mais comuns são uma altura de contabinor de mapa ausente, um token Mapbox rejeitado ou superscópico e a montagem do bate-papo antes que o aplicativo tenha estabelecido a instância do mapa.

Adicionar chat com IA ao Google Maps

O Google Maps Platform requer uma chave de API JavaScript do Maps e suporta importação dinâmica de biblioteca, carregamento direto de script e um carregador NPM. O guia oficial de integração do Kaleidr usa o padrão de retorno de chamada direto, que é a opção mais previsível para uma primeira integração. O retorno de chamada cria a instância google.maps. Map e passa diretamente para o Kaleidr.mount. O exemplo abaixo conecta a chave, o retorno de chamada e a montagem:

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

<div class="map-chat-layout">
  <div id="map" aria-label="Google map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

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

      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Google Maps or Kaleidr initialization failed:", error);
    }
  }

  window.gm_authFailure = function () {
    console.error("Google Maps authentication failed.");
  };
</script>

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

A chave do Google Maps e a chave Kaleidr servem diferentes sistemas e contas de forma independente, portanto, restringem a chave do Google aos sites e APIs necessários e restringem a chave Kaleidr para as origens exatas permitidas. A chave da API JavaScript do Google carrega e fatura o mapa do Google, enquanto o Kaleidr publica as principais cargas e fatura o recurso de bate-papo de IA. Uma distinção adicional importa: essa integração tem como alvo uma instância da API JavaScript do Google Maps dentro de um aplicativo e não anexa a um documento do Google Meu Maps, que é um produto separado.

Adicionar chat com IA ao MapLibre

MapLibre GL JS é um renderizador de navegador de código aberto para mapas de telhas vetoriais, e um aplicativo MapLibre deve fornecer um estilo mais as fontes de azulejo, glifo e sprite que estilo referências. A equipe anfitriã, portanto, possui mais do renderizador e da decisão de infraestrutura do que com um serviço de mapa totalmente gerenciado. A documentação atual do MapLibre utiliza módulos ES na versão 6. O exemplo abaixo adapta esse padrão à chamada de montagem de Kaleidr:

<link
  href="https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.css"
  rel="stylesheet"
/>

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

<div class="map-chat-layout">
  <div id="map" aria-label="MapLibre map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script type="module">
  import * as maplibregl from "https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.mjs";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://demotiles.maplibre.org/style.json",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("MapLibre error:", event.error ?? event);
  });
</script>

O guia atual do MapLibre da Kaleidr usa uma compilação global do MapLibre no estilo UMD e uma URL de estilo hospedada no Kaleidr, enquanto a documentação do provedor mudou para a versão 6 módulos ES, portanto, escolha uma versão e um método de carregamento do MapLibre consistente para o aplicativo, em vez de misturar compilações globais e de módulos. A MapLibre não fornece nenhum mapa base hospedado universal, o que significa que um fornecedor de blocos de mapa ou estilo de terceiros traz seus próprios requisitos de credenciais, atribuição, licenciamento, uso e faturamento que você deve seguir. Os blocos de mapa projetados pelo Kaleidr também podem emparelhar com o MapLibre, onde o plano atual e a configuração de estilo suportam esse fluxo de trabalho.

O que torna o assistente consciente do mapa?

Um assistente de conversação de uso geral pode descrever lugares, mas não pode coordenar com o mapa na página. Fechar essa lacuna é o que torna um assistente ciente do mapa, em vez de meramente conversacional. Um assistente ciente do mapa precisa de um loop de interação estruturado que conecta a linguagem ao estado do renderizador. Cada turno percorre a seguinte sequência:

1. O usuário envia uma pergunta de localização.
2. Kaleidr identifica lugar, área, proximidade, categoria ou intenção de rota.
3. Os serviços relevantes resolver lugares ou recuperar dados aprovados.
4. Eventos de lugar e ação estruturados fluem para o cliente.
5. A integração adiciona pinos, enquadra uma área, destaca um resultado ou aplica outra operação de mapa suportada.
6. A interface apresenta a resposta em prosa juntamente com evidências geográficas visíveis.

Kaleidr expõe o loop como um pequeno conjunto de eventos de fluxo, e cada um carrega um único tipo de resultado. O cliente se inscreve uma vez e reage a cada evento à medida que chega, em vez de esperar por uma carga útil final. A leitura do fluxo desta forma mantém a interface responsiva enquanto a resposta ainda está se formando. Os eventos documentados são:

• place carrega um local e coordenadas resolvidos;
• place_linked enriquece um local existente;
• early_actions pode levar ações de mapa antecipados, como ajustar limites ou destacar um resultado;
• grounding carrega fontes para voltas aterradas;
• end é o envelope final autorizado contendo o texto completo, lugares e ações;
• O error encerra o fluxo com uma mensagem de erro.

Trate esses eventos estruturados como o contrato de aplicativo e não raspar nomes de lugares de prosa quando o SDK ou a API já fornecer objetos de lugar resolvidos. A distinção é importante porque a prosa pode parafrasear um nome, enquanto um objeto de lugar resolvido carrega o identificador estável e coordena o renderizador precisa traçar o resultado corretamente. Construir sobre os objetos em vez do texto também mantém a integração estável quando a redação do modelo muda entre os lançamentos.

Chaves publicáveis e chaves de servidor

O Kaleidr fornece dois formulários de credenciais para os mesmos escopos de organização e capacidade, e mantê-los em linha reta é a decisão de segurança mais importante em uma integração com o navegador. A chave publicável pertence ao navegador, e a chave do servidor nunca pertence. Misturá-los é o erro mais provável de transformar uma demonstração de trabalho em uma credencial vazada. O diagrama e a tabela abaixo resumem como cada um viaja:

Uma chave publicável ao vivo sem origens permitidas é rejeitada sob o fluxo documentado, portanto, adicione origens exatas de produção e preparação quando você cunhar a chave. O cabeçalho Origin do navegador de cada solicitação é correspondido exatamente à lista, portanto, uma origem permitida deve ser uma origem nua, como https://app.example.com – esquema e host, sem nenhum caminho ou barra – e você lista todas as origens de que você serve, incluindo sua origem de desenvolvimento local. As chaves também carregam escopos de capacidade: ai para bate-papo e inferência, design para rotas de editores e maps para basemaps e blocos de mapa projetados.

A plataforma sinaliza problemas de credenciais com códigos de status distintos, e a interface deve tratar cada um de forma diferente. Uma credencial ausente, inválida, revogada ou expirada retorna 401; uma chave válida sem o escopo exigido retorna 403 com insufficient_scope; e limites de cota ou concorrência retornam 429, que a interface deve tratar como uma capacidade ou condição do plano em vez de uma falha de produto genérico. As credenciais do Mapbox e do Google Maps permanecem separadas das credenciais do Kaleidr, portanto, aplique as restrições de cada provedor de forma independente.

Fundamentar respostas de IA em dados de localização confiáveis

Alucinações relacionadas ao lugar são especialmente prejudiciais porque um mapa faz com que uma resposta incorreta pareça concreta e confiável. Um endereço errado em texto simples convida a uma segunda olhada, enquanto o mesmo erro fixado a uma coordenada é lido como verificado. A autoridade do mapa é exatamente o que a integração deve ganhar em vez de assumir. Os modos de falha comuns valem a pena nomear antes de projetar contra eles:

• uma empresa ou instalação fabricada;
• um nome de lugar ambíguo resolvido à cidade errada;
• um endereço obsoleto ou horário de abertura;
• registros duplicados que representam o mesmo local;
• uma rota solicitada através de um serviço que o aplicativo não autorizou;
• uma recomendação fora da área visível ou permitida;
• uma reivindicação operacional que entra em conflito com um sistema interno.

Uma arquitetura fundamentada mantém o modelo em sua faixa, roteando cada resposta através da resolução e recuperação, em vez de geração de forma livre. O modelo propõe intenção, e serviços autorizados decidem o que é verdade antes que qualquer coisa chegue ao mapa. Cada estágio é um ponto de verificação que o aplicativo controla, não uma etapa que o modelo executa por conta própria. O fluxo é lido em uma direção, desde as palavras do usuário até um resultado visível e verificado:

User intent → Interpretação de IA → recuperação autorizada ou resolução de lugar → ação de mapa permitida → resposta visível

Os controles práticos seguem desse fluxo. Resolva lugares em coordenadas e identificadores estáveis antes de plotar, mostre a área geográfica usada para a resposta, mantenha links de origem ou rótulos quando uma resposta for fundamentada e distinguir fatos de local público de dados operacionais privados. Rejeitar ações não suportadas em vez de improvisá-las, fornecer um estado visível sem resultado, permitir que os usuários corrigam a ambiguidade de localização e registrar o contexto de origem e inquilino usado para respostas comerciais. Acima de tudo, trate o resultado estruturado final como o contrato, em vez da prosa de forma livre que o acompanha. Para uma discussão mais ampla sobre sinais de identidade, evidência e recomendação de lugares, consulte o artigo do Kaleidr sobre Descoberta de negócios local baseada em IA e para os princípios de arquitetura e segurança por trás da superfície conversacional, consulte Adicionar um Assistente de bate-papo de IA a um Mapa Interativo.

O assistente pode usar dados comerciais privados?

Um painel de bate-papo de IA nunca deve receber acesso irrestrito ao banco de dados operacional de uma empresa, porque uma única consulta sobre-ampla pode expor muito mais do que as necessidades atuais da pergunta. A integração de dados privados, portanto, requer um design explícito de recuperação e autorização, não uma conexão aberta pela em que o modelo possa percorrer. O padrão mais seguro é não expor nada até que um conjunto de dados específico, conjunto de campo e regra de acesso justifique cada adição. Liquide os limites abaixo antes de com qualquer fonte privada para o assistente:

• quais conjuntos de dados o assistente pode consultar;
• quais atributos podem deixar o sistema de origem;
• qual usuário e inquilino poderá acessar cada registro;
• como o isolamento do inquilino é aplicado;
• quais campos são sensíveis;
• se a recuperação é executada através do backend do anfitrião;
• o que é registrado e por quanto tempo;
• como a atribuição de origem é preservada;
• quais requisitos regionais, contratuais ou de retenção se aplicam;
• quais operações requerem confirmação humana.

O Kaleidr Enterprise descreve APIs de inferência, sistemas de classificação, análise e suporte de implantação para pilhas de produtos cientes da localização, mas a documentação pública não estabelece um conector universal para cada banco de dados privado. O caminho de recuperação depende de seus próprios sistemas, modelo de permissões e restrições de conformidade, que nenhum conector genérico pode assumir em seu nome. Trate o caminho de dados privados como uma integração específica de implementação ou empresa até que a fonte exata, a autorização e o mecanismo de recuperação estejam documentados para o seu ambiente.

Padrões de UX para um chat de mapa útil

Uma integração tecnicamente correta ainda pode falhar se o chat e o mapa competirem por atenção em vez de cooperar. Um painel que esconde o mapa, ou um mapa que salta sem explicação, deixa o usuário inseguro sobre qual superfície confiar. Os padrões abaixo mantêm os dois funcionando como uma resposta, e cada um aborda uma maneira específica de que o emparelhamento tende a quebrar.

Manter o mapa visível

O mapa faz parte da resposta, não é um pano de fundo que o chat possa cobrir. No desktop, evite escondê-lo atrás de uma superfície de bate-papo em tela cheia e, no celular, use uma folha redimensionável ou um modo de bate-papo compacto que preserve o contexto do mapa suficiente para entender o resultado. Um usuário que não pode ver os pins não pode julgar se a resposta está certa.

Mostrar alterações feitas pelo assistente

Quando o assistente adiciona marcadores, muda a câmera, destaca uma área ou inicia uma rota, torna a ação perceptível. Um salto repentino no estado do mapa sem causa visível é lido como um bug, então anime ou anote a mudança. O usuário deve sempre entender por que o mapa se moveu.

Preservar os controles manuais

Os usuários ainda precisam de panorâmica, zoom, redefinição, localização, filtro e seleção direta de marcadores após o assistente agir. A IA deve adicionar um caminho de interação, não remover os caminhos de recuperação existentes em que um usuário já confia. Trate a conversa como mais um controle, ao lado dos padrões, em vez de um substituto para eles.

Oferecer desfazer e redefinir

Forneça uma maneira clara de limpar marcadores de assistente, restaurar a câmera anterior e reiniciar a conversa. Um estado de mapa irreversível cria confusão durante perguntas exploratórias, onde um usuário muitas vezes quer comparar uma resposta contra a última. Uma única acessibilidade de redefinição transforma um beco sem saída de volta em uma exploração.

Sugerir perguntas

Sugestões ensinam aos usuários o que o sistema pode fazer e reduzem solicitações vazias ou não suportadas. Baseie os exemplos no fluxo de trabalho real do produto em vez de estímulos genéricos de turismo, porque uma sugestão que espelha uma tarefa real demonstra valor e direciona o modelo para consultas que pode responder bem. Gire-os à medida que o produto cresce, de modo que o painel mantém os recursos atuais de publicidade em vez de um conjunto de partida congelado.

Projetar estados sem resultado e de erro

Distinguir um resultado sem correspondência de um lugar ambíguo, uma sessão expirada, uma origem não autorizada, um erro do provedor, uma condição de cota e uma solicitação não suportada."Algo deu errado" não é acionável o suficiente para um fluxo de trabalho de mapa, onde a etapa de recuperação difere acentuadamente entre, digamos, uma origem ruim e um conjunto de resultados vazios. Nomear a condição e oferecer o próximo passo.

Projetar para acessibilidade

Rotule a região do bate-papo e o mapa, preserve a ordem do teclado e anuncie o status de streaming sem sobrecarregar um leitor de tela. Qualquer informação transmitida apenas através da cor do marcador também deve estar disponível como texto, portanto, um usuário que não pode distinguir as cores ainda recebe a resposta completa. A acessibilidade aqui é a mesma disciplina que fundamentar: a resposta deve sobreviver sendo lida, não apenas olhada.

Eventos e métricas a acompanhar

Raw chat opens não prova valor, então instrua o assistente para medir se ele realmente ajuda os usuários a terminar uma tarefa de mapa. Os nomes dos eventos abaixo são recomendações editoriais, em vez de uma reivindicação sobre eventos de Kaleidr Analytics emitidos automaticamente. Ajuste-os para o seu próprio esquema, mas mantenha a divisão entre tentativa, sucesso e fracasso do qual as métricas dependem mais tarde. Comece a partir de um evento como este:

map_chat_opened
map_chat_question_submitted
map_chat_answer_returned
map_chat_no_result
map_chat_error
map_action_applied
map_result_selected
map_marker_opened
map_chat_followup_submitted
map_chat_shared
map_chat_to_editor

A partir desses eventos, as métricas que realmente refletem a utilidade são medidas de conclusão e resultado, em vez de volume. Abre e as contagens de perguntas descrevem o tráfego, mas não dizem nada sobre se o assistente resolveu a tarefa. Um painel útil, portanto, combina cada contagem de atividades com o resultado que deveria produzir. Peso-lo em direção às medidas que acompanham um trabalho acabado, como estes:

• taxa de conclusão de perguntas;
• taxa de sucesso de resposta;
• taxa sem resultado;
• taxa de erro técnico;
• taxa de sucesso map-action;
• resultado-seleção taxa;
• taxa de marcação-abertura;
• taxa de seguimento-questionação;
• tempo para resultado útil;
• salvar ou compartilhar a taxa;
• conversão a jusante;
• taxa de retorno de sete dias entre os usuários que completaram uma ação de mapa orientada por bate-papo.

Segmente os resultados por provedor, dispositivo, tipo de consulta, conta de cliente e fluxo de trabalho ativado, porque um número agregado se esconde onde o assistente funciona e onde não funciona. Uma alta taxa de abertura combinada com uma baixa taxa de seleção de resultados geralmente sinaliza curiosidade em vez de valor do produto, que é exatamente o erro de leitura que o rastreamento abre sozinho incentiva. A leitura dos segmentos em conjunto diz quais superfícies merecem mais investimento e quais precisam ser repensadas.

Lista de verificação de testes de produção

Os prompts de demonstração internos são geralmente mais limpos e específicos do que as perguntas que os usuários de produção realmente digitam. Testar apenas contra entradas arrumadas esconde os estados de falha que mais importam, de um lugar com erro de ortografia para uma sessão expirada. A lista abaixo mistura deliberadamente linguagem vaga, erros do provedor e eventos do ciclo de vida, porque cada um exerce uma parte diferente da integração. Exerça o assistente contra essas entradas confusas e condições de erro antes de enviar:

• perguntas vagas;
• locais de erro de orelação;
• nomes de lugares duplicados em diferentes regiões;
• um conjunto de resultados vazios;
• uma chave inválida publicável;
• uma origem não autoriada;
• uma sessão de navegador expirada;
• um âmbito de capacidade ausente;
• uma quota 429 ou resposta de concorrência;
• uma rede lenta ou interrompida;
• uma quota de provedor ou falha de autenticação;
• uma recarga de estilo de mapa;
• mudanças de redimensionamento e orientação móvel;
• navegação somente de teclado;
• rótulos de leitor de tela e atualizações ao vivo;
• um pedido não suportado;
• um pedido de dados privados não autorizados;
• bate-papo montando antes de prontidão do mapa;
• várias instâncias de mapa em uma página;
• alterações de rota e desmontagem de componentes;
• usuário, organização ou troca de inquilino.

Erros comuns de implementação

As falhas abaixo se repetem entre as integrações e cada uma tem uma correção limpa. Ninguém é exótico, e é precisamente por isso que eles são fáceis de enviar por acidente. Leia a tabela como uma lista de verificação do que quebra, por que ela quebra e o que fazer em vez disso.

Mapbox, Google Maps ou MapLibre: qual escolher?

Kaleidr é a camada de interação AI, então a decisão do renderizador ainda pertence ao produto host e não ao assistente. O renderizador certo depende do seu ferramental existente, controle de estilo e apetite de infraestrutura, nenhum dos quais a camada de bate-papo muda. A tabela abaixo resume onde cada renderizador se encaixa e o que a equipe anfitriã continua a possuir, com Kaleidr adicionado como uma camada de conversação consistente em todos os três.

Não alterne os renderizadores apenas para adicionar bate-papo quando o mapa atual já atender às necessidades de renderização do aplicativo. Passe a instância de mapa em tempo real existente para Kaleidri em vez disso e meça se a camada de conversação melhora uma tarefa de usuário específica e definida. Uma migração de renderizador é uma decisão grande e separada, e deve permanecer em sua própria renderização e méritos de infraestrutura, em vez de no recurso de bate-papo.

Lista final de verificação da implementação

• Fluxo de trabalho de mapa existente confirmado
• Prestador suportado confirmado
• Carregamentos de mapas do provedor com sucesso
• Credencial de provedor restrito
• Plano Kaleidr e acesso confirmado
• Chave publicável criada
• Âmbito ai confirmado
• Originas permitidas configuradas
• Chave do servidor excluída do código do navegador
• kaleidr.js carregado uma vez
• Instância de mapa em tempo real passada para Kaleidr.mount
• Ciclo de vida do bate-papo vinculado ao ciclo de vida do aplicativo
• Ações de mapa suportadas confirmadas
• Sistemas de origem da verdade documentados
• Não-resultados e estados de erro implementados
• Tratamento de cotas implementado
• Eventos de análise adicionados
• Revisão de segurança e privacidade concluída
• Acessibilidade testada
• Comportamento móvel testado
• Perguntas reais do usuário testadas

Conclusão

Mapbox, Google Maps e MapLibre não precisam ser substituídos para adicionar chat de IA ciente de mapa, porque o renderizador continua a possuir exibição de mapa e comportamento específico do provedor. O aplicativo host continua a possuir usuários, permissões, lógica de negócios e governança de dados, enquanto o Kaleidr adiciona a camada de conversação que resolve a intenção do local, transmite resultados de localização estruturados, plota lugares e coordena ações de mapa suportadas. As duas responsabilidades permanecem distintas, que é o que mantém a integração depurável e as respostas fundamentadas.

A integração ganha seu lugar quando a linguagem natural reduz o atrito significativo em um fluxo de trabalho de localização, não quando apenas adiciona uma caixa de bate-papo a uma página. Ele só tem sucesso quando a resposta permanece fundamentada, as credenciais do navegador e do servidor permanecem separadas, as responsabilidades do provedor permanecem explícitas e as tarefas de mapa concluídas de análise em vez da atividade de bate-papo sozinhas. Construa contra essas quatro condições, e o assistente se torna um caminho de interação genuíno, em vez de uma novidade. Equipes que também precisam de criação de mapas rápidos (não apenas o bate-papo em um mapa existente) podem começar a partir de Kaleidr Studio.

Adicione interação com IA ao mapa que você já usa

Conecte o bate-papo do Kaleidr a um mapa do Mapbox, do Google Maps ou do MapLibre que você já executa, sem trocar o renderizador. O SDK atual precisa apenas da instância do mapa em tempo real e de uma chave publicável com origem restrita, e a chamada de montagem é idêntica em todas as três. Crie uma chave com o escopo ai, adicione suas origens permitidas e passe o mapa para o Kaleidr.mount.

Obtenha uma chave de API Kaleidr

Revise a implementação completa

A documentação do desenvolvedor de Kaleidr abrange as peças que este guia resume, na profundidade, uma construção de produção precisa. O início rápido do SDK, os guias específicos do provedor e o modelo de autenticação ficam ao lado das referências de visualizador, editor, azulejo e plataforma-API. Comece por aí quando você passar de um protótipo funcional para uma integração endurecida.

Leia a documentação do desenvolvedor

Perguntas frequentes

Posso adicionar chat com IA a um mapa existente?

Sim. Sim. O produto de bate-papo da Kaleidr aceita uma instância de mapa em tempo real e atualmente documenta o anexo Mapbox, Google Maps, MapLibre e Leaflet. O renderizador existente permanece responsável por exibir o mapa, e Kaleidr adiciona a camada de conversação em cima dele.

Preciso substituir Mapbox, Google Maps ou MapLibre?

Não. Não. O aplicativo host pode manter seu renderizador existente e o Kaleidr opera como a camada de interação de IA anexada à instância do mapa em tempo real. Passar a instância do mapa para o Kaleidr.mount é suficiente – nenhuma migração do renderizador é necessária.

Como a Kaleidr se conecta a um mapa em tempo real?

Carregue o kaleidr.js, crie ou obtenha o objeto de mapa em tempo real do provedor e ligue para o Kaleidr.mount com o product: "chat", uma chave publicável e a instância do mapa. O Kaleidr detecta automaticamente o renderizador suportado e coordena marcadores e câmera através dele.

Devo usar uma chave publicável ou uma chave de servidor?

Use uma chave publicável através do SDK do navegador para embutimentos de bate-papo, editor ou azulejo e use uma chave de servidor apenas para solicitações de API de plataforma de back-end. A chave publicável é projetada para aparecer na fonte da página; a chave do servidor nunca deve fazê-lo.

Como evitar respostas inventadas sobre lugares?

Resolva lugares através de serviços de localização autorizada, use o local estruturado e eventos de fundamentação e mantenha os sistemas de negócios como fonte de verdade. Permitir listar as ações do mapa que o assistente pode tomar, e fornecer estados explícitos sem resultado e ambiguidade para que uma resposta incerta aflore em vez de inventar um lugar.

A Kaleidr paga pelo uso do Mapbox ou Google Maps?

Não. Não. A conta do provedor e a conta do Kaleidr são separadas: a Mapbox ou o Google fatura o renderizador e os serviços do provedor relacionados, e a Kaleidr fatura a capacidade de IA contra a organização do Kaleidor. Cada fornecedor aplica suas próprias restrições e cotas de forma independente.

O chat com IA é adequado para todos os mapas?

Não. Não. Uma caixa de pesquisa fixa, filtro ou controle de mapa direto é muitas vezes melhor para tarefas determinísticas simples, como abrir uma loja conhecida ou selecionar uma categoria. O chat de IA é mais útil quando os usuários precisam expressar a intenção de localização contextual, em mudança ou multivariável que os filtros fixos não podem capturar.

Referências

• Google. Load the Maps JavaScript API. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/documentation/javascript/load-maps-js-api
• Google. Google Maps Platform security guidance. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/api-security-best-practices
• Kaleidr. Attach Kaleidr AI to a Google map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-google-maps
• Kaleidr. Attach Kaleidr AI to a Mapbox map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-mapbox
• Kaleidr. Attach Kaleidr AI to a MapLibre map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-maplibre
• Kaleidr. Auth & scopes. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
• Kaleidr. Chat — attach AI to your map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/sdk/chat-attach
• Kaleidr. CORS & allowed origins. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
• Kaleidr. Get an API key. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/get-an-api-key
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 24 July 2026. https://kaleidr.com/pricing
• Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/quickstart
• Kaleidr. SSE wire contract. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/sse-wire-contract
• Mapbox. Get started with Mapbox GL JS using a CDN. Mapbox GL JS documentation. Accessed 24 July 2026. https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/
• Mapbox. How to use Mapbox securely. Mapbox Help. Accessed 24 July 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/
• MapLibre. Display a map. MapLibre GL JS documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/
• MapLibre. Map event types. MapLibre GL JS API documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapEventType/

@misc{kaleidr_chat_attach,
  title  = {Chat — attach AI to your map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/sdk/chat-attach}
}

@misc{kaleidr_auth_scopes,
  title  = {Auth \& scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_mapbox_guide,
  title  = {Attach Kaleidr AI to a Mapbox map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-mapbox}
}

@misc{kaleidr_google_maps_guide,
  title  = {Attach Kaleidr AI to a Google map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-google-maps}
}

@misc{kaleidr_maplibre_guide,
  title  = {Attach Kaleidr AI to a MapLibre map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-maplibre}
}

@misc{mapbox_cdn_guide,
  title  = {Get started with Mapbox GL JS using a CDN},
  author = {{Mapbox}},
  note   = {Mapbox GL JS documentation; accessed 24 July 2026},
  url    = {https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/}
}

@misc{google_maps_js_loader,
  title  = {Load the Maps JavaScript API},
  author = {{Google}},
  note   = {Google Maps Platform documentation; accessed 24 July 2026},
  url    = {https://developers.google.com/maps/documentation/javascript/load-maps-js-api}
}

@misc{maplibre_display_map,
  title  = {Display a map},
  author = {{MapLibre}},
  note   = {MapLibre GL JS documentation; accessed 24 July 2026},
  url    = {https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/}
}