Ajouter Kaleidr Chat à une carte Google

À la fin du guide, votre page comporte une carte Google avec un panneau de chat ancré à l’intérieur. Le visiteur pose une question, la réponse s’affiche progressivement, les lieux cités apparaissent comme marqueurs sur votre carte et la caméra se déplace pour les montrer. Cela fonctionne sur toutes les offres, y compris Free, avec une clé publiable. Chaque question consomme des crédits IA de votre organisation.

Votre clé Google Maps et votre clé Kaleidr sont indépendantes. Google facture la carte, Kaleidr les questions. Kaleidr ne reçoit jamais votre clé Google.

Avant de commencer

Une clé publiable Kaleidr (kld_pk_live_…) obtenue sur kaleidr.com/api-keys. Les nouvelles clés ont la portée ai nécessaire à Chat. Voir Obtenir une clé API.
L’origine de votre page parmi celles autorisées par la clé, si celle-ci en limite l’utilisation ; en local, par exemple http://localhost:8080.
Une clé Google Maps JavaScript API de votre projet Google Cloud, avec l’API Maps JavaScript activée et l’origine acceptée par ses restrictions de référent.
Un serveur HTTP comme npx serve ou python -m http.server 8080. Ouvrir le fichier depuis le disque ne fonctionne pas.
Si votre site applique une Content Security Policy, autorisez les hôtes indiqués dans Content Security Policy, en plus de ceux requis par Google Maps.

L’API Google Maps JavaScript définit toujours le global google.maps. Aucune étape supplémentaire n’est donc nécessaire pour rendre la bibliothèque accessible au module de chat.

É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:relative; height:100%; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

L’élément de carte remplit le conteneur avec height:100%. L’association de position:relative et z-index:0 maintient les couches propres à Google dans l’élément de carte, sous la couche de chat.

Résultat attendu : rien pour le moment, seulement un bloc vide de 520 px de haut.

Étape 3 : charger `kaleidr.js`

Chargez le chargeur Kaleidr avec une balise script classique pour que Kaleidr existe lorsque le callback de la carte s’exécute.

<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 3 : définir le callback qui crée la carte et monte le panneau

Le script Google Maps appelle une fonction nommée par vos soins après son chargement. Créez la carte et montez le panneau dans cette fonction, car google.maps n’existe pas avant son exécution.

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

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

Résultat attendu : toujours rien. La fonction est définie, mais personne ne l’a appelée.

Étape 4 : charger le script Google Maps après le callback

Placez la balise script Google après le script qui définit initMap.

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

L’ordre est important. Le script Google est async : le navigateur l’exécute dès son téléchargement et appelle aussitôt initMap. S’il figure en premier, il peut finir avant que le navigateur ait défini initMap, ce qui entraîne l’erreur « initMap is not a function ». Définir le callback auparavant supprime cette course. (initMap)

Résultat attendu : une carte Google du centre de Londres avec une barre « Ask Kaleidr » en haut à gauche.

Page complète

Enregistrez sous index.html, remplacez les deux clés 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 Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

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

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

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

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

Fonctionnement

Visiteur	Panneau	Carte Google
Pose une question	Ouvre la fenêtre de chat ; la réponse arrive progressivement.	Rien pour le moment.
Attend	Affiche une fiche pour chaque lieu cité.	Un marqueur apparaît à mesure que chaque lieu est localisé. Pour un lieu, la carte se déplace puis zoome ; pour plusieurs, elle cadre tous les lieux avec une marge de 56 px.
Clique sur un marqueur ou résultat	Ouvre la fiche du lieu avec aperçu, photos et outil d’itinéraire.	Cliquer sur un résultat déplace la carte vers le lieu.
Demande un itinéraire	Affiche distance et durée.	Trace et cadre le trajet.
Pose une autre question	Continue la même conversation.	Ajoute de nouveaux marqueurs tout en conservant les précédents.
Ferme le chat	Revient à la barre de saisie et termine la conversation.	Supprime les marqueurs et l’itinéraire.

Particularités de Google Maps :

Les marqueurs sont des éléments HTML dessinés par une superposition personnalisée. Aucun Map ID n’est requis. Si la bibliothèque Google marker est chargée, le module de chat utilise des marqueurs avancés, qui exigent un mapId côté Google.
Le déplacement vers un lieu se fait par panoramique suivi d’un changement de zoom, et non par un seul vol animé.
Le cadrage utilise une marge de 56 px de chaque côté. Il ne tient pas compte du panneau de chat : un résultat peut être masqué derrière celui-ci. Le visiteur peut déplacer la carte ou réduire le panneau.
L’itinéraire est constitué de deux polylignes : un tracé blanc sous une ligne colorée.
La carte reste plane et orientée nord. L’assistant ne règle ni l’orientation ni l’inclinaison.
La session est renouvelée en arrière-plan tant que le panneau est 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

Aucun avertissement ni erreur ne contient [kaleidr, et aucune erreur ne provient de l’API Google Maps.

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
Aucune carte ; Google signale `initMap is not a function`	Le script Google s’est exécuté avant la définition de `initMap`.	Placez le script Google après le callback comme à l’étape 4.
Pas de carte, ou carte grise avec une erreur Google	Problème de clé Google : API Maps JavaScript non activée, facturation non configurée ou origine non autorisée.	Corrigez la configuration dans Google Cloud, indépendamment de Kaleidr.
`Kaleidr is not defined` dans `initMap`	`kaleidr.js` utilise `async` ou `defer`, ou se trouve après le script Google.	Chargez d’abord `kaleidr.js` avec une balise script classique.
La carte apparaît sans panneau, avec erreur CORS sur `…/sdk/sessions` puis `[kaleidr:chat]`	Clé Kaleidr inconnue ou révoquée, ou origine non autorisée ; sans en-têtes CORS le navigateur masque la réponse.	Vérifiez la clé et ajoutez l’origine exacte (schéma, hôte et port) sur kaleidr.com/api-keys.
`[kaleidr:chat] kaleidr session exchange failed (403)`	Clé valide, mais `detail` vaut `insufficient_scope` (pas de `ai`), `product_not_allowed` 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 …`	Une clé serveur a été transmise ; aucune requête n’a eu lieu.	Utilisez une clé publiable (`kld_pk_live_…`) et révoquez la clé serveur si elle a été exposée.
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	Le module est bloqué, souvent par la CSP ou un bloqueur de publicités.	Autorisez `https://cdn.kaleidr.com` dans `script-src`.
Le panneau apparaît dans le coin 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 reste derrière la carte	L’élément de carte n’a pas de contexte d’empilement propre.	Conservez `z-index:0` sur `#map` et `z-index:1` sur `#chat`.
Le panneau répond, mais sans marqueurs ni mouvement de carte	L’objet `map` n’est pas une instance de `google.maps.Map`, mais par exemple un élément DOM ou un wrapper.	Passez l’objet renvoyé par `new google.maps.Map(…)`. Voir Cartes prises en charge.
Le panneau répond et la carte bouge, mais sans marqueurs	La bibliothèque `marker` est chargée sans `mapId`.	Ajoutez `mapId` aux options ou ne chargez pas la bibliothèque `marker`.
Le panneau dit toujours « Sorry — that didn't go through. Please try again. »	Session expirée ou invalide après révocation de clé ou changement d’origines.	Vérifiez la clé et rechargez la page.
Le panneau dit « You've reached your usage limit for now. »	429 : crédits IA épuisés ou limite de débit de la clé atteinte, partagée par les visiteurs.	Voir Quotas et limitations de débit.

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

Limites

Votre page ne reçoit aucun callback ou événement du panneau : elle ne peut réagir par code aux questions, réponses ou clics sur marqueurs.
L’assistant ne voit ni vos superpositions, ni vos marqueurs, ni la région affichée. Seul le niveau de zoom est transmis avec une question.
Vous ne pouvez pas transmettre vos instructions ou données propres au panneau.
Langue des réponses, titre et placeholder sont des options de montage (lang, title, placeholder) : voir Référence Chat. Les autres libellés restent en anglais.
Sur Google Maps, le cadrage ne tient pas compte du panneau de chat.
handle.setCamera() ne fonctionne pas sur un montage Chat et génère un avertissement. Déplacez la caméra avec l’API Google.
Dans une application monopage, appelez handle.destroy() lors du retrait de la vue et remontez-la à son retour.

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

Étapes suivantes

Thèmes et disposition : adaptez le panneau au site.
Cartes prises en charge : possibilités sur Google Maps.
Référence Chat : options, handle et erreurs.
Liste de vérification de production : points à vérifier avant déploiement.

Avant de commencer​

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

Étape 3 : charger kaleidr.js​

Étape 3 : définir le callback qui crée la carte et monte le panneau​

Étape 4 : charger le script Google Maps après le callback​

Page complète​

Fonctionnement​

Vérifier le fonctionnement​

En cas de problème​

Limites​

Étapes suivantes​