Eine veröffentlichte Karte einbetten

Nach dieser Anleitung ist Ihre in Kaleidr Studio erstellte Karte auf Ihrer Website live, auf die von Ihnen gewählten Websites beschränkt, und Ihre Seite kann erkennen, ob die Karte geladen wurde. Dies funktioniert mit jedem Tarif, auch Free. Zum Veröffentlichen brauchen Sie ein Kaleidr-Konto, aber keinen API-Schlüssel.

Voraussetzungen

• Eine Karte in Kaleidr Studio, die Sie öffentlich zeigen möchten.
• Eine Webseite, die Sie bearbeiten können. Für das SDK-Element ist ein <script>-Tag erforderlich; für einen normalen iframe nur HTML.
• Falls Ihre Website eine Content Security Policy verwendet, erlauben Sie Frames von https://map-embed.kaleidr.com und beim SDK-Element Skripte von https://cdn.kaleidr.com. Siehe Content Security Policy.
• Einen HTTP-Server zum Testen, beispielsweise npx serve . im entsprechenden Ordner.

Schritt 1: Karte veröffentlichen

1. Öffnen Sie die Karte in Studio und wählen Sie Publish. Die Seite Publish & embed wird geöffnet.
2. Unter Project status steht Draft. Wählen Sie Go Live.

Erwartetes Ergebnis: Der Status wechselt zu Live, die Schaltfläche zu Re-publish, daneben erscheint Unpublish, und der Abschnitt Embed code mit Live-Vorschau darunter wird eingeblendet.

Eine veröffentlichte Karte zeigt den aktuell in Studio gespeicherten Stand, nicht eine Kopie vom Zeitpunkt, an dem Sie Go Live gedrückt haben. Studio speichert Änderungen während der Arbeit. Deshalb ist jede spätere Bearbeitung, auch ein hinzugefügter Datensatz, beim nächsten Laden des Embeds öffentlich. Dafür ist Re-publish nicht nötig. Diese Funktion vermerkt eine neue veröffentlichte Version, behält jedoch ID, Link und Einbettungscode bei; die Besucher sehen davor und danach dieselbe Karte.

Wenn Besucher die laufende Bearbeitung nicht sehen sollen, wählen Sie zuerst Unpublish und veröffentlichen die Karte nach Abschluss erneut, oder bearbeiten eine separate Kopie. Das Aufheben der Veröffentlichung deaktiviert alle Einbettungen, bis Sie erneut veröffentlichen.

Die Veröffentlichung umfasst auch hochgeladene Daten. Datensätze und Bildüberlagerungen aus dem Data-Bereich werden Besuchern als die von Ihnen gestalteten Ebenen angezeigt. Lesen Sie vor der Veröffentlichung möglicherweise vertraulicher Inhalte den Abschnitt Hochgeladene Daten auf veröffentlichten Karten.

Schritt 2: Einbettungscode kopieren

Im Abschnitt Embed code stehen zwei Formate zur Verfügung.

Format in Studio	Ergebnis	Wann verwenden?
iFrame	Ein normaler <iframe> mit Verweis auf die veröffentlichte Karte.	Wenn die Seite keine eigenen Skripte ausführen kann (Website-Baukasten, CMS-Block, Wiki) oder nur die Karte anzeigen soll.
Developer	Der SDK-Loader mit einem <kaleidr-map product="viewer">-Element.	Wenn Sie die Seite programmieren und die Kamera steuern, ein Chat-Panel überlagern oder den Kartenlebenszyklus in einer Single-Page-App verwalten möchten.

Wählen Sie ein Format und klicken Sie auf Copy.

Das iFrame-Format:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

Das Developer-Format:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js" async></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
  style="display:block;width:100%;height:480px;"></kaleidr-map>

YOUR_MAP_ID steht für die Karten-ID aus dem von Studio bereitgestellten Code. Sie besteht aus Buchstaben, Ziffern sowie ., _, ~ und - und ist höchstens 100 Zeichen lang. Beide Formate verwenden dieselbe ID.

Beide Formate bringen die Kaleidr AI der Karte mit: das Panel Ask Kaleidr, wenn ihr Control Tower aktiviert ist, und AI-Chat in ihren Popups, wenn Popup Window aktiviert ist. Siehe Kaleidr AI auf einer veröffentlichten Karte.

Schritt 3: In die Webseite einfügen und Größe festlegen

Fügen Sie den Code an der Stelle ein, an der die Karte erscheinen soll.

Erwartetes Ergebnis: Zuerst erscheint „Loading map…“, danach die Karte in der in Studio gespeicherten Ansicht.

Größenregeln:

• Normaler iframe: Legen Sie width und height wie bei jedem iframe fest.

• SDK-Element: Geben Sie dem Element eine Höhe. <kaleidr-map> hat standardmäßig display:block, daher wird die Höhe angewendet. Die Beispiele verwenden dennoch style="display:block; height:480px", um Safari vor Version 16.4 abzudecken, wo das Element inline bleibt und height ignoriert. Sie können Breite und Höhe auch per Stylesheet setzen.

  kaleidr-map { display: block; height: 480px; }

• Die Karte füllt die Elementbreite aus. Hat das Element beim Einbinden keine Höhe, verwendet die Karte dauerhaft 500 Pixel, selbst wenn Sie die Höhe später setzen. Elemente in ausgeblendeten Tabs oder geschlossenen Bereichen haben möglicherweise keine Höhe. Binden Sie die Karte daher erst bei Sichtbarkeit ein oder vergeben Sie eine feste Höhe.

• Für eine responsive Höhe eignen sich beliebige CSS-Angaben mit berechenbarer Höhe, etwa height:60vh, aspect-ratio:16/9 oder eine Flex-/Grid-Zelle.

Schritt 4: Startkamera festlegen (optional)

Die Karte öffnet mit der vom Autor gespeicherten Ansicht. Für Desktop-, Tablet- und Smartphone-Breiten kann der Autor unterschiedliche Ansichten speichern oder festlegen, dass die Karte ihren Inhalt automatisch einrahmt. Eine so gespeicherte Karte wählt die Ansicht nach der Framebreite und passt sie beim Ändern der Größe wieder an. Um die Karte an einem anderen Ort zu öffnen, übergeben Sie eine Kamera. Für center gilt: zuerst Längengrad, dann Breitengrad.

Auf dem Element:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

Ergänzen Sie beim normalen iframe die URL um camera=longitude,latitude,zoom:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID?camera=-0.1276,51.5072,12&pitch=45&bearing=-20"
  width="100%" height="480" style="border:0;" loading="lazy"
  referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"></iframe>

Eine übergebene Kamera hat Vorrang vor der gespeicherten Ansicht des Autors, auch vor Varianten nach Bildschirmbreite und der automatischen Inhaltseinrahmung. Jeder angegebene Wert ersetzt nur das entsprechende Feld; fehlende Werte behalten die Autoreneinstellungen. Sobald Ihre Seite die Kamera setzt, wird die automatische Anpassung bei Größenänderungen abgeschaltet. Wichtig: zoom wird ignoriert, wenn center nicht ebenfalls angegeben wird. pitch und bearing funktionieren auch allein.

Erwartetes Ergebnis: Die Karte startet mit Ihrer Kamera, während Marker, Ebenen und hochgeladene Daten erhalten bleiben.

Um die Kamera nach dem Laden zu bewegen, binden Sie die Karte über JavaScript ein und bewahren Sie das zurückgegebene Handle auf:

<div id="map" style="height:480px"></div>
<button id="paris">Paris</button>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#map', {
    product: 'viewer',
    shareId: 'YOUR_MAP_ID',
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
  });
</script>

Zwei Hinweise zu setCamera:

• Die Methode befindet sich auf dem von Kaleidr.mount zurückgegebenen Handle, nicht auf dem Element. document.querySelector('kaleidr-map').setCamera ist undefined. Bei einer über das Element eingebundenen Karte verändern Sie die Attribute center, zoom, pitch oder bearing; die Ansicht springt ohne Animation an die neue Stelle.
• Sie können die Methode jederzeit nach Kaleidr.mount aufrufen. Befehle vor der Bereitschaft der Karte im iframe werden zwischengespeichert und ausgeführt, sobald die Karte bereit ist. Sie müssen also nicht auf die Nachricht kaleidr-embed:ready aus Schritt 6 warten. Für die Startansicht verwenden Sie Mount-Optionen.
• Ebenso wie eine beim Laden gesetzte Kamera überschreibt die Methode die Autorenansicht und beendet die automatische Anpassung bei Größenänderungen. Nicht angegebene Werte behalten ihre derzeitige Einstellung.

Schritt 5: Zulässige Websites beschränken (optional)

Standardmäßig kann eine veröffentlichte Karte auf jeder Website angezeigt werden, die ihre ID kennt. So schränken Sie dies ein:

1. Öffnen Sie die Karte in Studio und wählen Sie Share. Der Dialog veröffentlicht die Karte gegebenenfalls und erstellt bei jedem Öffnen einen neuen Freigabelink.

2. Öffnen Sie den Tab Embed.

3. Stellen Sie im Dropdown Any domain auf Specific domains um.

4. Tragen Sie eine Domain pro Zeile ein, beispielsweise:

   example.com
   blog.example.org

5. Klicken Sie außerhalb des Felds. Studio speichert die Liste und zeigt Saved.

Erwartetes Ergebnis: Die Karte wird auf den eingetragenen Websites weiterhin angezeigt. Auf anderen Websites meldet der Frame „This map isn’t allowed to render on this site. Please contact the map owner.“

So erfolgt der Listenabgleich:

• Geben Sie nur Hostnamen ein. Ein führendes https:// wird ignoriert; Pfad und Port gehören nicht hinein.
• Eine Domain umfasst auch Subdomains. example.com erlaubt example.com, www.example.com und shop.eu.example.com.
• Fügen Sie für lokale Tests bei aktiver Liste localhost hinzu.

Die Prüfung hängt vom Referrer ab

Die Karte prüft anhand des vom Browser beim Laden des iframes gesendeten Referrers, ob die Seite zugelassen ist. Ohne Referrer wird eine auf Domains beschränkte Karte nicht angezeigt. Das geschieht beispielsweise, wenn:

• Ihre Seite Referrer-Policy: no-referrer oder same-origin als Antwortheader oder <meta name="referrer"> festlegt;
• der iframe referrerpolicy="no-referrer" verwendet;
• die Seite als lokale file://-URL geöffnet wird;
• jemand die iframe-URL direkt in einem Browser-Tab öffnet.

Die Browser-Standardrichtlinie strict-origin-when-cross-origin übermittelt den Origin und funktioniert. Falls Ihre Seite eine strengere Richtlinie verwendet, behalten Sie beim normalen iframe referrerpolicy="no-referrer-when-downgrade" aus dem Beispiel bei, oder lockern Sie die Richtlinie für die einbettende Seite.

Wird Ihre Karte in einem weiteren Frame angezeigt, ist dessen Adresse der Referrer. Die Domain dieses Frames muss daher auf der Liste stehen.

Zugelassene Domains steuern lediglich, wo die Karte sichtbar ist. Sie schützen nicht den Inhalt einer veröffentlichten Karte – einschließlich ihrer Datensätze – vor dem Lesen. Siehe Hochgeladene Daten auf veröffentlichten Karten. Veröffentlichen Sie keine Daten, die vertraulich bleiben müssen.

Schritt 6: Laden oder Fehler erkennen (optional)

Das SDK bietet kein ready-Promise und das Element sendet keine Ereignisse. Stattdessen schickt der iframe in zwei Fällen eine Nachricht an die Seite:

Nachricht	Zeitpunkt	Felder
kaleidr-embed:ready	Die Karte wurde zum ersten Mal gezeichnet.	type, id (Karten-ID), source ("publish" oder "share")
kaleidr-embed:error	Die Karte konnte nicht geladen oder ein Teil nicht gezeichnet werden.	type, id, code, message

Hören Sie auf window und prüfen Sie sowohl die Herkunft der Nachricht als auch den sendenden Frame:

const el = document.getElementById('locations'); // the <kaleidr-map> element

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = el.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    console.log('map loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    console.warn('map problem', msg.code, msg.message);
  }
});

Bei einem normalen iframe vergleichen Sie event.source mit dessen contentWindow.

Der code einer Fehlermeldung lautet:

code	Bedeutung	Anzeige im Frame
no_id	Die iframe-URL enthält keine Karten-ID.	„Couldn't find a map id in the URL.“
not_found	Keine veröffentlichte Karte mit dieser ID: nie veröffentlicht, wieder unveröffentlicht oder ID falsch.	„This map isn't available — it may have been unpublished, paused, or the link is incorrect.“
domain_not_allowed	Die Website steht nicht auf der Liste oder sendet keinen Referrer.	„This map isn't allowed to render on this site. Please contact the map owner.“
map_loads_exhausted	Das Kartenlade-Kontingent der Organisation ist aufgebraucht.	„This map has reached its map load limit. It will be available again when the owner's allowance resets.“
fetch_failed	Die Karte konnte nicht abgerufen werden, z. B. aufgrund eines Netzwerkproblems.	„Could not load the map. Please try again in a moment.“
maplibre_error	Die Karte wurde gestartet, aber ein Teil konnte nicht gezeichnet werden; message enthält Details.	Die Karte, möglicherweise unvollständig.

Hinweise zum Zeitpunkt:

• Bei jedem Fehlercode außer maplibre_error erscheint keine Karte und ready wird nie gesendet.
• maplibre_error kann vor oder nach ready und mehrfach auftreten. Behandeln Sie es als Warnung, nicht als Beweis einer völlig unbrauchbaren Karte.
• Der SDK-iframe wird verzögert geladen. Liegt die Karte weit unter dem sichtbaren Bereich, startet das Laden erst, wenn der Besucher dorthin scrollt. Einige Sekunden ohne Meldung sind deshalb kein Fehler.
• Der Frame sendet weitere interne Nachrichten mit Präfix kaleidr-embed:. Sie sind kein öffentlicher Vertrag. Reagieren Sie nur auf die beiden oben genannten Typen.

Vollständige Seite

Speichern Sie die Datei als index.html, ersetzen Sie YOUR_MAP_ID und stellen Sie den Ordner über HTTP bereit.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our locations</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #map { height: 480px; }
  </style>
</head>
<body>
  <h1>Our locations</h1>
  <p id="status">Loading the map…</p>

  <div id="map"></div>
  <p>
    <button id="london">London</button>
    <button id="paris">Paris</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('map');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'viewer',
      shareId: 'YOUR_MAP_ID',
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (!msg || typeof msg.type !== 'string') return;

      if (msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      } else if (msg.type === 'kaleidr-embed:error' && msg.code !== 'maplibre_error') {
        status.textContent = 'The map could not load (' + msg.code + ').';
      }
    });

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 12, duration: 800 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
    });
  </script>
</body>
</html>

Verhalten

Thema	Verhalten
Startansicht	Die gespeicherte Ansicht des Autors, sofern Sie keine Kamera übergeben. Übergebene Werte haben feldweise Vorrang.
Scrollen	Scrollen mit dem Mauszeiger über der Karte zoomt die Karte, wie in Studio. Befindet sich der Mauszeiger außerhalb der Karte, bewegt Scrollen die Seite. Auf Touchgeräten wird die Karte durch Ziehen bewegt und mit einer Pinch-Geste gezoomt.
Aktualisierungen	Embeds zeigen den aktuell in Studio gespeicherten Stand. Änderungen erscheinen beim nächsten Laden, ohne erneute Veröffentlichung.
Hochgeladene Daten	Datensätze und Bildüberlagerungen aus dem Data-Bereich werden als gestaltete Ebenen gezeigt. Siehe Hochgeladene Daten.
Veröffentlichung aufheben	Nicht mehr veröffentlichte Karten zeigen eine Nichtverfügbarkeitsmeldung. Erneutes Veröffentlichen stellt die gleichen URLs wieder her; siehe Unpublish.
Popups	Orts-Popups öffnen sich beim Anklicken nur, wenn der Autor sie aktiviert hat.
Höhe	Folgt der Höhe des Elements beim Mount, sonst fest 500 Pixel.
Laden	Der SDK-iframe lädt verzögert beim Annähern an den sichtbaren Bereich.
Schlüssel	Keiner erforderlich. Übergeben Sie keinen veröffentlichbaren Schlüssel an Viewer: Dadurch entsteht eine unnötige Sitzungsanfrage, deren Ablehnung die Karte am Anzeigen hindert.

Hochgeladene Daten auf veröffentlichten Karten

Datensätze aus dem Data-Bereich von Studio gehören zur veröffentlichten Karte. Besucher sehen alle als gestaltete Ebenen und die Bildüberlagerungen an den entsprechenden Positionen. Dies gilt für normale iframes, SDK-Elemente und Freigabelinks gleichermaßen. Es muss nichts aktiviert werden; auch der einbettende Host benötigt keinen Schlüssel.

Weil veröffentlichte Karten den jeweils gespeicherten Stand anzeigen, werden nach der Veröffentlichung hinzugefügte Datensätze mit dem Speichern sofort öffentlich. Eine erneute Veröffentlichung ist nicht nötig.

Welche Daten ausgeliefert werden und an wen:

• Nur Daten einer veröffentlichten Karte. Datensätze werden Besuchern ausschließlich als Bestandteil veröffentlichter Karten oder eines Freigabelinks bereitgestellt, wenn die jeweilige Karte diese Datensätze enthält. Unveröffentlichte Kartendaten werden nicht ausgeliefert.
• Ein Datensatz kann nicht einzeln abgerufen werden. Es gibt keine Auflistung aller Kartendatensätze; eine Datensatz-ID öffnet außerhalb ihrer veröffentlichten Karte nichts.
• Wer die Karte öffnen kann, kann die Daten lesen. Eine veröffentlichte Karte ist öffentlich. Domainbeschränkungen schützen nur die Darstellung auf Websites, nicht die Daten.
• Alle Spalten werden ausgeliefert, nicht nur gestaltete. Der Browser bekommt jede Zeile mit sämtlichen Spalten. Entfernen Sie vor der Veröffentlichung vertrauliche Spalten aus der Datei und laden Sie sie erneut hoch.

So stoppen Sie die Bereitstellung eines Datensatzes:

Aktion in Studio	Wirkung auf die veröffentlichte Karte	Wirkung auf einen Freigabelink
Datensatz im Data-Bereich löschen	Der Datensatz wird gelöscht und nicht mehr ausgeliefert; der Rest der Karte bleibt unverändert.	Der Link zeigt die Karte ohne die Datensatzebene.
Karte unveröffentlichen	Die Karte einschließlich ihrer Datensätze wird nicht mehr ausgeliefert.	Bereits vorhandene Freigabelinks bleiben mit ihren bisherigen Daten aktiv.

Um einen Datensatz zu löschen, wählen Sie das Papierkorbsymbol seiner Zeile im Datenbereich und bestätigen Sie. Datensatz löschen oder ersetzen erklärt die Schritte und die Folgen von „Rückgängig“. Das Löschen nur der Ebenen, die einen Datensatz darstellen, ist nicht dasselbe: Der Datensatz bleibt gespeichert und Teil der Karte und wird daher weiterhin ausgeliefert.

Freigabelinks

Ein Freigabelink ist eine Momentaufnahme des Kartendesigns. Er zeigt die Karte so, wie sie beim Erstellen des Links aussah. Spätere Änderungen an der Karte oder ihre Zurücknahme aus der Veröffentlichung ändern diese Ansicht nicht. Die Momentaufnahme enthält auch den damaligen Kartennamen, die damals geltende Liste zulässiger Domains und die damaligen Schalter von Kaleidr AI. Spätere Änderungen daran ändern nicht, wo ein bereits erstellter Link angezeigt wird oder welche Funktionen von Kaleidr AI er bietet. Seine Kaleidr AI braucht zudem die Karte: Sie funktioniert nur, solange die Karte veröffentlicht ist, und nur auf einer Seite, die die zulässigen Domains der Karte jetzt umfassen. Die Zurücknahme der Veröffentlichung oder das Entfernen einer Domain stoppt sie daher. Die Organisation, der die Karte gehört, bezahlt sie; siehe Kaleidr AI auf einer veröffentlichten Karte.

Ein Freigabelink ist eine Momentaufnahme des Kartendesigns. Er zeigt die Karte zum Zeitpunkt der Linkerstellung. Spätere Bearbeitungen und das Aufheben der Veröffentlichung verändern die Ansicht nicht. Datensätze bilden die Ausnahme: Freigabelinks lesen denselben gespeicherten Datensatz, sodass dessen Löschung auch die Darstellung in allen Freigabelinks beendet.

Beim Öffnen des Studio-Dialogs Share wird die Karte veröffentlicht und jedes Mal ein neuer Freigabelink erstellt. Eine mehrfach geteilte Karte kann deshalb mehrere Design-Schnappschüsse als eigene Links besitzen.

In Studio gibt es keine Funktion, um einen Freigabelink zu löschen oder zu pausieren. Der Link bleibt nutzbar, bis seine Daten gelöscht werden oder Kaleidr auf Anfrage den Link entfernt. Für eine neuere Kartenfassung öffnen Sie Share erneut und verwenden den neuen Link; alte Links behalten ihren vorherigen Stand.

Karte unveröffentlichen

Auf der Seite Publish & embed steht bei einer Live-Karte Unpublish neben Re-publish. Studio fragt: „Unpublish this map? Embeds of it stop working. Share links you have already handed out still show the map, but their Kaleidr AI stops.“ Mit Unpublish bestätigen Sie, mit Cancel brechen Sie ab.

• Sämtliche Embeds dieser Karte stoppen, zeigen die Nichtverfügbarkeitsmeldung und senden not_found.
• Die Karten-ID bleibt erhalten. Mit Go Live stellen Sie später dieselben Embed-URLs wieder her; der Code auf den Webseiten muss nicht geändert werden.
• Bereits verteilte Freigabelinks bleiben mit ihren Daten erreichbar. Ihre Kaleidr AI stoppt, bis Sie die Karte erneut veröffentlichen.

Die Sperrung wird nicht überall sofort wirksam:

• Ein Browser, der Daten bereits geladen hat, behält sie. Ein Besucher mit geöffneter Karte sieht die Ebene weiter. Außerdem können Browser bereits geladene Daten noch einige Minuten aus dem Cache verwenden.
• Bereits ausgegebene Download-Links können bis zu einer Stunde funktionieren. Für größere Datensätze erhält der Browser eine temporäre Download-URL. Vor Löschen oder Unveröffentlichen ausgegebene Links funktionieren bis zum Ablauf, höchstens eine Stunde.

Ladeverhalten:

• Jeder Besucher lädt den gesamten Datensatz herunter. Die Karte lädt Datensätze beim Verschieben nicht stückweise. Viele Zeilen oder Spalten verlängern deshalb die Ladezeit, besonders bei langsamen Verbindungen. Veröffentlichen Sie nur benötigte Zeilen und Spalten.
• Ein fehlerhafter Datensatz macht nicht die ganze Karte unbrauchbar. Der Rest wird ohne die betreffende Ebene gezeichnet.

Upload-Grenzen stehen unter Datensatzlimits.

Zählung der Kartenaufrufe

Jedes Laden des Embeds durch einen Besucher zählt als ein Kartenladevorgang für die Organisation, die die Karte besitzt, nicht für die einbettende Website. Derselbe Besucher zählt beim erneuten Laden derselben Karte innerhalb von 24 Stunden nicht erneut. Aufrufe auf Kaleidrs eigenen Seiten, beispielsweise in der Studio-Vorschau, werden nicht gezählt.

Wenn die Organisation ihr Kartenlade-Kontingent im Abrechnungszeitraum erschöpft hat, zeigen Embeds eine entsprechende Meldung und senden map_loads_exhausted, bis das Kontingent zurückgesetzt wird. Siehe Kontingente und Ratenbegrenzungen.

Funktion prüfen

• Auf der Seite: Die Karte zeigt Marker, Routen, Datensätze und Bildüberlagerungen aus dem Data-Bereich von Studio in den von Ihnen gestalteten Ebenen. Zoom-Schaltflächen funktionieren, unten steht die Attribution.
• In der Konsole: Keine Zeile enthält [kaleidr.
• Im Netzwerk-Tab: Ein Dokumentaufruf an https://map-embed.kaleidr.com/embed/YOUR_MAP_ID mit Status 200; beim SDK-Element zusätzlich kaleidr.js und viewer.js von https://cdn.kaleidr.com.
• Im Listener: Eine Nachricht kaleidr-embed:ready.

Fehlerbehebung

Symptom	Ursache	Lösung
Die Karte ist immer 500 Pixel hoch, unabhängig vom gesetzten height.	Beim Einbinden hatte das Element keine Höhe, CSS setzt display:inline oder Safari vor 16.4 hat kein display:block.	display:block und Höhe setzen; nur bei Sichtbarkeit einbinden.
Nichts erscheint. Konsole: [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product fehlt oder ist falsch geschrieben.	product="viewer" setzen.
Konsole: [kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.	share-id fehlt, ist leer oder ungültig.	ID erneut aus Studio kopieren.
Konsole: [kaleidr:viewer] mount target not found: #map	Kaleidr.mount lief vor dem Erzeugen des Elements, oder der Selektor ist falsch.	Skript nach dem Element ausführen oder Selektor korrigieren.
Konsole: Kaleidr is not defined	Ihr Skript lief vor dem Laden von kaleidr.js; Studio verwendet dafür async.	async entfernen oder Code beim load-Ereignis starten.
Im Frame steht „This map isn't available…“.	Karte nicht veröffentlicht, unveröffentlicht oder ID falsch.	Go Live in Studio wählen; bei erneutem Veröffentlichen bleibt die ID bestehen.
Frame meldet „This map isn't allowed to render on this site.“	Domain nicht erlaubt oder kein Referrer gesendet.	Domain in Studio eintragen oder Referrer-Richtlinie anpassen. Siehe Schritt 5.
Frame meldet „This map has reached its map load limit.“	Kartenlade-Kontingent erschöpft.	Auf Zurücksetzung warten oder Kontingent erhöhen; siehe Kontingente.
Frame meldet „Could not load the map. Please try again in a moment.“	Karte konnte nicht abgerufen werden.	Neu laden; bei anhaltendem Fehler Netzwerk prüfen und iframe-URL separat öffnen.
Leerer Frame und CSP-Verstoß für frame-src.	Die Richtlinie blockiert den Frame.	https://map-embed.kaleidr.com in frame-src erlauben.
CSP-Verstoß für script-src.	Die Richtlinie blockiert den Loader.	https://cdn.kaleidr.com in script-src erlauben oder einen normalen iframe verwenden.
setCamera hat keine Wirkung.	Karte noch nicht bereit oder Handle zerstört.	kaleidr-embed:error und Konsole prüfen. Frühe Kamerabefehle werden bei Bereitschaft ausgeführt. Falls die Karte innerhalb der begrenzten Wartezeit (normalerweise 10 Sekunden nach dem Laden des Frames) keine Bereitschaft meldet, wird der Aufruf trotzdem gesendet. Die Konsole zeigt [kaleidr] the map frame has not reported ready an; in einem Frame mit Fehler gibt es keine Karte, die bewegt oder geändert werden kann.
el.setCamera is not a function	Methode wurde auf dem Element aufgerufen.	Handle von Kaleidr.mount nutzen oder Kameraattribute ändern. setCamera
Das Scrollen der Seite stoppt an der Karte.	Das ist beabsichtigt: Mit dem Mauszeiger über der Karte zoomt Scrollen die Karte.	Mit dem Mauszeiger neben der Karte scrollen. Die Karte niedriger als die Bildschirmhöhe machen, damit Besucher an ihr vorbeiscrollen können.
Neue Änderungen fehlen im Embed.	Das Embed liest beim Laden den gespeicherten Stand; es wurde vor dem Speichern geladen.	Seite neu laden, nicht erneut veröffentlichen.
Eine unbeabsichtigte Bearbeitung ist öffentlich sichtbar.	Die veröffentlichte Karte zeigt immer den aktuellen gespeicherten Stand.	Bearbeitung rückgängig machen oder vor privaten Änderungen unveröffentlichen bzw. eine Kopie nutzen. Referenz
Eine Ebene aus hochgeladenen Daten fehlt.	Datensatz gelöscht oder vorübergehend nicht ladbar; der Rest der Karte funktioniert.	Vorhandensein von Datensatz und Ebene in Studio prüfen, dann neu laden.
Große Datensatzebenen erscheinen spät.	Jeder Besucher lädt den gesamten Datensatz herunter.	Weniger Zeilen und Spalten hochladen; siehe Hochgeladene Daten.

Einschränkungen

• Das Embed ist schreibgeschützt. Ihre Seite kann keine Marker oder Ebenen hinzufügen, die Daten lesen oder Klickereignisse empfangen.
• Die einzigen Signale an Ihre Seite sind kaleidr-embed:ready und kaleidr-embed:error.
• Sie können die Karte aus dem Embed nicht umgestalten oder die Basiskarte tauschen. Ändern Sie sie in Studio; das Embed zeigt sie beim nächsten Laden.
• Änderungen an share-id nach dem Einbinden haben keine Wirkung. Entfernen und erstellen Sie das Element neu, oder verwenden Sie handle.destroy() und binden erneut ein.
• Die Domainbeschränkung hängt vom Browser-Referrer ab und ist kein Geheimnis. ,

Nächste Schritte

• Viewer-Referenz: alle Optionen, Attribute und Meldungen.
• Kaleidr AI auf einer veröffentlichten Karte: Fragen von Besuchern zur Karte.
• Datensätze auf Karten: Dateiformate, Limits und Spaltenrollen.
• Framework-Integration: Karten in React, Next.js und Vue einbinden und entfernen.
• Content Security Policy: erlaubte Hosts und Richtlinien.