Ajouter Kaleidr Chat à une carte MapLibre

À la fin du guide, votre page contient une carte MapLibre GL JS avec un panneau de chat intégré. Le visiteur pose une question : la réponse s’affiche progressivement, les lieux apparaissent sous forme de marqueurs sur la carte et la caméra se déplace pour les montrer. Compatible avec toutes les offres, dont Free, à l’aide d’une clé publiable. Les questions consomment les crédits IA de votre organisation.

Le panneau fonctionne avec le style déjà utilisé par votre carte. Il ne modifie ni le style ni la source de tuiles.

Avant de commencer

Une clé publiable Kaleidr (kld_pk_live_…) sur kaleidr.com/api-keys, dotée de ai pour Chat. Voir Obtenir une clé API.
L’origine de la page parmi celles autorisées, si la clé les limite ; en local, par exemple http://localhost:8080.
Une URL de style MapLibre. L’exemple utilise le style de démonstration public de MapLibre ; utilisez le vôtre en production.
MapLibre GL JS chargé par script, de manière à exposer window.maplibregl. Pour npm, voir Rendre une bibliothèque npm globale.
Un serveur HTTP, par exemple npx serve ou python -m http.server 8080. L’ouverture depuis le disque ne fonctionne pas.
Si votre site applique une Content Security Policy, autorisez les hôtes de Content Security Policy.

Étape 1 : disposer la carte et la couche de chat

Placez la carte et la cible de montage du chat dans un même conteneur positionné. La couche du chat se superpose à la carte tout en laissant passer les événements de pointeur.

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

Résultat attendu : rien encore, seulement un bloc vide de 520 px. Thèmes et disposition explique chaque déclaration.

Étape 2 : charger MapLibre GL JS et créer la carte

Chargez la feuille de style dans l’en-tête et le script avant votre code. Les deux URL doivent correspondre à la même version.

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json', // your own style here
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

Résultat attendu : une carte déplaçable et zoomable. Le style de démonstration montre des pays simples avec peu de détails urbains ; marqueurs et mouvements de caméra fonctionnent tout de même.

Étape 3 : charger `kaleidr.js`

Ajoutez le chargeur après le script MapLibre et avant le code qui monte le panneau.

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

Résultat attendu : aucune modification visible. Dans la console, Kaleidr.version renvoie une chaîne de version.

Étape 4 : monter le panneau de chat

Fournissez votre clé et l’objet de carte actif.

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
});

Il n’est pas nécessaire d’attendre l’événement load de la carte. Kaleidr.mount renvoie immédiatement ; le panneau apparaît une fois le module de chat chargé et la clé échangée contre une session.

Résultat attendu : une barre de saisie « Ask Kaleidr » en haut à gauche de la carte.

Page complète

Enregistrez le fichier sous index.html, remplacez la clé et servez le dossier en 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 MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; 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>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

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

Fonctionnement

Visiteur	Panneau	Carte MapLibre
Envoie une question	Ouvre une fenêtre de chat ; le texte de réponse arrive progressivement.	Rien pour le moment.
Attend	Affiche une fiche pour chaque lieu cité.	Un marqueur apparaît dès qu’un lieu est localisé. Pour un lieu, la caméra s’y déplace ; pour plusieurs, elle ajuste le cadrage en évitant le panneau.
Clique sur un marqueur ou résultat	Ouvre une fiche avec présentation, photos et outil d’itinéraire.	Cliquer sur un résultat déplace la caméra vers ce lieu.
Demande un itinéraire	Affiche la distance et la durée du trajet.	Trace et cadre la ligne de l’itinéraire.
Pose une autre question	Ajoute la question à la même conversation.	Ajoute de nouveaux marqueurs ; les précédents restent.
Ferme le chat	Revient à la barre de saisie ; la conversation se termine.	Les marqueurs et l’itinéraire sont retirés.

Particularités de MapLibre GL JS :

Les épingles sont des objets Marker de MapLibre utilisant un élément HTML, distincts des marqueurs que vous avez ajoutés.
L’itinéraire est dessiné avec des sources et couches ajoutées au style par le panneau puis supprimées. Vos propres sources et couches ne sont pas modifiées.
La session est renouvelée automatiquement tant que le panneau reste monté. Vous ne gérez aucun jeton.

Vérifier le fonctionnement

Sur la page

La barre Ask Kaleidr apparaît en haut à gauche de la carte.
Saisissez Show me three museums in London, puis appuyez sur Entrée. Le texte apparaît progressivement, trois marqueurs s’affichent et la carte les cadre tous.

Dans la console

Aucune erreur ni aucun avertissement ne contient [kaleidr.

Dans l’onglet Réseau

Requête	Résultat attendu
`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, avec un corps JSON semblable à l’exemple ci-dessous
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (après une question)	200, `content-type: text/event-stream`

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

En cas de problème

Le SDK affiche un message bref sans recopier le motif renvoyé par le serveur. Si une requête échoue, ouvrez-la dans Réseau pour lire sa réponse JSON. Un 403 ou 404 place son code dans detail. Un 429 place son code dans error, accompagné d’une phrase dans detail.

Symptôme	Cause	Correction
Panneau absent, erreur CORS sur `…/sdk/sessions` puis erreur `[kaleidr:chat]`	Clé inconnue ou révoquée, ou origine non autorisée. L’API n’envoie les en-têtes CORS qu’aux origines admises.	Vérifiez la clé et ajoutez l’origine exacte (schéma et port compris) sur kaleidr.com/api-keys.
`[kaleidr:chat] kaleidr session exchange failed (403)`	Clé valide, mais non autorisée pour Chat. `detail` vaut `insufficient_scope` (portée `ai` absente), `product_not_allowed` (autres produits seulement) ou `tier_capability_not_allowed`.	Utilisez une clé avec `ai` qui autorise `chat`.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	Vous avez passé une clé serveur ; aucune requête n’a été envoyée.	Utilisez une clé publiable (`kld_pk_live_…`). Révoquez la clé serveur si elle a été exposée publiquement.
`[kaleidr:chat] mount target not found: #chat`	Le sélecteur ne trouve aucun élément.	Appelez `mount` après la création de l’élément ou passez l’élément lui-même. `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	Module bloqué, généralement par la CSP ou un bloqueur de publicités.	Autorisez `https://cdn.kaleidr.com` dans `script-src`.
`Kaleidr is not defined`	Votre code a été exécuté avant `kaleidr.js`, par exemple à cause de `async` ou `defer`.	Chargez `kaleidr.js` sans ces attributs avant votre code, ou déclenchez le code à l’événement `load`.
`[kaleidr] embed is disabled — …`	Le contrôle d’activation bloque les montages.	Le message indique quel contrôle a été activé. Voir kaleidr.js.
Le panneau apparaît en haut à gauche de la fenêtre, pas sur la carte	`contained` manque ou `#chat` n’est pas positionné.	Ajoutez `contained: true` et les styles de l’étape 1.
Le panneau répond, mais aucun marqueur ni déplacement	L’objet passé dans `map` n’est pas reconnu.	Passez directement l’instance `maplibregl.Map`. Voir Cartes prises en charge.
La caméra se déplace vers un lieu, mais pas de marqueurs ni de cadrage multiple	`window.maplibregl` n’existe pas. Un déplacement simple n’utilise que l’objet de carte ; les marqueurs et le cadrage nécessitent le global.	Si MapLibre est importé avec npm, définissez `window.maplibregl` avant le montage. Voir Imports npm.
Le panneau dit toujours « Sorry — that didn't go through. Please try again. »	Session devenue invalide : clé révoquée ou origines autorisées modifiées.	Vérifiez la clé et rechargez la page.
Le panneau dit « You've reached your usage limit for now. »	Erreur 429 : crédits IA épuisés ou limite du débit atteinte. Tous les visiteurs utilisent la même limite de clé.	Voir Quotas et limitations de débit.
La carte ne se laisse plus déplacer	La couche de chat intercepte les événements.	Ajoutez `pointer-events:none` à `#chat`.

D’autres cas figurent sur la page Dépannage.

Limites

Votre page ne reçoit ni callback ni événement du panneau et ne peut réagir par code à une question, une réponse ou un clic sur un marqueur.
L’assistant ne voit pas vos couches, vos marqueurs ni la zone affichée. Seul le niveau de zoom accompagne la question.
Vous ne pouvez pas transmettre vos instructions ou données propres à l’assistant par le panneau.
La langue des réponses, le titre et le texte indicatif sont définis au montage (lang, title, placeholder) : voir Référence Chat. Les autres libellés restent en anglais.
handle.setCamera() n’a aucun effet sur un montage Chat et affiche un avertissement. Déplacez la caméra avec l’API de MapLibre.
Dans une application monopage, appelez handle.destroy() lorsque la vue cartographique disparaît, puis remontez-la au retour.
Le panneau ne fournit pas de fond de carte. Pour afficher celui de Kaleidr, utilisez Tile, dans son propre élément, que le chat peut piloter via map-target.

La liste complète se trouve dans Capacités et limites.

Étapes suivantes

Thèmes et disposition : assortissez le panneau à votre site.
Référence Chat : toutes les options, le handle et les erreurs.
Liste de vérification de production : contrôles avant mise en ligne.
Frameworks : montage sous React, Next.js et Vue.

Avant de commencer​

Étape 1 : disposer la carte et la couche de chat​

Étape 2 : charger MapLibre GL JS et créer la carte​

Étape 3 : charger kaleidr.js​

Étape 4 : monter le panneau de chat​

Page complète​

Fonctionnement​

Vérifier le fonctionnement​

En cas de problème​

Limites​

Étapes suivantes​