kaleidr.js — le chargeur

Une seule balise script installe window.Kaleidr et définit l’élément <kaleidr-map> :

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

La façade est un chargeur léger. Elle ne gère que : version, configuration, chargement des scripts, registre des produits, transmission des clés, choix du mode d’intégration, cycle de vie du montage, normalisation des erreurs et indicateur de dormancy. Le comportement réel de chaque produit se trouve dans son propre bundle, chargé à la demande par URL lors de la première utilisation.

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

Renvoie un handle de manière synchrone pendant que le bundle du produit se charge en arrière-plan ; les appels effectués avant le chargement sont mis en file d’attente puis exécutés une fois prêt.

Options

Option	Type	Notes
product	'chat' | 'viewer' | 'editor' | 'tile'	Obligatoire. Sélectionne le bundle + le mode d’intégration par défaut.
publishableKey	string	Clé navigateur publishable (kld_pk_live_…). Obligatoire pour chat/editor/tile ; viewer ne doit pas recevoir de clé et la rejette avec product_not_allowed. Le SDK échange la clé contre une session de courte durée liée à l’origine à l’exécution.
apiKey	string	Alias obsolète de publishableKey. Accepte également une ancienne clé kld_live_….
shareId / mapId	string	Viewer uniquement. Obligatoire — son absence déclenche une erreur au chargement du bundle.
styleId	string	Tile/editor. Tile : un ID de style de fond de carte Kaleidr (par défaut, le canevas par défaut de viewer). Editor : un ID de style ou une URL complète de style — s’il est omis, le réglage par défaut enregistré de l’organisation s’applique, puis kaleidr-morning.
map	map instance	Chat : votre carte Mapbox / MapLibre / Google active dans la page à laquelle se connecter.
mapTarget	string	Chat : sélecteur CSS d’un élément de carte hôte (chemin déclaratif).
contained	boolean	Chat uniquement. Valeur par défaut false. Ancre le panneau dans l’élément de montage au lieu de le laisser flotter sur document.body — sans cela, le panneau sort de votre mise en page et semble cassé.
center zoom		Caméra initiale (viewer, editor, tile).
pitch bearing		Caméra initiale sur viewer, editor et tile.
theme	object or JSON object string	Ensemble de tokens CSS (par ex. { '--kd-accent': '#2da84a' }). Chat accepte également une mise à jour en direct via le handle. Les thèmes nommés sous forme de chaîne ne sont pas pris en charge ; une chaîne simple génère un avertissement et est ignorée.
doorway	'iframe' | 'attach'	Option de secours — remplace le comportement par défaut du produit.
base	string	Remplace l’origine CDN depuis laquelle les bundles sont chargés (dev / self-host).
viewerBase	string	Viewer/tile : l’origine chargée par l’iframe. Distincte de base — l’iframe ne pointe jamais vers le CDN.
tileBase	string	Editor : le CDN de tuiles utilisé pour résoudre les valeurs styleId du catalogue. Valeur par défaut https://tile.kaleidr.com.
apiBase	string	Doit inclure le chemin du service. Valeur par défaut https://api.kaleidr.com/inference-api ; une origine seule comme https://api.kaleidr.com renvoie 404 lors de l’échange de session. S’applique à chat, editor et tile — tout produit qui effectue un échange de session.
enabled	boolean	Remplacement de dormancy par montage.

KaleidrHandle

La forme du handle est un superset — chaque produit n’implémente que les méthodes qu’il peut réellement prendre en charge. Consultez Handle matrix pour savoir quelle méthode fait quoi sur quel produit.

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

L’appel d’une méthode non prise en charge enregistre actuellement un avertissement [kaleidr] puis retourne — le chargeur ne lève pas d’erreur. Ce comportement fait partie du contrat de l’alias majeur v1.

Kaleidr.init()

Met à niveau tout <kaleidr-map> déjà présent dans le DOM. Appelé automatiquement au chargement ; appelez-le après avoir injecté dynamiquement des éléments.

Kaleidr.enable(on = true)

Le SDK est actif par défaut — vous n’avez rien à activer, et le quickstart fonctionne tel qu’il est écrit.

enable() sert d’interrupteur d’arrêt : passer false empêche mount() de charger le moindre bundle, ce qui permet de placer les embeds derrière une bannière de consentement ou de les désactiver sur une page sans supprimer le balisage. Le même interrupteur est disponible via window.__KALEIDR_EMBED_ENABLED__ = false (avant l’exécution du script) ou via l’attribut flag / l’option enabled pour chaque montage.

Kaleidr.version

La chaîne de version du chargeur.

Remplacer la base CDN

Pour le développement local ou l’auto-hébergement, pointez le chargeur vers une autre origine :

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>