Aller au contenu principal

kaleidr.js, le chargeur

kaleidr.js est le script de départ de toute intégration Kaleidr. Il définit la variable globale window.Kaleidr et l'élément personnalisé <kaleidr-map>. Léger, il ne contient ni bibliothèque cartographique ni code de produit. Lors d'un montage, il charge le module du produit depuis le même CDN et lui transmet les options.

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

Il n'existe aucun paquet npm. Le SDK se charge uniquement avec une balise script. Pour React, Next.js, Vue et TypeScript, voir Intégration aux frameworks.

Charger le script​

QuestionRéponse
Où placer la balise ?N'importe où. Les éléments <kaleidr-map> se montent qu'ils précèdent ou suivent la balise.
Quand appeler Kaleidr.mount ?Après l'exécution du script. Avec une balise <script src> ordinaire, tout script suivant peut l'appeler.
Puis-je utiliser async ou defer ?Oui pour les éléments. Pour Kaleidr.mount, attendre l'événement load de la balise, car window.Kaleidr n'existe pas avant.
À quelle fréquence ?Une fois par page.
Puis-je ajouter integrity ?Non. Le fichier est remplacé à la même URL ; une empreinte figée ne correspondrait plus à la prochaine version. Voir Versionnement CDN.
Fonctionne-t-il côté serveur ?Non. Il requiert window et document. Dans une application rendue côté serveur, ne le charger que dans le navigateur.

Charger avec async et monter à l'arrivée du script :

<div id="map" style="height:480px"></div>
<script>
const s = document.createElement('script');
s.src = 'https://cdn.kaleidr.com/embed/v1/kaleidr.js';
s.async = true;
s.onload = () => {
Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });
};
document.head.appendChild(s);
</script>

window.Kaleidr​

MembreDescription
Kaleidr.mount(target, options)Monte un produit dans un élément et renvoie un handle.
Kaleidr.init()Active les éléments <kaleidr-map> déjà dans le document. Rarement nécessaire.
Kaleidr.enable(on)Active ou suspend les montages ultérieurs.
Kaleidr.versionChaîne de version du chargeur.

Kaleidr.mount(target, options)​

const handle = Kaleidr.mount('#chat', {
product: 'chat',
publishableKey: 'kld_pk_live_…',
map: myMap,
contained: true,
});
ParamètreTypeDescription
targetSélecteur CSS ou HTMLElementÉlément cible. Le sélecteur est résolu une seule fois avec document.querySelector.
optionsobjetObligatoire. Voir Options.

Renvoie un handle.

Comportement :

  • Retour immédiat. L'échange de session et le chargement du module se font en arrière-plan. Les appels au handle sont conservés et appliqués dans l'ordre lorsque le produit est prêt. Pour Viewer et Tile, c'est quand la carte de l'iframe signale sa disponibilité ; un setCamera juste après mount prend donc effet.
  • Aucune exception pour un montage échoué. Cible introuvable, module impossible à charger, session refusée ou identifiant invalide produisent une erreur console contenant [kaleidr:<product>]. Le handle est tout de même renvoyé, mais inactif. Seul Kaleidr.mount('#map') sans objet d'options lève un TypeError.
  • Aucun résultat transmis à votre code. Pas de promesse à attendre ni de callback. Voir Savoir si le montage a réussi.
  • Un montage par cible. Détruire le précédent avec handle.destroy() avant de recommencer. Détruire et remonter dans le même élément est sûr, même si le premier charge encore : celui-ci ne modifie pas le second.

Options​

OptionTypeValeur par défautProduitsDescription
product'chat' | 'viewer' | 'editor' | 'tile'aucune, obligatoiretousProduit à monter.
publishableKeychaîneaucunechat, editor, tileClé publiable kld_pk_…. Le SDK l'échange contre une session courte et ne fournit que celle-ci au produit. Ne pas la transmettre au Viewer. Une clé serveur (kld_sk_…) est refusée avant toute requête.
shareIdchaîneaucuneviewer, chatViewer : ID de carte publiée. Chat sans clé : carte publiée dont le propriétaire fournit les réponses.
mapIdchaîneaucuneviewerAlias de shareId en l'absence de shareId.
styleIdchaînefond de carte par défaut de l'organisationtile, editorID de style tel que kaleidr-morning, ou URL complète de style.
mapinstance de carte activeaucunechatCarte que l'assistant pilote : Mapbox GL JS, MapLibre GL JS, Google Maps ou Leaflet. Voir Cartes compatibles. Omettre pour un chat seul.
mapTargetsélecteur CSSaucunchatÉlément Viewer ou Tile <kaleidr-map> à piloter au lieu de map.
containedbooléenfalsechatAncre le panneau dans la cible, qui doit être positionnée et dimensionnée. Sinon, fenêtre fixe en haut à gauche.
langchaîne<html lang> valide de la page, sinon anglaischatLangue des réponses, étiquette BCP 47 comme en, ko ou pt-BR. Voir Langue du Chat.
titlechaînetitre propre du panneauchatTitre de l'en-tête ; sur l'élément, l'attribut est chat-title.
placeholderchaînetexte indicatif du panneauchatTexte indicatif du champ de saisie.
center[longitude, latitude]valeur du produitviewer, tile, editorCentre initial.
zoomnombrevaleur du produitviewer, tile, editorZoom initial ; sur Viewer et Tile, seulement avec center.
pitchnombrevaleur du produitviewer, tile, editorInclinaison initiale en degrés.
bearingnombrevaleur du produitviewer, tile, editorOrientation initiale en degrés.
themeobjet ou chaîne JSON d'objetaucunechat, editorChat : propriétés CSS personnalisées, par exemple { '--highlight-color': '#0b5fff' }. Editor : 17 clés de thème. Une chaîne non JSON est ignorée avec avertissement.
enabledbooléenaucunetousCommande par montage du mécanisme d'activation, lue au montage seulement.
baseURLhttps://cdn.kaleidr.comtousOrigine des modules. Seule l'origine compte ; les modules sont demandés dans /embed/v1/. Seules les origines de Surcharge de base sont acceptées ; les autres provoquent un avertissement.
viewerBaseURLhttps://map-embed.kaleidr.comviewer, tileOrigine de l'iframe ; seule l'origine est retenue.
apiBaseURLhttps://api.kaleidr.com/inference-apichat, editor, tileDestination de l'échange de session et des requêtes. Doit contenir /inference-api ; une origine seule renvoie 404.
tileBaseURLhttps://tile.kaleidr.comeditorHôte de résolution des IDs de style.

Remarques :

  • apiKey est un ancien alias de publishableKey.
  • Les quatre options …Base servent à tester un autre déploiement et sont inutiles en production. base ne déplace que les modules : la page cartographique, l'API et le serveur de fond de carte restent chez Kaleidr sans surcharge spécifique.
  • lang, title et placeholder sont lus au montage. Pour les changer, détruire puis remonter.
  • Toute option inutilisée par un produit est ignorée sans message.

Surcharge de base​

base (option ou attribut) et la variable de page window.__KALEIDR_EMBED_BASE__ désignent l'origine des modules. La surcharge est acceptée uniquement lorsque l'origine est l'une des suivantes :

Origine admiseExemple
CDN Kaleidrhttps://cdn.kaleidr.com
Origine d'où kaleidr.js a été chargékaleidr.js est servi par https://static.example.com, et base vaut https://static.example.com.
Origine de la pagePage à https://www.example.com/…, avec base égal à https://www.example.com.

Toute autre valeur est ignorée. Le montage a lieu, les modules viennent du CDN par défaut et la console affiche un avertissement :

[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.

La variable globale doit être une chaîne ; toute autre valeur est ignorée silencieusement. L'auto-hébergement respecte cette règle lorsque chargeur et modules proviennent de la même origine.

Valeurs de caméra par défaut selon le produit :

ProduitCaméra par défaut
viewerVue enregistrée par l'auteur de la carte.
tileVue par défaut du style, sinon le monde entier.
editorCentre [0, 0], zoom 2, inclinaison 0, orientation 0.
chatSans objet : le chat ne crée pas de carte.

Chaque produit a ses détails : Chat, Viewer, Tile, Editor.

Le handle​

Kaleidr.mount renvoie la même structure pour tous les produits.

interface KaleidrHandle {
readonly product: 'chat' | 'viewer' | 'editor' | 'tile';
setCamera(camera: {
center?: [number, number]; // [longitude, latitude]
zoom?: number;
pitch?: number;
bearing?: number;
duration?: number; // milliseconds
}): void;
setTheme(theme: string | Record<string, string>): void;
setStyle(style: string): void;
destroy(): void;
}

Toutes les méthodes existent sur tous les handles. Leur effet dépend du produit :

Méthodechatviewereditortile
setCamera(camera)avertitouiouioui
setTheme(theme)ouiavertitavertitavertit
setStyle(style)avertitavertitavertitoui
destroy()ouiouiouioui

« Avertit » signifie que l'appel ne fait rien et affiche un message console.

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

Cela fait partie du contrat /embed/v1 : une méthode non prise en charge ne lève jamais d'exception.

Précisions sur les méthodes :

  • setCamera : les champs omis conservent leur valeur. duration anime le déplacement ; absent ou égal à 0, la carte saute immédiatement. Sur Chat, setCamera n'est pas pris en charge puisque le panneau ne possède pas la carte. L'assistant déplace néanmoins la carte quand il répond ; utilisez l'API de votre bibliothèque pour la déplacer vous-même.
  • setTheme : uniquement Chat. Reçoit des propriétés CSS personnalisées en objet ou chaîne JSON.
  • setStyle : uniquement Tile. Reçoit un ID ou une URL de style.
  • destroy : supprime le montage, arrête les renouvellements de session et oublie les appels en attente. Appels répétés sans risque. Un handle détruit ne se réutilise pas : remonter.

Le handle s'utilise immédiatement après mount. Sur Viewer et Tile, les appels précoces à setCamera (et setStyle sur Tile) sont gardés dans l'ordre jusqu'à ce que la carte dans l'iframe signale sa disponibilité, par kaleidr-embed:ready ou sa première position de caméra. Les 256 derniers appels sont conservés. Si la carte n'est toujours pas prête après un délai limité, généralement 10 secondes après chargement de l'iframe, les appels sont envoyés malgré tout et un avertissement s'affiche :

[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. The frame may be showing an error (an unpublished map, a blocked request).

Ce délai commence au chargement de l'iframe. Si elle est hors de la zone visible et n'a pas encore chargé, ses appels restent en attente. Nul besoin d'attendre kaleidr-embed:ready. Ce message et kaleidr-embed:error signalent toujours la réussite ou l'échec ; voir Messages Viewer.

Le handle n'a ni promesse ready, ni méthode on(), ni propriété map ou iframe.

Kaleidr.init()​

Initialise les éléments <kaleidr-map> présents dans le document au moment de l'appel. Le chargeur le fait automatiquement, et les éléments insérés après se montent seuls. Rarement utile ; plusieurs appels sont sans danger.

Mécanisme d'activation​

Les intégrations sont actives par défaut. Lorsque le mécanisme bloque un montage, Kaleidr.mount ne charge ni n'envoie rien et retourne un handle inerte. Il permet d'attendre le consentement d'un visiteur ou de suspendre les intégrations sans supprimer le HTML.

Les trois leviers​

LevierPortéeRéglage
Indicateur de pageTous les montages sur la pagewindow.__KALEIDR_EMBED_ENABLED__ = false, avant les montages à suspendre
Kaleidr.enable()Tous les montages suivant son appelKaleidr.enable(false)
Par montageUn montageOption enabled: false ou attribut flag="false"

Décision au montage​

À chaque montage, le SDK examine les trois leviers :

  1. Si un seul est explicitement false, le montage est retenu.
  2. Sinon, si au moins un est explicitement true, il démarre.
  3. Sinon, la valeur par défaut est active.

Trois conséquences importantes :

  • Un false ne se libère qu'avec le levier qui l'a défini. Kaleidr.enable(true) ne lève ni enabled: false ni un indicateur de page à false. Aucun levier n'en remplace un autre.
  • La vérification n'a lieu qu'au montage. Libérer un levier ne redémarre pas ce qui était retenu ; le désactiver ne supprime pas ce qui tourne déjà. Après libération, appeler de nouveau Kaleidr.mount, ou retirer puis réinsérer l'élément.
  • L'indicateur de page est relu à chaque montage, pas seulement au chargement du script. Une modification ultérieure agit sur le prochain montage.
Blocage initialPour libérer
window.__KALEIDR_EMBED_ENABLED__ = falseLui attribuer true, ou le supprimer.
Kaleidr.enable(false)Appeler Kaleidr.enable(true) ou Kaleidr.enable(null) pour rétablir le défaut.
enabled: false ou flag="false"Remonter sans ce réglage. Changer l'attribut flag d'un élément déjà monté ne fait rien.

Lorsqu'un montage est bloqué, un avertissement console indique quel levier en est responsable :

[kaleidr] embed is disabled — window.__KALEIDR_EMBED_ENABLED__ is false. Reassigning it releases that lever — Kaleidr.enable() cannot.

Valeurs acceptées​

Les leviers interprètent strictement les booléens pour empêcher qu'une chaîne inattendue active les intégrations par erreur.

LevierInterprété comme trueInterprété comme falseIgnoré avec avertissement
window.__KALEIDR_EMBED_ENABLED__truefalseToute valeur non booléenne, y compris les chaînes "true" et "false"
Kaleidr.enable(x)sans argument, true, "true", "1", "yes", "on"false, 0, "", "false", "0", "no", "off"Autres chaînes, undefined, objets, fonctions
Option enabledtrue, "true", "1", "yes", "on"false, 0, "", "false", "0", "no", "off"Autres chaînes, objets, fonctions
Attribut flagflag sans valeur, "true", "1", "yes", "on""false", "0", "no", "off"Toute autre valeur

Casse et espaces extérieurs sont ignorés. Deux points comptent pour des valeurs stockées :

  • Kaleidr.enable(null) réinitialise le levier à sa valeur par défaut ; ce n'est pas « sans avis ». localStorage.getItem(key) renvoie null lorsqu'aucune valeur n'a été enregistrée, précisément avant le consentement. Ne passez jamais directement une valeur stockée : comparez d'abord, avec Kaleidr.enable(stored === 'true').
  • Une valeur ignorée laisse le levier dans son état précédent ; elle n'active ni ne désactive.

Exemple : attendre le consentement avant de monter​

Cette page retient chaque intégration avec l'indicateur de page, efficace pour les éléments qui se montent dès l'exécution du chargeur. Au consentement, elle libère ce même indicateur et réinsère les éléments pour les monter.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Consent-gated map</title>
<script>
// A real boolean, set before the loader. A stored string is compared, never passed through.
window.__KALEIDR_EMBED_ENABLED__ =
localStorage.getItem('embeds-consent') === 'true';
</script>
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
</head>
<body>
<div id="banner">
This page shows an interactive map from Kaleidr.
<button id="accept">Show the map</button>
</div>

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

<script>
const banner = document.getElementById('banner');
if (window.__KALEIDR_EMBED_ENABLED__) banner.hidden = true;

document.getElementById('accept').addEventListener('click', () => {
localStorage.setItem('embeds-consent', 'true');
banner.hidden = true;

// 1. Release the lever that held the embeds.
window.__KALEIDR_EMBED_ENABLED__ = true;

// 2. A held element does not mount by itself. Re-insert each one.
document.querySelectorAll('kaleidr-map').forEach((el) => {
const parent = el.parentNode;
const next = el.nextSibling;
el.remove();
parent.insertBefore(el, next);
});
});
</script>
</body>
</html>

Avant le consentement, l'onglet Réseau montre kaleidr.js et rien d'autre de Kaleidr : pas de module produit, d'échange de session ni d'iframe.

Si vous montez via JavaScript, nul besoin du mécanisme : attendez le consentement avant d'appeler Kaleidr.mount. Il est surtout utile si les intégrations sont des éléments HTML, ou si un gestionnaire de balises ou une autre équipe appelle mount et qu'un interrupteur global est souhaité :

Kaleidr.enable(false); // hold every later mount
// …
Kaleidr.enable(true); // release it
const handle = Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });

Variables globales de page​

GlobaleTypeLectureRôle
window.__KALEIDR_EMBED_ENABLED__booléenÀ chaque montageIndicateur de page du mécanisme d'activation.
window.__KALEIDR_EMBED_BASE__chaîne URLÀ chaque montageOrigine des modules auto-hébergés ; seule l'origine est utilisée et doit satisfaire la surcharge de base. Voir Versionnement CDN.

Savoir si le montage a réussi​

Le SDK ne fournit pas de signal de disponibilité ou d'échec à votre code. On peut observer :

ProduitChargéÉchec
viewerL'iframe émet kaleidr-embed:ready.L'iframe émet kaleidr-embed:error ou la console affiche une erreur [kaleidr:viewer].
tileL'iframe émet kaleidr-embed:ready.Session refusée : console seulement. Problème de rendu : kaleidr-embed:error.
chatPas de signal ; le panneau apparaît dans la page.Console seulement.
editorPas de signal ; l'éditeur apparaît dans la page.Console seulement.

Ces messages figurent dans Messages Viewer.

Lorsqu'un montage échoue​

CauseCe qui s'afficheRequête envoyée ?
Le sélecteur ne trouve rien[kaleidr:<product>] mount target not found: <selector>Non
L'élément n'a pas de product valide[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"Non
Clé serveur fournie[kaleidr:<product>] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.Non
Clé inconnue/révoquée, ou origine interditeErreur CORS du navigateur sur sessions, puis erreur de récupération [kaleidr:<product>]. Aucun rendu.Oui
Portée insuffisante, restriction produit ou forfait incompatible[kaleidr:<product>] kaleidr session exchange failed (403). Aucun rendu.Oui
Quota de chargements de cartes épuisé (tile) ou trop de sessions[kaleidr:<product>] kaleidr session exchange failed (429). Aucun rendu.Oui
Impossible de charger le module[kaleidr:<product>] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/<product>.jss.o.
Viewer sans ID ou avec un ID mal formé[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.Non
Editor sans clé[kaleidr:editor] [editor-embed] attach() requires an { apiKey }Non
Chat sans clé ni shareIdLe panneau apparaît, mais chaque question échoue.Pas au montage
Mécanisme d'activation désactivé[kaleidr] embed is disabled — …Non

Le SDK n'affiche jamais la raison donnée par le serveur. Il ne journalise que le statut HTTP. Le corps de réponse contient le code : pour 403/404 dans detail, par exemple {"detail":"insufficient_scope"} ; pour 429 dans error, avec une phrase dans detail. Exception : map_load_quota_exceeded est dans detail. Ouvrez Réseau, sélectionnez sessions et consultez le corps. Si CORS le masque, reproduisez la requête depuis un terminal :

curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "x-api-key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "content-type: application/json" \
-d '{"product":"chat"}'
HTTP/2 403
content-type: application/json

{"detail":"origin_not_allowed"}

Utilisez exactement l'origine de la page en échec. Pour tester, passez "chat", "editor" ou "viewer" : un échange "tile" réussi compte un chargement de carte. Tous les codes sont expliqués dans Erreurs.

Un premier échange échoué est définitif pour ce montage. Le SDK ne réessaie pas. Corriger la cause et remonter.

Échange de session en bref​

Pour Chat, Editor et Tile, le SDK n'utilise jamais directement votre clé publiable pour l'API d'exécution : il l'échange d'abord contre une session.

  1. Au montage, le SDK envoie POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions avec l'en-tête x-api-key: <your publishable key> et le corps {"product":"<product>"}. Le navigateur ajoute Origin.
  2. Kaleidr vérifie successivement : clé publiable, présence d'une origine, origine autorisée si une liste existe, produit admis par la clé et le forfait, puis portée nécessaire : ai pour Chat, design pour Editor, maps pour Tile, aucune pour Viewer.
  3. Réponse : {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …}. basemap_style_id contient le fond de carte par défaut de l'organisation, ou null.
  4. Le produit emploie le jeton de session, lié à l'origine et au produit, pour ses requêtes.
  5. Le SDK renouvelle la session 90 secondes avant l'expiration et au retour au premier plan d'un onglet avec une session presque expirée. En cas d'échec, il réessaie toutes les 30 secondes tant que le montage existe.
  6. handle.destroy() arrête les renouvellements.

Viewer ne nécessite pas de session. Chat avec shareId sans clé obtient une session à partir de la carte publiée ; voir Chat sur une carte publiée.

Requête et réponse sont détaillées dans Points de terminaison. Les clés, sessions et limites des origines autorisées figurent dans le Modèle de sécurité.

Autres messages console​

MessageSignification
[kaleidr] <method>() is not supported on product "<product>" — the call is a no-op. …Vous avez appelé une méthode de handle non prise en charge.
[kaleidr] <method>() IS supported on product "<product>", but this mount did not expose it, so the call did nothing. …Le module en cache est plus ancien que le chargeur : recharger sans cache.
[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. …L'iframe Viewer/Tile n'a pas signalé sa disponibilité dans le délai du handle : les appels setCamera et setStyle ont quand même été envoyés ; surveiller kaleidr-embed:error.
[kaleidr] theme must be an object of CSS tokens, not an array; ignored.theme était un tableau.
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.theme était une chaîne ne commençant pas par {.
[kaleidr] theme JSON parse failed (…); ignored.JSON theme mal formé.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. …L'attribut flag ou contained avait une valeur invalide. Le message précise flag="…" ou contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from <origin>. …base ou window.__KALEIDR_EMBED_BASE__ visait une origine interdite par la surcharge de base. Le CDN standard est utilisé.
[kaleidr] window.__KALEIDR_EMBED_ENABLED__ must be a boolean; got <type> (…). …Indicateur de page non booléen, ignoré.
[kaleidr] Kaleidr.enable(): "<value>" is not a recognized boolean — the value is IGNORED. …Valeur invalide passée à Kaleidr.enable.
[kaleidr] enabled: "<value>" is not a recognized boolean — the value is IGNORED. …Valeur invalide de l'option enabled.
[kaleidr] Kaleidr.enable(undefined) is IGNORED and leaves the gate exactly as it was. …Kaleidr.enable a reçu undefined.
[kaleidr] Kaleidr.enable(null) RESET the gate to the build default, releasing the <value> set earlier. …Kaleidr.enable(null) a effacé le réglage antérieur.

Non disponible​

  • Aucun paquet npm, module ES ni définitions de types ; déclaration à copier dans Intégration aux frameworks.
  • Aucun SDK natif pour iOS, Android, React Native ou Flutter.
  • Aucun ready sous forme de promesse, ni événements ou callbacks sur le handle.
  • Aucun client JavaScript pour l'API sans montage : utilisez l'API serveur dans votre backend.

Pages connexes​