Utiliser un fond de carte Kaleidr

À la fin de ce guide, votre page affichera un fond de carte interactif Kaleidr dans le style et avec la caméra choisis. Votre code pourra déplacer la caméra et changer de style. Cela fonctionne sur toutes les offres, y compris Free, avec une clé publiable dotée de la portée maps, présente par défaut sur les nouvelles clés.

Avant de commencer

Une clé publiable (kld_pk_live_…) obtenue sur kaleidr.com/api-keys. Voir Obtenir une clé API.
L’origine de la page de test, par exemple http://localhost:3000, doit figurer parmi les origines autorisées de la clé. Une clé sans restriction d’origine fonctionne sur tous les sites.
Un serveur HTTP pour servir la page, par exemple npx serve .. Une page ouverte depuis le disque n’a pas d’origine utilisable ; une clé soumise à des restrictions la refusera.
Si votre site applique une Content Security Policy, autorisez https://cdn.kaleidr.com dans script-src, https://api.kaleidr.com dans connect-src et https://map-embed.kaleidr.com dans frame-src. Voir Content Security Policy.

Étape 1 : ajouter la carte

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Résultat attendu : un indicateur « Loading map… », puis un fond de carte clair. Dans l’onglet Réseau, une requête POST vers https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions renvoie 200, suivie d’une requête de document vers https://map-embed.kaleidr.com/. L’URL de l’iframe contient l’identifiant du style, mais aucun secret : la clé n’est envoyée que dans la demande de session et le jeton de session ne figure pas dans l’URL.

L’élément doit avoir une hauteur, faute de quoi la carte utilise une hauteur fixe de 500 pixels. <kaleidr-map> est en display:block par défaut, donc la hauteur s’applique. Conservez cette déclaration dans le style : elle est sans conséquence et assure la compatibilité avec Safari avant 16.4, où l’élément reste inline et ignore height. (display:block)

Étape 2 : choisir un style

Définissez style-id avec l’un des styles généraux :

`style-id`	Aspect
`kaleidr-morning`	Clair : fond blanc, eau cyan, routes blanches.
`kaleidr-afternoon`	Sol de ton moyen, végétation verte et routes grises.
`kaleidr-evening`	Lumière dorée, tons sable chauds et olive.
`kaleidr-night`	Bleu marine et anthracite sombres, autoroutes ambrées.
`kaleidr-plain`	Toile blanche avec frontières et noms des lieux. Les bâtiments 3D apparaissent dès le zoom 15.
`kaleidr-editorial`	Palette de l’après-midi sans étiquettes, pour cartes petites ou décoratives.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

Résultat attendu : la même zone dans une palette sombre.

Indiquez toujours style-id. Sans lui, l’intégration utilise le fond de carte par défaut de votre organisation s’il existe ; sinon l’iframe affiche « Couldn't find a map id in the URL. ».

Les identifiants de style doivent être exacts. Il n’existe aucun alias abrégé : night ne remplace pas kaleidr-night.

Étape 3 : régler la caméra

Sans caméra, la carte s’ouvre sur la vue par défaut du style, souvent le monde entier. Fournissez center (longitude, puis latitude) et zoom pour cadrer votre région. pitch incline la vue et bearing la fait pivoter.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

Résultat attendu : le centre de Londres incliné et tourné.

zoom est ignoré sans center. pitch et bearing peuvent être utilisés seuls.

Étape 4 : déplacer la caméra et changer le style par code

L’élément est la forme déclarative. Pour le contrôler depuis JavaScript, montez la carte avec Kaleidr.mount et conservez l’objet de contrôle qu’il renvoie.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

Résultat attendu : chaque bouton modifie la carte sur place. L’iframe ne se recharge pas et aucune nouvelle demande de session n’apparaît dans l’onglet Réseau.

À retenir :

setCamera et setStyle appartiennent à l’objet de contrôle, pas à l’élément.
setStyle n’existe que sur Tile. Sur les autres produits, il affiche un avertissement et ne fait rien.
Vous pouvez appeler les méthodes de l’objet de contrôle dès que Kaleidr.mount a renvoyé sa valeur. Les appels effectués avant que la carte dans l’iframe soit prête sont conservés et appliqués dans l’ordre à la réception du signal de disponibilité. Il n’est donc pas nécessaire d’attendre kaleidr-embed:ready (étape 6). Pour la caméra et le style initiaux, utilisez les options de montage.
Sur un élément monté, modifier center, zoom, pitch ou bearing déplace la carte. Modifier style-id n’a aucun effet.

Étape 5 : associer un panneau de chat à la carte (facultatif)

Un panneau Kaleidr Chat peut piloter une carte Tile : il affiche sous forme de marqueurs les lieux de ses réponses et ajuste le cadrage. Placez l’élément Tile dans un conteneur positionné, superposez un élément de chat et pointez son attribut map-target vers l’élément Tile.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

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

Résultat attendu : le panneau de chat est fixé en haut à gauche de la carte. Demandez « coffee near Covent Garden » : des marqueurs apparaissent sur la carte Tile.

Rôle des attributs et styles de l’élément de chat :

Élément	Rôle
`map-target="#basemap"`	Sélecteur CSS de l’élément Tile que le chat doit piloter.
`contained`	Ancre le panneau dans l’élément de chat ; sans lui, le panneau reste fixé dans l’angle supérieur gauche de la fenêtre.
`position:absolute; inset:0`	Étend l’élément de chat par-dessus la carte pour fixer le panneau dans l’angle de la carte.
`z-index:1`	Place la couche de chat au-dessus de la carte.
`pointer-events:none`	Permet de faire glisser et zoomer la carte partout sauf sur le panneau ; le panneau reste cliquable.

Remarques :

Une même clé convient aux deux éléments, car les nouvelles clés possèdent par défaut les portées maps et ai. Le chat effectue sa propre demande de session et chaque question consomme des crédits IA.
L’ordre des deux éléments n’a pas d’importance : le chat recherche sa carte au moment utile.

Les options de mise en page et de thème sont décrites dans Thèmes et disposition. Les Capacités et limites indiquent ce que l’assistant peut ou ne peut pas faire.

Étape 6 : savoir quand la carte est chargée (facultatif)

Le SDK ne possède pas de promesse ready et l’élément n’émet pas d’événement. L’iframe envoie un message à votre page quand la carte s’est affichée, et un autre si une partie n’a pas pu s’afficher :

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

Si la demande de session échoue, aucun message n’arrive, car aucune iframe n’a été créée. L’erreur apparaît dans la console. Voir En cas de problème.

Page complète

Enregistrez ce fichier sous index.html, ajoutez votre clé et servez le dossier par HTTP depuis une origine autorisée par la clé.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

Fonctionnement

Sujet	Comportement
Session	Le SDK échange votre clé contre une session Tile temporaire avant de créer l’iframe, puis la renouvelle tant que la carte reste montée. Cet échange vérifie la clé et compte un chargement de carte. La session n’est pas transmise à l’iframe : son URL ne contient que le style et la caméra.
Vue initiale	Caméra fournie, sinon vue par défaut du style.
Défilement	Faire défiler avec le pointeur sur la carte zoome la carte. Avec le pointeur hors de la carte, le défilement fait défiler la page. Sur écran tactile, faire glisser le doigt déplace la carte et pincer la zoome.
Hauteur	Suit la hauteur du conteneur au montage, ou 500 pixels fixes s’il n’en a pas.
Chargement	L’iframe se charge à la demande à l’approche de la zone visible.
Suppression	`handle.destroy()` supprime l’iframe et arrête les renouvellements de session ; retirer un élément `<kaleidr-map>` fait la même chose.
Réinsertion	Réinsérer ou déplacer vers un autre parent un élément retiré entraîne un nouveau montage et une nouvelle session.

Comptage des chargements de carte

Un chargement de carte est compté chaque fois que le SDK obtient une session Tile :

Événement	Chargements de carte
La carte est montée	1
La session est renouvelée tant que la carte reste montée	1 par renouvellement
Le montage est détruit et recréé ou l’élément réinséré	1
`setCamera`, `setStyle`, déplacement ou zoom	0

Par défaut, les sessions durent 15 minutes. Le SDK les renouvelle 90 secondes avant leur expiration, au premier plan comme en arrière-plan. Une visite de quelques minutes représente un seul chargement ; une page ouverte une heure en utilise environ cinq.

Pour réduire l’utilisation :

Détruisez le montage quand la carte est définitivement masquée : fermeture d’une boîte de dialogue, changement de route ou suppression d’un panneau d’onglets.
Ne recréez pas l’élément à chaque rendu. Voir Intégration aux frameworks pour React, Vue et autres.
Utilisez setStyle plutôt qu’un nouveau montage pour modifier le style.

Une fois le quota de chargements épuisé pour la période, toute nouvelle session est refusée avec HTTP 429 et le corps {"detail":"map_load_quota_exceeded"}. Les cartes déjà visibles le restent ; un nouveau montage n’affiche rien. Voir Quotas et limitations de débit.

Vérifier le fonctionnement

Sur la page : la carte est interactive et la mention des crédits cartographiques apparaît en bas.
Dans la console : aucune ligne contenant [kaleidr.
Dans l’onglet Réseau : kaleidr.js et tile.js chargés depuis https://cdn.kaleidr.com ; un POST …/sdk/sessions avec statut 200 et corps JSON contenant session_token et expires_in ; une requête de document vers https://map-embed.kaleidr.com/?style=….
Dans l’écouteur : un message kaleidr-embed:ready dont source vaut "tile".

En cas de problème

Le SDK consigne les échecs de montage dans la console sous [kaleidr:tile] …. Si une session est refusée, seul le statut HTTP est affiché. Le motif figure dans la réponse à la requête sessions de l’onglet Réseau. Un 403 place son code dans detail, tout comme map_load_quota_exceeded ; un 429 rate_limited place son code dans error.

Symptôme	Cause	Solution
Rien ne s’affiche, la console signale une erreur CORS pour `…/sdk/sessions` et `[kaleidr:tile]`	Clé inconnue ou révoquée, ou origine non autorisée. La réponse de refus ne comporte pas d’en-têtes CORS.	Vérifiez la clé et ajoutez l’origine exacte (schéma, hôte, port) sur kaleidr.com/api-keys. Attendez quelques minutes avant de recharger. La requête affiche 401 ou 403 dans Réseau.
`[kaleidr:tile] kaleidr session exchange failed (403)`	La clé ne contient pas la portée `maps` (`insufficient_scope`), est réservée à d’autres produits (`product_not_allowed`) ou l’offre n’autorise pas la demande (`tier_capability_not_allowed`).	Consultez `detail` dans Réseau et créez une clé avec les portées par défaut.
`[kaleidr:tile] kaleidr session exchange failed (429)`	Quota de chargements épuisé (`map_load_quota_exceeded`) ou trop de demandes (`rate_limited`).	Consultez `detail` dans le premier cas, `error` dans le second, puis Quotas et limitations de débit.
La requête `sessions` renvoie 404	Une surcharge de `api-base` omet `/inference-api`.	Supprimez la surcharge ou utilisez `https://api.kaleidr.com/inference-api`.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Une clé serveur a été fournie ; le SDK la refuse avant tout appel.	Utilisez une clé publiable. Révoquez ou remplacez la clé serveur si elle a déjà été publique.
`[kaleidr:tile] Kaleidr tile: invalid style "…"…`	`style-id` contient un caractère interdit, par exemple un espace ou `?`.	Utilisez un identifiant de l’étape 2.
L’iframe affiche « Couldn't find a map id in the URL. » et l’écouteur reçoit `code: 'no_id'` et `id: null`	Aucun `style-id` et aucun fond de carte par défaut pour l’organisation.	Définissez `style-id`.
L’iframe est vide et l’écouteur reçoit `kaleidr-embed:error` avec `maplibre_error`	Le style n’existe pas, souvent à cause d’une faute dans son identifiant.	Choisissez un style de l’étape 2.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	L’attribut `product` manque ou est mal orthographié.	Utilisez `product="tile"`.
La carte conserve une hauteur de 500 pixels	L’élément n’avait pas de hauteur au montage, utilise `display:inline`, ou Safari avant 16.4 n’a pas `display:block`.	Attribuez-lui `display:block` et une hauteur. `height`
Un cadre vide et une violation CSP dans la console	La politique bloque le chargeur, la demande de session ou l’iframe.	Autorisez les trois hôtes indiqués dans Avant de commencer.
`setStyle` ou `setCamera` ne fonctionne pas	Appel sur l’élément, ou carte encore en cours de chargement.	Appelez la méthode sur l’objet de contrôle renvoyé par `Kaleidr.mount`, vérifiez `kaleidr-embed:error` et la console. Un appel précoce sera appliqué quand la carte sera prête. Si la carte n’a pas signalé son chargement au terme d’une attente limitée, normalement 10 secondes après le chargement de l’iframe, l’appel est néanmoins envoyé et la console indique `[kaleidr] the map frame has not reported ready` : une iframe en erreur n’a pas de carte à déplacer ou modifier.
Modifier `style-id` sur l’élément ne change rien	C’est normal : le style n’est lu qu’au montage.	Utilisez `handle.setStyle` ou insérez un nouvel élément. `style-id`

Limites

Votre page ne peut ajouter ni marqueurs, ni couches, ni popups sur une carte Tile, et ne reçoit aucun événement de clic ou de caméra. Un panneau de chat associé peut toutefois y positionner des lieux.
Aucune méthode n’expose l’état de la caméra.
Tile est le produit prévu pour afficher un fond de carte Kaleidr.
Une carte Tile ne s’affiche pas si son origine n’est pas autorisée par la clé.

Étapes suivantes

Référence Tile : toutes les options, attributs et messages.
Intégration aux frameworks : montage et destruction dans React, Next.js et Vue sans chargements supplémentaires.
Chat : ajouter l’assistant à la carte.
Quotas et limitations de débit : quotas de chargement de carte.

Avant de commencer​

Étape 1 : ajouter la carte​

Étape 2 : choisir un style​

Étape 3 : régler la caméra​

Étape 4 : déplacer la caméra et changer le style par code​

Étape 5 : associer un panneau de chat à la carte (facultatif)​

Étape 6 : savoir quand la carte est chargée (facultatif)​

Page complète​

Fonctionnement​

Comptage des chargements de carte​

Vérifier le fonctionnement​

En cas de problème​

Limites​

Étapes suivantes​