Démarrage rapide

Cette page présente les trois intégrations fonctionnelles les plus simples, dans l'ordre habituel des équipes :

Chat sur une carte existante. Un panneau répond aux questions sur des lieux et place les résultats sur votre propre carte sous forme de repères, déplacements de caméra et itinéraires.
Une carte publiée. Une carte créée dans Kaleidr Studio et intégrée à votre page.
Un fond de carte. Un fond de carte conçu par Kaleidr, prêt à l'emploi sur votre page.

Chaque parcours utilise un seul fichier HTML. Les trois fonctionnent avec l'offre Free.

Parcours	Produit	Clé requise	Affichage
Chat sur votre carte	`chat`	Clé publiable	Dans votre page, au-dessus de votre carte
Carte publiée	`viewer`	Aucune	Dans une iframe Kaleidr
Fond de carte	`tile`	Clé publiable	Dans une iframe Kaleidr

Pour comprendre d'abord le modèle, consultez Comment fonctionne Kaleidr. Si vous hésitez entre les produits, lisez Choisir votre parcours.

Avant de commencer

Un compte Kaleidr. Inscrivez-vous sur kaleidr.com. L'offre Free suffit pour tous les exemples de cette page.
Une clé publiable pour le chat et le fond de carte. Créez-la sur kaleidr.com/api-keys ; elle commence par kld_pk_live_. Obtenir une clé API décrit la procédure. Une carte publiée ne nécessite pas de clé.
Un serveur web pour la page. Servez le fichier en HTTP, même localement. Depuis le dossier du fichier, l'une de ces méthodes convient :
```
python -m http.server 8000
# or
npx serve -l 8000
```
Ouvrez ensuite http://localhost:8000/your-file.html. N'ouvrez pas le fichier directement depuis le disque : une page file:// n'a pas d'origine utilisable dans la liste d'origines autorisées de la clé.
L'origine de la page dans les origines autorisées de la clé, si une liste existe. Une clé sans liste fonctionne depuis tout site. Avec une liste, seuls les sites indiqués sont admis : ajoutez http://localhost:8000 pendant les tests.
Une politique de sécurité du contenu permettant le chargement de Kaleidr, si votre site en définit une. Sans en-tête Content-Security-Policy, aucune configuration n'est requise. Sinon, voir Politique de sécurité du contenu.

Les trois parcours commencent par la même balise script. C'est le seul fichier chargé directement ; elle récupère le code de chaque produit lorsque vous le montez.

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

Chat sur votre carte

Vous obtiendrez une carte MapLibre GL JS avec un panneau de chat intégré. Une question comme « Où manger des ramen près de Bryant Park ? » déclenche une réponse en continu, place un repère pour chaque lieu et déplace la caméra pour les montrer.

Cet exemple utilise MapLibre GL JS. Chat peut aussi se connecter à Mapbox GL JS, à l'API JavaScript Google Maps et à Leaflet. Voir Cartes prises en charge.

1. Créer la page

Enregistrez ce fichier sous chat.html et remplacez kld_pk_live_… par votre clé publiable.

<!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; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <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', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

Trois détails de ce fichier sont importants :

La bibliothèque cartographique est globale sur la page. Le chat trouve MapLibre dans window.maplibregl. Une balise script MapLibre définit cette variable globale. Si vous l'importez depuis npm, affectez-la avant le montage : window.maplibregl = maplibregl.
map désigne l'objet carte. Passez l'instance créée, pas un sélecteur CSS.
contained: true exige un conteneur positionné et doté d'une hauteur. Le panneau apparaît dans la cible de montage. Sans contained, il s'affiche comme une fenêtre fixe en haut à gauche du navigateur.

Le style de démonstration est une carte mondiale peu détaillée. Les repères sont aux bonnes coordonnées, mais utilisez votre propre style pour voir les rues.

2. Servir la page et poser une question

Lancez un serveur local dans le dossier du fichier et ouvrez http://localhost:8000/chat.html.

Ce que vous devez voir :

La carte remplit la fenêtre, avec un panneau de chat comportant une zone de saisie en haut à gauche.
Dans l'onglet Réseau du navigateur, une requête à https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions renvoie 200 : le SDK échange votre clé contre une session temporaire.
Posez une question sur des lieux, par exemple Where can I get ramen near Bryant Park?. La réponse arrive dans le panneau, des repères apparaissent et la caméra s'ajuste. L'onglet Réseau montre une requête à …/b2b/v1/chat/control/stream qui reste ouverte pendant la réponse.
La console ne contient aucune ligne avec [kaleidr.

3. En cas de problème

Symptôme	Cause	Solution
Aucun panneau, erreur CORS pour `…/sdk/sessions` puis erreur `[kaleidr:chat]` dans la console	Clé incorrecte ou révoquée, ou origine de la page absente des origines autorisées. L'API répond sans en-têtes CORS, donc le navigateur signale un échec CORS.	Vérifiez la clé. Ajoutez l'origine exacte, port inclus, sur kaleidr.com/api-keys, ou videz la liste pendant le test.
Panneau en haut à gauche du navigateur, pas dans la carte	`contained: true` manque ou la cible n'est pas positionnée	Passez `contained: true` et donnez à la cible `position: relative` ainsi qu'une hauteur.
Le panneau répond, mais aucun repère ne s'affiche	La bibliothèque cartographique n'est pas globale, donc le chat ne peut pas créer les repères	Chargez la bibliothèque par une balise script ou définissez `window.maplibregl` avant `Kaleidr.mount`.

Dépannage détaille tous les symptômes avec leurs messages exacts dans la console.

Ensuite : Connecter Chat à MapLibre pour le guide complet et Capacités et limites pour ce que le panneau peut ou ne peut pas faire.

Une carte publiée

Vous afficherez sur votre propre page une carte conçue dans Kaleidr Studio. Aucun besoin de clé API : son identifiant public suffit.

1. Publier la carte et copier son identifiant

Ouvrez la carte dans Kaleidr Studio et choisissez Publier.
Sur la page Publier et intégrer, choisissez Mettre en ligne.
Sous Code d'intégration, copiez l'extrait. L'identifiant est la dernière partie de l'adresse : pour https://map-embed.kaleidr.com/embed/abc123, c'est abc123.

Résultat attendu : le statut du projet indique live, et l'aperçu sous le code d'intégration montre la carte telle que les visiteurs la verront.

2. Créer la page

Enregistrez sous map.html et remplacez YOUR_SHARE_ID par l'identifiant copié.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

L'élément a besoin d'une hauteur ; sinon, la carte prend une hauteur de secours de 500 pixels. <kaleidr-map> utilise display:block par défaut, donc la hauteur s'applique. L'exemple précise aussi display:block pour Safari antérieur à 16.4, où l'élément reste en ligne et ignore sa hauteur.

Si vous ne pouvez pas ajouter de script (constructeur de site ou champ CMS), utilisez l'iframe simple de l'onglet iFrame de Studio. Elle ne nécessite pas le chargeur :

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. Servir la page

Ouvrez http://localhost:8000/map.html.

Ce que vous devez voir :

Votre carte haute de 480 pixels, aussi large que la page, ouverte sur la vue enregistrée dans Studio.
Faire défiler avec le pointeur sur la carte la zoome. Avec le pointeur à côté de la carte, le défilement déplace la page.
Dans le panneau Éléments, une <iframe> dans l'élément <kaleidr-map>, dont l'adresse commence par https://map-embed.kaleidr.com/embed/.

Si l'iframe affiche "This map isn't available — it may have been unpublished, paused, or the link is incorrect.", l'identifiant est incorrect ou la carte n'est pas publique. Si elle affiche "This map isn't allowed to render on this site. Please contact the map owner.", les domaines autorisés excluent votre site.

Pour poursuivre : Intégrer une carte explique les restrictions de domaine, et Chat sur une carte publiée permet aux visiteurs de discuter sans aucune clé.

Un fond de carte

Vous afficherez un fond de carte conçu par Kaleidr : une carte interactive prête à l'emploi, sans bibliothèque à installer ni style à écrire.

1. Créer la page

Enregistrez sous basemap.html et remplacez kld_pk_live_… par votre clé publiable.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

style-id désigne le fond de carte. Précisez-le toujours. kaleidr-morning est un des styles généraux ; Tile répertorie les autres.
center contient longitude,latitude. Définissez center lorsque vous passez zoom : un zoom sans center est ignoré.

2. Servir la page

Ouvrez http://localhost:8000/basemap.html.

Ce que vous devez voir :

Le fond de carte centré sur Midtown Manhattan, haut de 480 pixels.
Dans l'onglet Réseau, une requête à https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions renvoyant 200, puis une iframe chargée depuis https://map-embed.kaleidr.com.
Faire défiler avec le pointeur sur la carte la zoome.

Si rien ne s'affiche et qu'une erreur CORS pour …/sdk/sessions apparaît dans la console, la clé est incorrecte ou votre origine n'est pas autorisée, comme pour le chat.

Chaque session Tile compte comme un chargement de carte sur le quota mensuel de votre organisation. Voir Quotas et limites de débit.

Ensuite : Utiliser Tile explique le changement de styles à l'exécution et le pilotage de la caméra.

Ce que vous avez chargé

Les trois parcours utilisent deux composants communs :

Kaleidr.mount(target, options) monte un produit depuis JavaScript et renvoie immédiatement un handle. Le code du produit se charge en arrière-plan et les appels au handle sont mis en attente puis appliqués dès que le produit est prêt.
<kaleidr-map> fait de même depuis HTML. Ses attributs reprennent les options de montage en kebab-case (share-id, style-id, publishable-key), à deux exceptions près : enabled est l'attribut flag, et title du chat est l'attribut chat-title.

Utilisez Kaleidr.mount pour le chat sur votre propre carte, car il nécessite l'objet carte actif. Pour les autres produits, les deux formes conviennent.

Chaque handle comporte destroy(). Les autres méthodes varient selon le produit : setCamera fonctionne avec viewer, tile et editor, mais pas avec chat, où l'assistant déplace lui-même votre carte tandis que votre code conserve les méthodes de caméra de sa bibliothèque. Voir la matrice dans L'élément <kaleidr-map>.

Limites à connaître

Chat ajoute ses propres repères, itinéraires et déplacements de caméra. Il ne modifie ni vos couches ni vos marqueurs et ne les envoie pas à Kaleidr. Votre page ne reçoit aucun événement du panneau. Voir Capacités et limites.
Viewer et Tile utilisent une iframe. Vous ne pouvez pas y ajouter vos propres couches ou marqueurs. Si nécessaire, conservez votre carte et connectez-y Chat.
Un fond de carte Kaleidr s'affiche grâce à Tile. Charger les styles ou tuiles Kaleidr dans votre propre bibliothèque n'est pas pris en charge.
Le SDK fonctionne dans les pages web. Aucun package npm ni SDK mobile natif. Les backends appellent l'API serveur.
Les montages avec clé consomment votre quota. Les réponses Chat dépensent les crédits IA de votre organisation et chaque session Tile compte un chargement de carte. Voir Comment fonctionne Kaleidr.

Quel parcours ensuite

Vous souhaitez	Lire
Connecter Chat à Mapbox GL JS	Connecter Chat à Mapbox
Connecter Chat à MapLibre GL JS	Connecter Chat à MapLibre
Connecter Chat à Google Maps	Connecter Chat à Google Maps
Connecter Chat à Leaflet	Connecter Chat à Leaflet
Placer le panneau et reprendre vos couleurs de marque	Thèmes et disposition
Laisser les visiteurs discuter sur une carte publiée	Chat sur une carte publiée
Intégrer une carte publiée limitée à vos domaines	Intégrer une carte
Afficher un fond de carte et changer son style	Utiliser Tile
Ajouter un éditeur de cartes à votre page	Connecter l'éditeur
Utiliser le SDK avec React, Next.js ou Vue	Frameworks
Appeler Kaleidr depuis votre backend	Démarrage rapide côté serveur
Répondre à partir de vos données d'entreprise	Vos données
Passer en production	Liste de vérification de production

Avant de commencer​

Chat sur votre carte​

1. Créer la page​

2. Servir la page et poser une question​

3. En cas de problème​

Une carte publiée​

1. Publier la carte et copier son identifiant​

2. Créer la page​

3. Servir la page​

Un fond de carte​

1. Créer la page​

2. Servir la page​

Ce que vous avez chargé​

Limites à connaître​

Quel parcours ensuite​

Avant de commencer

Chat sur votre carte

1. Créer la page

2. Servir la page et poser une question

3. En cas de problème

Une carte publiée

1. Publier la carte et copier son identifiant

2. Créer la page

3. Servir la page

Un fond de carte

1. Créer la page

2. Servir la page

Ce que vous avez chargé

Limites à connaître

Quel parcours ensuite