CDN-Versionierung

Das SDK wird als fünf Dateien unter einem versionierten Pfad ausgeliefert. Sie binden die erste ein; sie lädt die weiteren, sobald ein Produkt eingebunden wird.

https://cdn.kaleidr.com/embed/v1/kaleidr.js   the loader: window.Kaleidr and <kaleidr-map>
https://cdn.kaleidr.com/embed/v1/chat.js      the chat panel
https://cdn.kaleidr.com/embed/v1/viewer.js    the viewer's iframe loader
https://cdn.kaleidr.com/embed/v1/tile.js      the tile iframe loader
https://cdn.kaleidr.com/embed/v1/editor.js    the editor

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

Ein Produktpaket wird beim ersten Einbinden des Produkts auf einer Seite geladen, höchstens einmal pro Seite. Eine Seite, die nur Viewer zeigt, lädt weder chat.js noch editor.js herunter.

Was `v1` bedeutet

v1 bezeichnet einen Vertrag, keinen bestimmten Build.

Jede URL verweist auf genau eine Datei, die bei einem Release am selben Ort ersetzt wird.
Es gibt keine Patchversionen und keine Inhalts-Hash-Pfade. Sie können /embed/v1.2.3/kaleidr.js nicht festpinnen, weil der Pfad nicht existiert.
Fehlerbehebungen und abwärtskompatible Erweiterungen erscheinen unter /embed/v1/ und erreichen Ihre Seite ohne Änderungen.

Kaleidr.version ist eine Zeichenfolge für Diagnosen, keine Kennung eines abrufbaren Builds.

Was unter `v1` stabil bleibt

Stabil	Bedeutung
Die fünf URLs	Sie bleiben erreichbar.
`window.Kaleidr`	`mount`, `init`, `enable` und `version` behalten ihr dokumentiertes Verhalten.
Mount-Optionen und Elementattribute	Dokumentierte Optionen behalten Namen und Bedeutung.
Das Handle	Jedes Handle bietet `setCamera`, `setTheme`, `setStyle` und `destroy`. Nicht unterstützte Methoden protokollieren eine Warnung und bewirken nichts; sie werfen keine Ausnahme und werden nicht entfernt.
Die zwei iframe-Nachrichten	`kaleidr-embed:ready` und `kaleidr-embed:error` behalten ihre dokumentierten Felder.

Was sich innerhalb von v1 ändern darf:

Erweiterungen. Neue Optionen, Attribute, Handle-Methoden, Nachrichtenfelder, Fehlercodes und Stream-Ereignisse können hinzukommen. Programmieren Sie so, dass unbekannte Nachrichtenfelder, unbekannte code-Werte und Ereignisse ignoriert werden.
Aussehen. Das Erscheinungsbild von Chatfenster, Editor und Kartenbedienelementen kann sich ändern.
Undokumentiertes Verhalten. Alles, was hier nicht beschrieben ist, einschließlich weiterer kaleidr-embed:-Nachrichten zwischen SDK und iframes, der von Produktpaketen definierten globalen Variablen und des exakten Wortlauts von Konsolenmeldungen.

Die HTTP-API folgt unter /inference-api/b2b/v1/ derselben Regel: Ein v2 entsteht nur bei inkompatiblen Änderungen. Die Änderungen stehen im Änderungsprotokoll.

Veröffentlichung inkompatibler Änderungen

Eine Änderung, die eine funktionierende v1-Integration unterbrechen würde, wird nicht unter /embed/v1/ veröffentlicht. Stattdessen erscheint eine neue Hauptversion parallel:

https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js

Ihr v1-Skripttag lädt weiterhin v1-Dateien. Nach dem Lesen der Änderungen können Sie bei Bedarf den Pfad des Skripttags auf die neue Hauptversion umstellen. Der Loader fordert Produktpakete aus seiner eigenen Hauptversion an.

Zwischenspeicherung

Jede Datei wird ausgeliefert mit

Cache-Control: public, max-age=300

und die CDN-Kopie wird bei jedem Release ersetzt.

Frage	Antwort
Wie schnell erreicht ein Release Besucher?	Innerhalb von ungefähr fünf Minuten. Hat ein Browser die alte Datei in den letzten fünf Minuten geladen, verwendet er sie bis zum Ablauf seines Caches.
Lädt ein Besucher das SDK auf jeder Seite neu herunter?	Nein. Nach einem Abruf nutzt der Browser die zwischengespeicherte Kopie fünf Minuten lang; danach prüft er erneut bei der CDN.
Darf ich die Dateien länger zwischenspeichern?	Nein. Ein Proxy, Service Worker oder Build-Prozess mit längerem Cache liefert nach einem Release veralteten Code.
Kann ich Subresource Integrity (`integrity="sha384-…"`) hinzufügen?	Nein. Der Datei-Hash ändert sich bei jedem Release. Browser verweigern Skripte mit abweichendem Hash; die Einbettungen würden beim nächsten Release nicht mehr laden.
Kann ich `kaleidr.js` in mein eigenes Bundle kopieren?	Nein, aus demselben Grund. Binden Sie die URL ein.

Falls Ihre Website einen Service Worker nutzt, der ursprungsübergreifende Skripte cached, nehmen Sie https://cdn.kaleidr.com aus Cache-First-Regeln aus oder verwenden Sie eine Strategie mit erneuter Prüfung.

Loader und Bundles werden getrennt veröffentlicht

Die fünf Dateien werden unabhängig veröffentlicht. Kurz nach einem Release kann deshalb eine Seite ein neueres kaleidr.js mit einem älteren Produktpaket aus dem Browsercache nutzen oder umgekehrt. Darauf ist das SDK ausgelegt:

Der Loader leitet Optionen an das Bundle weiter und toleriert, dass dieses neue Optionen noch nicht kennt.
Wird eine vom Produkt unterstützte Handle-Methode aufgerufen, die im zwischengespeicherten Bundle noch fehlt, passiert nichts und die Konsole meldet dies:
```
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …
```
Ein Neuladen ohne Cache holt das aktuelle Bundle. Sobald der Cache abläuft, verschwindet die Situation von selbst.

Die Seiten in Viewer- und Tile-iframes werden unter https://map-embed.kaleidr.com bereitgestellt und ebenfalls getrennt veröffentlicht. Die SDK-Cache-Einstellungen Ihrer Seite beeinflussen sie nicht.

Self-Hosting

Sie können die fünf Dateien von Ihrer eigenen Herkunftsadresse bereitstellen, sodass alle Skriptquellen zur eigenen Domain gehören. Beachten Sie den Nachteil: Eine selbst gehostete Kopie erhält keine automatischen Fehlerbehebungen. API und iframe-Inhalte werden bei Kaleidr weiter aktualisiert; eine nicht erneuerte Kopie gerät damit auseinander.

Vorgehen beim Self-Hosting:

Spiegeln Sie alle fünf Dateien unter https://your-origin/embed/v1/. Der Pfad ist fest; nur der Ursprung darf sich ändern.

Teilen Sie dem Loader vor seinem Start mit, wo seine Bundles liegen:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script>
<script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>

oder pro Einbindung mit der Option base beziehungsweise dem Attribut base.

Spiegeln Sie die Dateien regelmäßig erneut und liefern Sie sie wie Kaleidr mit kurzer Cache-Lebensdauer aus.

Zulässige Ursprünge für eine Base-Überschreibung

Der Loader lädt keine Bundles von beliebigen Ursprüngen. Eine Base-Überschreibung (globaler Seitenwert, Option base oder Attribut base) wird nur berücksichtigt, wenn ihr Ursprung einer dieser drei ist:

das Kaleidr-CDN (https://cdn.kaleidr.com);
der Ursprung, von dem kaleidr.js selbst geladen wurde; oder
der Ursprung der aktuellen Seite.

Self-Hosting funktioniert, wenn Loader und Bundles vom selben Ursprung ausgeliefert werden. So ist die Anordnung in Schritt 2: kaleidr.js kommt von https://cdn.example.com; deshalb wird https://cdn.example.com als Base akzeptiert. Bundles vom Ursprung der Seite sind ebenfalls zulässig.

Alle anderen Werte werden ignoriert, auch andere Hosts von kaleidr.com. Die Einbettung wird weiterhin erstellt, die Bundles kommen von https://cdn.kaleidr.com, und die Konsole zeigt:

[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.

Diese zwei Anordnungen sind ausgeschlossen:

kaleidr.js von https://cdn.kaleidr.com bei einer Base auf einem dritten Ursprung. Laden Sie dann auch den Loader von diesem dritten Ursprung.
Der Loader auf einem Ihrer Ursprünge und die Bundles auf einem anderen, wobei keiner der Seitenursprung ist. Stellen Sie alle fünf Dateien von einem Ursprung bereit.

Erscheint die Warnung auf einer Seite, deren Content Security Policy nur die eigene Skriptquelle erlaubt, wird die Bundle-Anfrage an https://cdn.kaleidr.com blockiert und nichts angezeigt. Korrigieren Sie die Base, nicht die Richtlinie.

Was Self-Hosting ändert und was nicht:

Nur kaleidr.js selbst zu hosten reicht nicht aus. Ohne Base-Überschreibung lädt der Loader Produktpakete weiterhin von https://cdn.kaleidr.com.
Verwendet wird nur der Ursprung von base. Ein Pfad im Wert wird verworfen; die Pakete werden unter /embed/v1/ dieses Ursprungs angefordert.
window.__KALEIDR_EMBED_BASE__ muss eine Zeichenfolge sein. Andere Werte werden ignoriert.
Self-Hosting betrifft nur Skripte. Der Sitzungsaustausch läuft weiterhin über https://api.kaleidr.com, Viewer- und Tile-iframes über https://map-embed.kaleidr.com, und die Editor-Basiskarte kommt weiterhin von https://tile.kaleidr.com. Ihre Content Security Policy muss diese Quellen weiter zulassen.

Was v1 bedeutet​

Was unter v1 stabil bleibt​

Veröffentlichung inkompatibler Änderungen​

Zwischenspeicherung​

Loader und Bundles werden getrennt veröffentlicht​

Self-Hosting​

Zulässige Ursprünge für eine Base-Überschreibung​

Verwandte Themen​