Comment ajouter un chat IA à une carte

Vous pouvez ajouter un chat IA à une carte déjà exploitée avec Mapbox, Google Maps ou MapLibre sans remplacer son moteur de rendu. L’application hôte conserve son interface, ses autorisations, sa logique métier et son compte fournisseur, tandis que Kaleidr fournit uniquement la couche conversationnelle. Celle-ci interprète les questions géographiques, diffuse les données de lieux et d’actions, place les emplacements résolus sur la carte et déplace la carte en direct à mesure que la réponse se construit.

L’ajout de l’assistant ne transfère pas toutes les responsabilités du produit au modèle. Une intégration en production nécessite toujours une clé de navigateur limitée aux origines autorisées, des données sources fiables, une gestion du cycle de vie propre à chaque fournisseur, des états d’erreur, l’accessibilité et l’analytique. Les sections suivantes traitent successivement du montage du SDK, de la configuration par fournisseur, de la sécurité des clés, de l’ancrage des réponses, de l’UX, des tests et des indicateurs permettant de vérifier que l’assistant facilite une tâche réelle. Considérez cet article comme une référence d’architecture et d’intégration, plutôt que comme une simple présentation des fonctionnalités. Pour essayer la carte conversationnelle avant d’intégrer le SDK, commencez par Kaleidr AI ; pour comprendre la différence avec les cartes personnalisées créées manuellement, consultez Kaleidr face à Google My Maps.

Ce que vous allez construire

L'expérience terminée coordonne deux surfaces qui restent synchronisées: une carte interactive déjà en cours d'exécution dans votre application, et un panneau de discussion d'IA que Kaleidr monte à côté ou sur cette carte. Un utilisateur exprime un objectif dans le langage naturel, et l'assistant répond en prose et en état de carte en même temps. Aucune des deux surfaces ne mène l'autre, car la valeur vient de les lire ensemble. Une demande de représentant ressemble à ceci:

Montrez des endroits favorables aux familles près du front de mer qui sont ouverts cet après-midi.

L'assistant résout l'intention géographique, retourne les lieux pertinents, ajoute des épingles à la carte en direct, encadre la zone de résultat et présente une réponse que le lecteur peut affiner avec une question de suivi. La pièce jointe de chat de Kaleidr est construite autour exactement de cette boucle: l'intégration product: "chat" monte la tour de contrôle de Kaleidr sur une carte que votre application rend déjà, détecte le rendu, trace les endroits résolus et met à jour la caméra lorsque la conversation se déplace entre les emplacements. La documentation actuelle répertorie Mapbox, Google Maps, MapLibre et Leaflet parmi les instances de carte en direct prises en charge — voir la référence Kaleidr chat attachment et développeur quickstart. Une carte conversationnelle convient aux questions contextuelles qui résistent aux filtres fixes, mais une boîte de recherche classique peut toujours être la meilleure interface pour les tâches déterministes telles que localiser un identifiant de magasin connu, sélectionner une catégorie fixe ou afficher une route prédéfinie.

Fonctionnement de l’architecture

L'ajout d'IA conversationnelle ne transfère pas toutes les responsabilités au modèle; une implémentation fiable maintient l'application, le rendu, la couche d'IA, les systèmes sources et les limites de sécurité distinctes. Chaque couche possède un travail que les autres ne devraient pas effectuer, et cette séparation est ce qui maintient les réponses fondées et les autorisations exécutoires. Le diagramme ci-dessous retrace comment une question s'écoule à travers ces couches, et la table qui suit nomme chaque responsabilité.

Le modèle linguistique ne devrait pas devenir la source faisant autorité pour les adresses, les heures d'ouverture, l'inventaire, l'admissibilité, les itinéraires, l'état de la propriété ou les faits commerciaux internes. La couche d'IA interprète la demande et coordonne les actions supportées, tandis que les services faisant autorité valident les faits dont dépend la réponse. Le contrat de streaming de Kaleidr reflète cette séparation: la prose arrive progressivement, les endroits résolus arrivent à mesure que les événements place structurés, les opérations de carte peuvent arriver en early_actions, les informations de source peuvent arriver en grounding, et l'événement end final transporte le texte complet, les lieux et les actions. Les développeurs utilisant kaleidr.js n'analysent jamais ces événements à la main, et les équipes qui construisent un client personnalisé peuvent suivre la référence de contrat de fil SSE.

Prérequis

Avant de monter le panneau de discussion, confirmez une courte liste de prérequis afin que l'intégration échoue bruyamment à l'installation plutôt que silencieusement au moment de l'exécution. La plupart des problèmes à ce stade remontent à un élément manquant – une origine non définie, une carte sans hauteur ou une clé sans la bonne portée. Quelques minutes passées ici enregistre une session de débogage contre une erreur que le navigateur signale uniquement indirectement. Confirmez chacune des conditions suivantes:

• une instance de carte de travail, Google Maps ou MapLibre;
• une organisation Kaleidr avec accès à l'API de chat;
• une clé de navigateur publiable Kaleidr portant le périmètre ai;
• au moins une origine autorisée du navigateur pour la clé live publiable;
• le chargeur kaleidr.js actuel;
• un conteneur de carte avec une hauteur explicite;
• un conteneur de chat ou un élément personnalisé pris en charge;
• les informations d'identification du fournisseur requises par Mapbox ou Google Maps;
• des questions représentatives tirées du flux de travail réel de l'utilisateur;
• des systèmes de source de vérité définis pour tout fait opérationnel.

Accès complet à l'API du développeur - clés publiables, clés de serveur et support d'intégration - est livré avec les plans Kaleidr Pro et Enterprise, tandis que l'accès gratuit peut exposer uniquement les clés de navigateur à portée de tuiles. Vérifiez la page de tarification Kaleidr actuelle et documentation API-key avant de construire, de sorte que le plan que vous supposez correspond aux informations d'identification que vous pouvez réellement créer. Si la Page de clés API est restreinte pour votre compte, demandez l'accès à l'équipe de Kaleidr plutôt que de remplacer un identifiant de serveur dans le code du navigateur.

Ajouter un chat IA à une carte avec le SDK Kaleidr

Le chargeur actuel est une seule balise de script. Vous l'ajoutez une fois par page, avant ou à côté du propre script du fournisseur, et il est sûr de mettre en cache de manière agressive. La balise installe le point d'entrée global dont chaque appel ultérieur dans ce guide dépend.

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

Le chargeur installe window. Kaleidr et l'élément <kaleidr-map>, et il ne tire le paquet de produit sélectionné en arrière-plan qu'en cas de besoin; le chargeur lui-même ne regroupe ni MapLibre ni React. Le SDK prend en charge les produits chat, viewer, editor et tuiles, alors suivez la valeur exacte du produit affiché sur la page courante pour l'intégration spécifique que vous construisez. Pour une carte en direct que vous possédez déjà, l'API impérative est le chemin le plus clair. L'exemple ci-dessous donne l'objet de carte existant directement à 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>

Kaleidr.mount(target, options) retourne une poignée de manière synchrone pendant que le paquet de produits se charge en arrière-plan, et a mis en file d'attente les appels sur cette poignée s'appliquent une fois le chargement terminé. Gardez la poignée retournée afin que l'application hôte puisse mettre à jour la caméra ou réduire l'intégration lors des changements d'itinéraire, des commutateurs de compte ou du démontage du composant. Les exemples de fournisseurs qui suivent combinent la configuration actuelle de chaque renderer avec cet appel de montage; valider la version du fournisseur épinglé et le dernier comportement du SDK Kaleidr dans la mise en scène avant de vous déployer en production.

Ajouter un chat IA à Mapbox

Mapbox GL JS crée une instance mapboxgl. Map à l'intérieur d'un conteneur de navigateur, et il nécessite un jeton d'accès. Mapbox recommande un jeton public étendu uniquement à ce dont l'application cliente a besoin, avec des restrictions d'URL appliquées et des opérations de portée secrète conservées sur un serveur. L'exemple ci-dessous associe ce guidage à l'appel de montage documenté de Kaleidr. Chargez les deux scripts, créez la carte et montez le chat une fois que la carte a tiré son événement 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>

Le guide du fournisseur de Kaleidr démontre actuellement Mapbox GL JS v3.0.0, tandis que le guide CDN de Mapbox documente une version ultérieure de v3.27.0, alors gardez la version que votre application a déjà testée et confirme la compatibilité avant de la mettre à niveau uniquement pour cette intégration. Le jeton Mapbox et la clé publiée Kaleidr authentifient différents systèmes et facturent séparément: le jeton authentifie les services de rendu et de Mapbox, et la clé publiable authentifie la portée du chat de l'IA via le SDK du navigateur. Les échecs de configuration les plus courants sont une hauteur de conteneur de carte manquante, un jeton Mapbox rejeté ou sur-champé, et le montage du chat avant que l'application n'ait établi l'instance de la carte.

Ajouter un chat IA à Google Maps

Google Maps Platform nécessite une clé API Maps JavaScript, et il prend en charge l'importation dynamique de la bibliothèque, le chargement direct du script et un chargeur NPM. Le guide d'intégration officiel de Kaleidr utilise le modèle de rappel direct, qui est l'option la plus prévisible pour une première intégration. Le rappel crée l'instance google.maps. Map et la transmet directement à Kaleidr.mount. L'exemple ci-dessous câble la clé, le rappel et le montage ensemble:

<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>

La clé Google Maps et la clé Kaleidr servent différents systèmes et facturent indépendamment, donc restreignent la clé Google aux sites Web et aux API requis, et limitent la clé Kaleidr aux origines exactes autorisées. La clé API JavaScript de Google Maps charge et facture la carte Google, tandis que la clé publiée de Kaleidr charge et facture la capacité de chat de l'IA. Une autre distinction est importante: cette intégration cible une instance d'API JavaScript Google Maps à l'intérieur d'une application, et elle ne se fixe pas à un document Google My Maps, qui est un produit séparé.

Ajouter un chat IA à MapLibre

MapLibre GL JS est un navigateur open-source pour les cartes vectorielles, et une application MapLibre doit fournir un style plus les sources de tuile, de glyphe et de sprite qui font référence. L'équipe hôte possède donc plus de la décision de rendu et d'infrastructure qu'elle ne le ferait avec un service de carte entièrement géré. La documentation MapLibre actuelle utilise des modules ES dans la version 6. L'exemple ci-dessous adapte ce modèle à l'appel de montage 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>

Le guide MapLibre actuel de Kaleidr utilise une version MapLibre de style UMD global et une URL de style hébergée par Kaleidr, tandis que la documentation du fournisseur est passée aux modules ES de la version 6, alors choisissez une version et une méthode de chargement MapLibre cohérentes pour l'application plutôt que de mélanger les builds globaux et de module. MapLibre ne fournit aucune carte de base hébergée universelle, ce qui signifie qu'un fournisseur de tuiles ou de style tiers apporte ses propres exigences d'accréditation, d'attribution, de licence, d'utilisation et de facturation que vous devez suivre. Les tuiles conçus par Kaleidr peuvent également s'associer à MapLibre où le plan actuel et la configuration du style supportent ce flux de travail.

Comment l’assistant comprend-il la carte ?

Un assistant conversationnel à usage général peut décrire des lieux, mais il ne peut pas se coordonner avec la carte sur la page. Fermer cet écart est ce qui rend une carte assistante consciente plutôt que simplement conversationnelle. Un assistant de carte-saleur a besoin d'une boucle d'interaction structurée qui relie le langage à l'état de rendu. Chaque tour passe par la séquence suivante:

1. L'utilisateur soumet une question de localisation.
2. Kaleidr identifie le lieu, la zone, la proximité, la catégorie ou l'intention de l'itinéraire.
3. Les services concernés résolve des lieux ou récupère des données approuvées.
4. Les événements structurés et d'action diffusent le flux vers le client.
5. L'intégration ajoute des broches, encadre une zone, met en évidence un résultat ou applique une autre opération de carte prise en charge.
6. L'interface présente la réponse en prose avec des preuves géographiques visibles.

Kaleidr expose la boucle comme un petit ensemble d'événements de flux, et chacun porte un seul type de résultat. Le client s'abonne une fois et réagit à chaque événement à son arrivée, plutôt que d'attendre une charge utile finale. La lecture du flux de cette façon maintient l'interface réactive pendant que la réponse se forme encore. Les événements documentés sont:

• place est porteur d’un lieu et de coordonnées résolus;
• place_linked enrichit une place existante;
• early_actions peut mener des actions de carte précoces telles que des bornes ajustées ou mettre en évidence un résultat;
• grounding transporte des sources pour les virages à terre;
• end est l'enveloppe finale faisant autorité contenant le texte complet, les lieux et les actions;
• error termine le flux par un message d'erreur.

Traiter ces événements structurés comme le contrat d'application, et ne pas racler les noms de lieux de la prose lorsque le SDK ou l'API fournit déjà des objets de lieu résolus. La distinction est importante parce que la prose peut paraphraser un nom, tandis qu'un objet de place résolu porte l'identifiant stable et coordonne les besoins du rendu pour tracer correctement le résultat. La construction des objets plutôt que le texte maintient également l'intégration stable lorsque la formulation du modèle change entre les versions.

Clés publiables et clés serveur

Kaleidr fournit deux formulaires d'identification pour la même organisation et les mêmes portées de capacité, et les garder directement est la décision de sécurité la plus importante dans une intégration de navigateur. La clé publiable appartient au navigateur, et la clé du serveur ne le fait jamais. Les mélanger est l'erreur la plus susceptible de transformer une démo de travail en une accréditation divulguée. Le diagramme et le tableau ci-dessous résument comment chacun voyage:

Une clé publiable en direct sans origines autorisées est rejetée sous le flux documenté, alors ajoutez des origines exactes de production et de mise en scène lorsque vous frappent la clé. L'en-tête Origin du navigateur de chaque demande est correspondu exactement à la liste, de sorte qu'une origine autorisée doit être une origine nue telle que https://app.example.com - schéma et hôte sans chemin ou barre oblique de fuite de piste - et vous listez chaque origine à partir de qui vous servez, y compris votre origine de développement local. Les clés portent également des portées de capacité: ai pour le chat et l'inférence, design pour les itinéraires d'éditeur, et maps pour les cartes de base et les tuiles conçues.

La plate-forme signale des problèmes d'identification avec des codes d'état distincts, et l'interface devrait traiter chacun différemment. Un 401; une clé valide sans la portée requise 403 avec insufficient_scope; et les limites de contingent ou de concurrence renvoient 429, que l'interface devrait traiter comme une capacité ou une condition de plan plutôt que comme une défaillance de produit générique. Les informations d'identification Mapbox et Google Maps restent séparées des informations d'identification de Kaleidr tout au long, alors appliquez les restrictions de chaque fournisseur indépendamment.

Ancrer les réponses de l’IA dans des données de localisation fiables

Les hallucinations liées à l'endroit sont particulièrement dommageables parce qu'une carte rend une réponse incorrecte concrète et digne de confiance. Une mauvaise adresse en texte brut invite à un second regard, tandis que la même erreur épinglée à une coordonnée se lit comme vérifié. L'autorité de la carte est exactement ce que l'intégration doit gagner plutôt que d'assumer. Les modes de défaillance courants valent la peine d'être nommés avant de concevoir contre eux:

• une entreprise ou une installation fabriquée;
• un nom de lieu ambigu résolu à la mauvaise ville;
• une adresse vic-stale ou une heure d’ouverture;
• dupliquer les enregistrements représentant le même lieu;
• un itinéraire demandé par l'intermédiaire d'un service que l'application n'a pas autorisé;
• une recommandation en dehors de la zone visible ou autorisée;
• une revendication opérationnelle qui entre en conflit avec un système interne.

Une architecture à la terre maintient le modèle dans sa voie en acheminant chaque réponse par la résolution et la récupération plutôt que par la génération de forme libre. Le modèle propose de l'intention et les services faisant autorité décident de ce qui est vrai avant que quoi que ce soit n'atteigne la carte. Chaque étape est un point de contrôle que l'application contrôle, pas une étape que le modèle effectue seul. Le flux se lit dans un sens, des mots de l'utilisateur à un résultat visible, vérifié:

Itentielle de l'utilisateur → Interprétation de l'IA → récupération faisant autorité ou résolution de lieu → action de la carte autorisée → réponse visible

Les contrôles pratiques découlent de ce flux. Résoudre les places en coordonnées et en identifiants stables avant de tracer, montrer la zone géographique utilisée pour la réponse, conserver les liens sources ou les étiquettes lorsqu'une réponse est fondée et distinguer les faits du lieu public des données opérationnelles privées. Rejeter les actions non soutenues au lieu de les improviser, fournir un état de non-résultat visible, laisser les utilisateurs corriger l'ambiguïté de localisation et enregistrer le contexte source et locataire utilisé pour les réponses professionnelles. Surtout, traiter le résultat structuré final comme le contrat plutôt que la prose de forme libre qui l’accompagne. Pour une discussion plus large sur l'identité de lieu, les preuves et les signaux de recommandation, consultez l'article de Kaleidr sur découverte d'entreprise locale alimentée par l'IA, et pour les principes d'architecture et de sécurité derrière la surface conversationnelle, voir Ajouter un assistant de chat AI à une carte interactive.

L’assistant peut-il utiliser des données d’entreprise privées ?

Un panneau de discussion d'IA ne devrait jamais recevoir un accès illimité à la base de données opérationnelle d'une entreprise, car une seule requête trop large peut exposer bien plus que les besoins actuels en matière de questions. L'intégration de données privées nécessite donc une récupération explicite et une conception d'autorisation, et non une connexion ouverte, le modèle peut se promener. La valeur la plus sûre par défaut est de ne rien exposer jusqu'à ce qu'un ensemble de données spécifique, un jeu de champs et une règle d'accès justifient chaque ajout. Installez les limites ci-dessous avant de câblageer une source privée à l'assistant:

• les ensembles de données que l'assistant peut interroger;
• quels attributs peuvent quitter le système source;
• quel utilisateur et locataire peuvent accéder à chaque enregistrement;
• comment l'isolement des locataires est appliqué;
• quels champs sont sensibles;
• si la récupération passe par le backend hôte;
• ce qui est enregistré et pour combien de temps;
• comment l'attribution de la source est préservée;
• quelles exigences régionales, contractuelles ou de conservation s’appliquent;
• quelles opérations nécessitent une confirmation humaine.

Kaleidr Enterprise décrit les API d'inférence, les systèmes de classement, l'analyse et la prise en charge du déploiement pour les piles de produits de localisation, mais la documentation publique n'établit pas un connecteur universel pour chaque base de données privée. Le chemin de récupération dépend de vos propres systèmes, modèle d'autorisations et contraintes de conformité, qu'aucun connecteur générique ne peut assumer en votre nom. Traiter le chemin de données privées comme une intégration spécifique à la mise en œuvre ou à l'entreprise jusqu'à ce que la source exacte, l'autorisation et le mécanisme de récupération soient documentés pour votre environnement.

Principes UX pour un chat cartographique utile

Une intégration techniquement correcte peut encore échouer si le chat et la carte rivalisent d'attention plutôt que de coopérer. Un panneau qui cache la carte, ou une carte qui sauté sans explication, laisse l'utilisateur incertain de la surface à laquelle il faut faire confiance. Les modèles ci-dessous maintiennent les deux en fonction comme une seule réponse, et chacun aborde une façon spécifique dont l'appariement a tendance à se briser.

Garder la carte visible

La carte fait partie de la réponse, pas une toile de fond que le chat peut couvrir. Sur le bureau, évitez de le cacher derrière une surface de discussion en plein écran et sur mobile, utilisez une feuille redimensionneuse ou un mode de discussion compact qui préserve suffisamment de contexte de carte pour comprendre le résultat. Un utilisateur qui ne peut pas voir les épingles ne peut pas juger si la réponse est juste.

Rendre visibles les modifications de l’assistant

Lorsque l'assistant ajoute des marqueurs, change la caméra, met en évidence une zone ou commence un itinéraire, rendent l'action perceptible. Un saut soudain dans l'état de la carte sans cause visible se lit comme un bug, alors animez ou annotez le changement. L'utilisateur doit toujours comprendre pourquoi la carte a bouplé.

Préserver les commandes manuelles

Les utilisateurs ont toujours besoin de panoramique, de zoom, de réinitialisation, de localisation, de filtre et de sélection de marqueurs directs après que l'assistant ait atteint. L'IA devrait ajouter un chemin d'interaction, et non supprimer les chemins de récupération existants sur les que l'utilisateur se fonde déjà. Traiter la conversation comme un contrôle de plus, aux côtés des standard, plutôt que comme un remplacement pour eux.

Permettre l’annulation et la réinitialisation

Fournir un moyen clair d'effacer les marqueurs d'assistant, de restaurer la caméra précédente et de relancer la conversation. Un état de carte irréversible crée de la confusion lors de questions exploratoires, où un utilisateur veut souvent comparer une réponse à la dernière. Une seule offre de réinitialisation transforme une impasse en une exploration.

Proposer des questions

Les suggestions enseignent aux utilisateurs ce que le système peut faire et réduisent les requêtes vides ou non prises en charge. Basez les exemples sur le flux de travail réel du produit plutôt que sur les invitations touristiques génériques, car une suggestion qui reflète une tâche réelle démontre à la fois la valeur et oriente le modèle vers les requêtes auxquelles il peut bien répondre. Tournez-les au fur et à mesure que le produit se développe, de sorte que le panneau conserve les capacités actuelles de la publicité plutôt qu'un ensemble de démarrage congelé.

Concevoir les états sans résultat et les états d’erreur

Distinguer un résultat sans correspondance d'un lieu ambigu, d'une session expirée, d'une origine interdite, d'une erreur du fournisseur, d'une condition de quota et d'une demande non supportée."Quelque chose a mal tourné" n'est pas assez exploitable pour un flux de travail de carte, où l'étape de récupération diffère fortement entre, disons, une mauvaise origine et un ensemble de résultats vides. Nommez la condition et offrer la prochaine étape.

Concevoir une expérience accessible

Étiquetez la région de chat et la carte, préservez l'ordre du clavier et annoncez l'état de diffusion en continu sans accabler un lecteur d'écran. Toute information transmise uniquement par la couleur du marqueur doit également être disponible sous forme de texte, de sorte qu'un utilisateur qui ne peut pas distinguer les couleurs reçoit toujours la réponse complète. L'accessibilité ici est la même discipline que l'ancrage: la réponse doit survivre en étant lue, pas seulement regardé.

Événements et indicateurs à suivre

Les ouvertures de chat brut ne prouvent pas la valeur, alors instrumentez l'assistant pour mesurer si cela aide réellement les utilisateurs à terminer une tâche de carte. Les noms des événements ci-dessous sont des recommandations éditoriales plutôt qu'une affirmation sur les événements Kaleidr Analytics émis automatiquement. Ajustez-les à votre propre schéma, mais gardez la division entre la tentative, le succès et l'échec sur lequel les métriques dépendent plus tard. Commencez à partir d'un ensemble d'événements comme celui-ci:

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

À partir de ces événements, les mesures qui reflètent réellement l'utilité sont les mesures d'achèvement et de résultats plutôt que le volume. Les nombres d'ouvertures et de questions décrivent le trafic, mais ils ne disent rien sur la question de savoir si l'assistant a résolu la tâche. Un tableau de bord utile associe donc chaque nombre d’activités au résultat qu’il était censé produire. Pondérez-le vers les mesures qui suivent un travail terminé, tels que ceux-ci:

• question taux d'achèvement;
• répondre à ses taux de réussite;
• taux de non-résulte;
• taux d'erreur technique;
• taux de réussite map-action;
• taux de sélection des résultats;
• taux d'ouverture de marqueur;
• taux de suivi des questions;
• temps pour un résultat utile;
• sauver ou partager du taux;
• conversion en aval;
• Taux de retour de sept jours parmi les utilisateurs qui ont effectué une action de carte axée sur le chat.

Segmentez les résultats par fournisseur, appareil, type de requête, compte client et flux de travail activé, car un nombre agrégé se cache où l'assistant fonctionne et où il ne fonctionne pas. Un taux d'ouverture élevé associé à un faible taux de sélection de résultats signale généralement la curiosité plutôt que la valeur du produit, ce qui est exactement la lecture erronée que le suivi ouvre seul encourage. La lecture des segments ensemble vous indique quelles surfaces méritent plus d’investissements et qui doivent être repensées.

Liste de contrôle des tests en production

Les invites de démonstration internes sont généralement plus propres et plus spécifiques que les questions que les utilisateurs de production tapent réellement. Le test uniquement contre les entrées bien rangées cache les états d'échec qui comptent le plus, d'un lieu mal orthographié à une session expirée. La liste ci-dessous mélange délibérément le langage vague, les erreurs du fournisseur et les événements du cycle de vie, car chacun exerce une partie différente de l'intégration. Exercez l'assistant contre ces entrées désordonnées et conditions d'erreur avant d'expédier:

• questions vagues;
• lieux mal orthographiés;
• dupliquer les noms de lieux dans différentes régions;
• un jeu de résultats vide;
• une clé publiable invalide;
• une origine interdite;
• une session de navigateur expirée;
• une portée de capacité manquante;
• une réponse au contingent ou à la concurrence de 429;
• un réseau lent ou interrompu;
• un quota de fournisseur ou une défaillance d'authentification;
• un rechargement de style de carte;
• le resizing mobile et les changements d’orientation;
• navigation uniquement par clavier;
• les étiquettes de lecteur d'écran et les mises à jour en direct;
• une demande non supportée;
• une demande de données privées non autorisée;
• montage de chat avant préparation de la carte;
• plusieurs instances de carte sur une page;
• changements de route et démontage des composants;
• l'utilisateur, l'organisation ou le locataire qui bascule.

Erreurs d’implémentation courantes

Les défaillances ci-dessous se reproduisent à travers les intégrations, et chacune a une correction propre. Aucun n'est exotique, c'est précisément pourquoi ils sont faciles à expédier par accident. Lisez le tableau comme une liste de contrôle de ce qui se brise, pourquoi il se casse et ce qu'il faut faire à la place.

Mapbox, Google Maps ou MapLibre : que choisir ?

Kaleidr est la couche d'interaction de l'IA, de sorte que la décision de rendu appartient toujours au produit hôte plutôt qu'à l'assistant. Le bon rendu dépend de votre outillage existant, de votre contrôle de style et de votre appétit d'infrastructure, aucun de ceux dont la couche de discussion ne change. Le tableau ci-dessous résume où chaque renderer s'adapte et ce que l'équipe hôte continue de posséder, Kaleidr étant ajouté comme couche conversationnelle cohérente sur les trois.

Ne pas changer de rendu uniquement pour ajouter du chat lorsque la carte actuelle répond déjà aux besoins de rendu de l'application. Passez plutôt l'instance de carte en direct existante à Kaleidr, et mesurez si la couche conversationnelle améliore une tâche utilisateur spécifique et définie. Une migration de rendu est une décision importante et distincte, et elle devrait se tenir sur ses propres mérites de rendu et d'infrastructure plutôt que sur la fonctionnalité de chat.

Liste de contrôle finale de l’implémentation

• Le flux de travail de la carte existante confirmé
• Rendeur supporté confirmé
• Charges de carte de fournisseur avec succès
• Prescrigences restreints du fournisseur
• Plan de Kaleidr et accès confirmé
• • clé publiable créée
• Champ d'application de ai confirmé
• Origines autorisées configurées
• Touche de serveur exclue du code du navigateur
• kaleidr.js chargé une fois
• Instance de carte en direct passée à Kaleidr.mount
• Cycle de vie du chat lié au cycle de vie de l'application
• Actions cartographiques appuyées confirmées
• Systèmes de source de vérité documentés
• États de non-résulte et d'erreurs mis en œuvre
• Gestion des quotas mise en œuvre
• Événements analytiques ajoutés
• Examen de sécurité et de confidentialité terminé
• Accessibilité testée
• Le comportement mobile testé
• Vraies questions d'utilisateur testées

Conclusion

Mapbox, Google Maps et MapLibre n'ont pas besoin d'être remplacés pour ajouter un chat d'IA conscient de la carte, car le rendu continue de posséder un affichage de la carte et un comportement spécifique au fournisseur. L'application hôte continue de posséder des utilisateurs, des autorisations, une logique d'entreprise et une gouvernance des données, tandis que Kaleidr ajoute la couche conversationnelle qui résout l'intention du lieu, diffuse les résultats de localisation structurés, trace les lieux et coordonne les actions de carte prises en charge. Les deux responsabilités restent distinctes, ce qui maintient l'intégration débuggable et les réponses fondées.

L'intégration gagne sa place lorsque le langage naturel réduit les frictions significatives dans un flux de travail de localisation, et non lorsqu'il ajoute simplement une boîte de discussion à une page. Il ne réussit que lorsque la réponse reste ancrée, que les informations d'identification du navigateur et du serveur restent séparées, que les responsabilités du fournisseur restent explicites et que l'analyse mesure les tâches cartographiques terminées plutôt que l'activité de chat seule. Construisez contre ces quatre conditions, et l'assistant devient un véritable chemin d'interaction plutôt qu'une nouveauté. Les équipes qui ont également besoin d'une création de carte rapide (pas seulement le chat sur une carte existante) peuvent commencer à partir de Kaleidr Studio.

Ajoutez une interaction IA à votre carte existante

Connectez le chat Kaleidr à une carte Mapbox, Google Maps ou MapLibre que vous exécutez déjà, sans échanger votre renderer. Le SDK actuel n'a besoin que de l'instance de carte en direct et d'une clé publiable restreinte à l'origine, et l'appel de montage est identique sur les trois. Créez une clé avec la portée ai, ajoutez vos origines autorisées et passez la carte à Kaleidr.mount.

Obtenir une clé API Kaleidr

Examinez l’implémentation complète

La documentation du développeur de Kaleidr couvre les éléments que ce guide résume, en profondeur, les besoins de construction de la production. Le SDK quickstart, les guides spécifiques au fournisseur et le modèle d'authentification sont assis aux côtés des références du visualiseur, de l'éditeur, de la tuile et de l'API de la plate-forme. Commencez par vous déplacer d'un prototype fonctionnel à une intégration durcie.

Lire la documentation du développeur

Questions fréquentes

Puis-je ajouter un chat IA à une carte existante ?

Oui. Le produit de chat de Kaleidr accepte une instance de carte en direct et documente actuellement Mapbox, Google Maps, MapLibre et la pièce jointe. Le rendu existant reste responsable de l'affichage de la carte, et Kaleidr ajoute la couche conversationnelle sur elle.

Dois-je remplacer Mapbox, Google Maps ou MapLibre ?

Non. L'application hôte peut conserver son rendu existant, et Kaleidr fonctionne comme la couche d'interaction d'IA attachée à l'instance de carte en direct. Passer l'instance de la carte à Kaleidr.mount est suffisant - aucune migration de rendu n'est nécessaire.

Comment Kaleidr se connecte-t-il à une carte en direct ?

Chargez kaleidr.js, créez ou obtenez l'objet de carte en direct du fournisseur, et appelez Kaleidr.mount avec product: "chat", une clé publiable et l'instance de la carte. Kaleidr détecte automatiquement le rendu pris en charge et coordonne les marqueurs et la caméra à travers lui.

Faut-il utiliser une clé publiable ou une clé serveur ?

Utilisez une clé publiable via le SDK du navigateur pour le chat, l'éditeur ou les intégrations de tuiles, et utilisez une clé serveur uniquement pour les requêtes d'API de la plate-forme backend. La clé publiable est conçue pour apparaître dans la source de la page; la clé du serveur ne doit jamais le faire.

Comment éviter les réponses inventées sur les lieux ?

Résoudre les lieux par le biais de services de localisation faisant autorité, utiliser le lieu structuré et les événements de base, et garder les systèmes d'affaires comme source de vérité. Autoriser les actions de la carte que l'assistant peut prendre, et fournir un non-résultat explicite et des états d'ambiguïté afin qu'une réponse incertaine se présente plutôt que d'inventer un lieu.

Kaleidr prend-il en charge les coûts de Mapbox ou Google Maps ?

Non. Le compte fournisseur et le compte Kaleidr sont distincts: Mapbox ou Google facture le rendu et les services de fournisseur connexes, et Kaleidr facture la capacité d'IA contre l'organisation Kaleidr. Chaque fournisseur applique ses propres restrictions et quotas de manière indépendante.

Le chat IA convient-il à toutes les cartes ?

Non. Une boîte de recherche fixe, un filtre ou un contrôle direct de la carte est souvent mieux pour les tâches déterministes simples, telles que l'ouverture d'un magasin connu ou la sélection d'une catégorie. Le chat d'IA est le plus utile lorsque les utilisateurs doivent exprimer une intention de localisation contextuelle, changeante ou multi-variable que les filtres fixes ne peuvent pas capturer.

Références

• 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/}
}