Intégrer l’éditeur de cartes

À la fin de ce guide, votre page affiche les outils d’édition cartographique de Kaleidr sur un fond de carte Kaleidr, avec les couleurs de votre marque. Cette fonction est disponible sur tous les forfaits, y compris Free. Il vous faut une clé publiable dotée de la portée design, incluse par défaut dans les nouvelles clés.

Les modifications ne sont pas enregistrées

L’éditeur intégré conserve le travail uniquement en mémoire dans la page. Rien n’est enregistré, exporté ou publié depuis l’intégration et votre page ne reçoit aucun rappel lors d’une modification. Recharger la page ou appeler handle.destroy() efface les modifications. Pour conserver des cartes, créez-les dans Kaleidr Studio puis intégrez-les avec Viewer.

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 à tester, par exemple http://localhost:3000, figure dans les origines autorisées de la clé. Une clé sans restriction d’origine fonctionne sur tous les sites.
Un serveur HTTP pour la page, par exemple npx serve ..
Si votre site applique une Content Security Policy, les directives de l’éditeur indiquées dans Content Security Policy. L’éditeur fonctionne dans votre page et a besoin de règles connect-src, img-src, worker-src, font-src et style-src qui ne sont pas nécessaires aux produits iframe.
Aucun autre éditeur Kaleidr sur la même page.

Étape 1 : dimensionner le conteneur et monter l’éditeur

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

Résultat attendu : un fond de carte Kaleidr affichant le monde remplit le conteneur (kaleidr-morning, sauf autre valeur par défaut définie par votre organisation), avec un bouton Create sur la carte. Cliquez sur Create pour afficher la barre latérale de l’éditeur et ses outils Texte, Image, Marqueur et Popup.

Le conteneur doit avoir une hauteur. L’éditeur occupe 100 % de sa largeur et de sa hauteur, et ses panneaux restent à l’intérieur.

Vous pouvez aussi utiliser l’élément. Il est en display:block par défaut, donc la hauteur s’applique. L’exemple précise également display:block pour Safari avant la version 16.4 :

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

Étape 2 : choisir le fond de carte et la vue initiale

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

Résultat attendu : le fond de carte sombre montre le centre de Londres, incliné et pivoté.

Le fond de carte est choisi ainsi :

styleId si vous le fournissez. Utilisez par exemple kaleidr-morning, kaleidr-afternoon, kaleidr-evening, kaleidr-night, kaleidr-plain ou kaleidr-editorial. La référence Tile décrit les styles.
Sinon, le fond de carte par défaut de votre organisation, si elle en a défini un.
Sinon, kaleidr-morning.

La caméra démarre au centre [0, 0], avec zoom 2, inclinaison 0 et orientation 0. Contrairement à Viewer et Tile, l’éditeur accepte zoom sans center.

Une option de caméra transmise à Kaleidr.mount qui n’est pas un nombre fini est ignorée et signalée dans la console. Sur l’élément, un attribut de caméra non numérique est écarté sans message.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

Étape 3 : personnaliser les panneaux (facultatif)

Transmettez theme pour harmoniser les panneaux de l’éditeur avec votre produit. Cet objet accepte jusqu’à 17 clés nommées; les autres sont ignorées.

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

Résultat attendu : l’outil actif, les contours de focus et les boutons principaux utilisent votre couleur de marque, et les panneaux votre police.

Les 17 clés figurent dans la référence de l’éditeur.

Trois points à retenir :

Les valeurs sont des valeurs CSS. brandColor accepte une couleur CSS, cardRadius une longueur CSS et fontPrimary une valeur font-family. Chargez vous-même la police.
Le thème est appliqué à tout le document pendant que l’éditeur est monté, puis restauré au démontage. Il ne modifie vos propres styles que si ceux-ci utilisent les mêmes propriétés personnalisées.
Le thème est lu uniquement au montage. L’éditeur ne prend pas en charge handle.setTheme. Pour modifier le thème, démontez puis remontez l’éditeur : les modifications seront perdues.

Sur l’élément, theme est une chaîne JSON :

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

Étape 4 : déplacer la caméra depuis votre page (facultatif)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

Résultat attendu : la carte se déplace en animation vers Paris. Les éléments placés sur la carte restent à leur emplacement.

setCamera est le seul moyen dont dispose votre page pour agir sur la carte de l’éditeur. Le handle n’expose pas l’objet carte.

Étape 5 : démonter

handle.destroy();

destroy() retire l’éditeur, sa carte et ses panneaux du conteneur, et rétablit les valeurs du thème. Les modifications sont perdues.

Dans une application monopage, appelez destroy() lorsque la route ou le composant contenant l’éditeur disparaît. Pour l’élément, le retirer du document a le même effet. Voir Intégration aux frameworks.

Un seul éditeur pouvant exister par page, démontez toujours l’éditeur en cours avant d’en monter un autre.

Page complète

Enregistrez le fichier sous index.html, renseignez votre clé et servez le dossier en HTTP depuis une origine autorisée.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

Comportement

Sujet	Comportement
Exécution	Dans votre document. Le canevas de la carte et les panneaux de l’éditeur sont des éléments du conteneur cible.
Session	Le SDK échange votre clé contre une session courte avant de lancer l’éditeur et la renouvelle tant que celui-ci est monté.
Modifications	En mémoire uniquement : ni enregistrement, ni exportation, ni publication, ni notification à votre page.
Fond de carte	Chargé par la page depuis `https://tile.kaleidr.com`, fixé au montage.
Thème	Appliqué à tout le document au montage, restauré à la destruction.
Caméra	Définie au montage, déplacée par `handle.setCamera`.
Utilisation	La demande de session de l’éditeur ne compte pas comme chargement de carte; l’éditeur intégré ne comporte aucune fonction IA consommant des crédits. Les requêtes de fond de carte utilisant votre clé comptent comme chargements de carte groupés : un chargement pour 20 requêtes en une heure. Voir Chargements de carte.
Signaux	Aucun : ni événement prêt, ni modification, ni rappel d’erreur.

Prévenir vos utilisateurs

L’éditeur n’avertit pas lui-même que le travail est temporaire. Si vos utilisateurs y passent du temps, indiquez-le dans votre interface, comme dans la page complète ci-dessus, pour qu’ils ne s’attendent pas à retrouver leurs cartes ultérieurement.

Vérifier que tout fonctionne

Dans la page : le fond de carte remplit le conteneur; Create ouvre la barre latérale et permet d’ajouter du texte ou un marqueur.
Dans la console : aucune ligne contenant [kaleidr.
Dans l’onglet Réseau : kaleidr.js et editor.js chargés depuis https://cdn.kaleidr.com, un POST …/sdk/sessions de statut 200 et des requêtes vers https://tile.kaleidr.com pour le style et les tuiles.

En cas de problème

Le SDK journalise l’échec d’un montage sous la forme [kaleidr:editor] …. Si une session est refusée, il n’indique que le statut HTTP. Consultez la réponse de la requête sessions dans l’onglet Réseau : un 403 place son code dans detail; un 429 utilise error pour le code et detail pour l’explication.

Symptôme	Cause	Solution
Rien ne s’affiche. Console : `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	Aucune clé fournie.	Fournissez `publishableKey`.
Rien ne s’affiche, erreur CORS sur `…/sdk/sessions` et erreur `[kaleidr:editor]`.	Clé inconnue ou révoquée, ou origine non autorisée.	Vérifiez la clé; ajoutez l’origine exacte (schéma, hôte, port) sur kaleidr.com/api-keys, puis attendez quelques minutes.
Console : `[kaleidr:editor] kaleidr session exchange failed (403)`	Clé sans portée `design` (`insufficient_scope`), limitée à d’autres produits (`product_not_allowed`) ou forfait incompatible (`tier_capability_not_allowed`).	Consultez `detail` et créez une clé avec les portées par défaut.
Console : `[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Clé serveur utilisée.	Utilisez une clé publiable. Renouvelez la clé serveur si la page a été publique.
Conteneur vide sans hauteur.	La cible du montage n’a pas de hauteur.	Définissez-en une; sous Safari antérieur à 16.4, ajoutez `display:block`.
Panneaux visibles mais carte vide; réponses 429 de `https://tile.kaleidr.com` avec `"error":"tile_access_restricted"`.	Le serveur de fond de carte refuse la page.	Vérifiez la clé et l’origine autorisée, attendez quelques minutes après une modification puis rechargez; contactez l’assistance au besoin. `[kaleidr:editor] …`
Panneaux visibles mais carte vide avec violation CSP.	La politique bloque le fond de carte, son worker ou ses images.	Ajoutez les directives de Content Security Policy.
Éditeur sans style.	La politique bloque les styles en ligne.	Autorisez `'unsafe-inline'` dans `style-src`.
Le second éditeur dysfonctionne ou le premier s’arrête.	Deux éditeurs montés simultanément.	Démontez le premier avant le second.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	Le thème n’est lu qu’au montage.	Fournissez `theme` au montage.
`[kaleidr] theme string must be JSON…`	L’attribut `theme` n’est pas un objet JSON.	Utilisez des apostrophes autour de l’attribut et des guillemets doubles dans le JSON.
Une clé de thème est sans effet.	Clé inconnue ou mal orthographiée, ignorée sans message.	Vérifiez la liste.
Les modifications ont disparu.	Page rechargée, éditeur détruit ou élément déplacé ou retiré.	Comportement normal; voir l’avertissement initial.

Limites

Rien n’est enregistré, exporté ou publié depuis l’intégration.
Aucun rappel de modification, signal de disponibilité ou rappel d’erreur.
Aucun accès à l’objet carte : ni couches personnalisées ni lecture des éléments dessinés.
Pas d’onglet Data, de catalogue de designs, de panneau IA, de bibliothèque 3D, de partage ni de projets. La barre d’outils propose Text, Image, Marker, Popup, Background, Layer, Design et Legend : voir Périmètre.
Un seul éditeur par page.
Impossible de modifier le fond de carte ou le thème après le montage.

Étapes suivantes

Référence de l’éditeur : toutes les options et les clés de thème.
Intégration aux frameworks : monter et démonter l’éditeur avec React, Next.js et Vue.
Content Security Policy : directives pour l’éditeur.
Intégrer une carte publiée : pour conserver les cartes.

Avant de commencer​

Étape 1 : dimensionner le conteneur et monter l’éditeur​

Étape 2 : choisir le fond de carte et la vue initiale​

Étape 3 : personnaliser les panneaux (facultatif)​

Étape 4 : déplacer la caméra depuis votre page (facultatif)​

Étape 5 : démonter​

Page complète​

Comportement​

Prévenir vos utilisateurs​

Vérifier que tout fonctionne​

En cas de problème​

Limites​

Étapes suivantes​