kaleidr.js — der Loader

Ein einziges Script-Tag installiert window.Kaleidr und definiert das <kaleidr-map>-Element:

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

Die Fassade ist ein schlanker Loader. Sie verwaltet nur Version, Konfiguration, Script-Laden, das Produktregister, Schlüsselweitergabe, Einbindungswahl, Mount-Lebenszyklus, Fehler- normalisierung und das Dormancy-Flag. Das eigentliche Verhalten jedes Produkts liegt in dessen eigenem Bundle, das bei der ersten Nutzung per URL lazy geladen wird.

Kaleidr.mount(target, options) → KaleidrHandle

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

Gibt ein Handle synchron zurück, während das Produkt-Bundle im Hintergrund lädt; Aufrufe vor dem Laden werden in eine Warteschlange gestellt und bei Bereitschaft ausgeführt.

Optionen

Option	Typ	Hinweise
product	'chat' | 'viewer' | 'editor' | 'tile'	Erforderlich. Wählt das Bundle + die Standard-Einbindung.
publishableKey	string	Publishable Browser-Schlüssel (kld_pk_live_…). Erforderlich für chat/editor/tile; viewer darf keinen Schlüssel erhalten und lehnt ihn mit product_not_allowed ab. Das SDK tauscht den Schlüssel zur Laufzeit gegen eine kurzlebige, origin-gebundene Session aus.
apiKey	string	Veralteter Alias für publishableKey. Akzeptiert auch einen älteren kld_live_…-Schlüssel.
shareId / mapId	string	Nur Viewer. Erforderlich — fehlt der Wert, wird beim Bundle-Laden ein Fehler ausgelöst.
styleId	string	Tile/editor. Tile: eine Kaleidr-Basemap-Style-ID (standardmäßig der Canvas-Standard des Viewers). Editor: eine Style-ID oder vollständige Style-URL — fehlt sie, gilt zuerst der gespeicherte Org-Standard, dann kaleidr-morning.
map	map instance	Chat: deine aktive Mapbox-/MapLibre-/Google-Karte in der Seite, an die angehängt wird.
mapTarget	string	Chat: CSS-Selektor eines Host-Kartenelements (deklarativer Pfad).
contained	boolean	Nur Chat. Standard false. Dockt das Panel im Mount-Element an, statt es auf document.body schweben zu lassen — ohne diese Option verlässt das Panel dein Layout und wirkt fehlerhaft.
center zoom		Initiale Kamera (viewer, editor, tile).
pitch bearing		Initiale Kamera für viewer, editor und tile.
theme	object or JSON object string	CSS-Token-Sammlung (z. B. { '--kd-accent': '#2da84a' }). Chat unterstützt auch Live-Updates über das Handle. Benannte String-Themes werden nicht berücksichtigt; ein einfacher String erzeugt eine Warnung und wird ignoriert.
doorway	'iframe' | 'attach'	Escape-Hatch — überschreibt den Produktstandard.
base	string	Überschreibt den CDN-Origin, von dem Bundles geladen werden (dev / self-host).
viewerBase	string	Viewer/tile: der Origin, den das iframe lädt. Unabhängig von base — das iframe zeigt nie auf das CDN.
tileBase	string	Editor: das Tile-CDN zur Auflösung von Katalog-styleId-Werten. Standard https://tile.kaleidr.com.
apiBase	string	Muss den Servicepfad enthalten. Standard https://api.kaleidr.com/inference-api; ein reiner Origin wie https://api.kaleidr.com liefert beim Session-Austausch 404. Gilt für chat, editor und tile — jedes Produkt, das einen Session-Austausch durchführt.
enabled	boolean	Dormancy-Überschreibung pro Mount.

KaleidrHandle

Die Handle-Form ist ein Superset — jedes Produkt implementiert nur die Methoden, die es tatsächlich unterstützen kann. Siehe Handle matrix, um zu erfahren, welche Methode bei welchem Produkt was tut.

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;
}

Der Aufruf einer nicht unterstützten Methode protokolliert derzeit eine [kaleidr]-Warnung und kehrt zurück — der Loader wirft keinen Fehler. Dieses Verhalten ist Bestandteil des Vertrags des Major-Alias v1.

Kaleidr.init()

Aktualisiert alle bereits im DOM vorhandenen <kaleidr-map>-Elemente. Wird beim Laden automatisch aufgerufen; rufe es nach dem dynamischen Einfügen von Elementen auf.

Kaleidr.enable(on = true)

Das SDK ist standardmäßig aktiv — du musst nichts aktivieren, und der Quickstart funktioniert wie beschrieben.

enable() dient als Ausschalter: Wenn false übergeben wird, verhindert es, dass mount() irgendein Bundle lädt. Dadurch kannst du Embeds hinter einem Consent-Banner sperren oder sie auf einer Seite deaktivieren, ohne das Markup zu entfernen. Derselbe Schalter ist auch als window.__KALEIDR_EMBED_ENABLED__ = false (vor Ausführung des Scripts) oder über das Attribut flag / die Option enabled pro Mount verfügbar.

Kaleidr.version

Der Versionsstring des Loaders.

CDN-Basis überschreiben

Für lokale Entwicklung oder Self-Hosting kannst du den Loader auf einen anderen Origin richten:

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