Zum Hauptinhalt springen

Eine Kaleidr-Basiskarte verwenden

Am Ende dieser Anleitung zeigt Ihre Seite eine interaktive Kaleidr-Basiskarte mit dem gewählten Stil und der festgelegten Kamera. Ihr Code kann die Kamera bewegen und den Stil wechseln. Dies funktioniert mit allen Tarifen, einschließlich Free. Sie benötigen einen veröffentlichbaren Schlüssel mit dem Berechtigungsumfang maps, den neue Schlüssel standardmäßig enthalten.

Voraussetzungen​

  • Ein veröffentlichbarer Schlüssel (kld_pk_live_…) von kaleidr.com/api-keys. Siehe API-Schlüssel erstellen.
  • Die Origin Ihrer Testseite, zum Beispiel http://localhost:3000, muss in den zugelassenen Origins des Schlüssels stehen. Ohne Origin-Beschränkung funktioniert der Schlüssel auf jeder Website.
  • Eine Möglichkeit, die Seite über HTTP auszuliefern, etwa npx serve .. Eine direkt von der Festplatte geöffnete Seite hat keine brauchbare Origin und wird von einem eingeschränkten Schlüssel abgewiesen.
  • Falls Ihre Seite eine Content Security Policy verwendet: https://cdn.kaleidr.com in script-src, https://api.kaleidr.com in connect-src und https://map-embed.kaleidr.com in frame-src zulassen. Siehe Content Security Policy.

Schritt 1: Karte hinzufügen​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Erwartetes Ergebnis: Zunächst erscheint „Loading map…“, danach eine helle Basiskarte. Im Netzwerk-Tab folgt auf einen erfolgreichen POST an https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions (Status 200) eine Dokumentanfrage an https://map-embed.kaleidr.com/. Die Frame-URL enthält die Stil-ID, aber keine Zugangsdaten: Der Schlüssel wird nur beim Sitzungsabruf gesendet; das Sitzungstoken wird nicht an die Frame-URL angehängt.

Das Element benötigt eine Höhe, sonst erhält die Karte eine feste Höhe von 500 Pixeln. <kaleidr-map> hat standardmäßig display:block, sodass die Höhe wirksam wird. Schreiben Sie display:block trotzdem in die CSS-Regel: Das ist unschädlich und berücksichtigt Safari vor 16.4, wo das Element inline bleibt und height ignoriert.

Schritt 2: Stil auswählen​

Setzen Sie style-id auf einen der allgemeinen Stile:

style-idErscheinungsbild
kaleidr-morningHell: weißer Untergrund, türkisfarbenes Wasser, weiße Straßen.
kaleidr-afternoonMittlerer Untergrundton, grüne Vegetation, graue Straßen.
kaleidr-eveningGoldene Stunde mit warmen Sand- und Olivtönen.
kaleidr-nightDunkles Marineblau und Anthrazit mit bernsteinfarbenen Fernstraßen.
kaleidr-plainWeiße Fläche mit Grenzen und Ortsnamen. 3D-Gebäude erscheinen ab Zoomstufe 15.
kaleidr-editorialNachmittagsfarben ohne Beschriftung, für kleine oder dekorative Karten.
<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

Erwartetes Ergebnis: derselbe Kartenausschnitt in dunklen Farben.

Geben Sie style-id immer an. Ohne diese Angabe verwendet das Embed die Standard-Basiskarte der Organisation, sofern eine festgelegt ist. Sonst erscheint im Frame „Couldn't find a map id in the URL.“.

Stil-IDs müssen exakt stimmen. Es gibt keine Kurzformen: night ist kein Alias für kaleidr-night.

Schritt 3: Kamera einstellen​

Ohne Kameraangabe öffnet sich die Karte mit der Standardansicht des Stils, meist einer Weltansicht. Mit center (erst Längengrad, dann Breitengrad) und zoom öffnen Sie den gewünschten Ausschnitt. pitch neigt, bearing dreht die Ansicht.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

Erwartetes Ergebnis: die Londoner Innenstadt, geneigt und gedreht.

zoom wird ohne center ignoriert. pitch und bearing funktionieren auch einzeln.

Schritt 4: Kamera bewegen und Stil im Code wechseln​

Das Element ist die deklarative Variante. Um die Karte mit JavaScript zu steuern, binden Sie sie per Kaleidr.mount ein und behalten das zurückgegebene Handle.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  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: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

Erwartetes Ergebnis: Jede Schaltfläche ändert die Karte direkt. Der iframe wird nicht neu geladen, und im Netzwerk-Tab erscheint kein weiterer Sitzungsabruf.

Wichtige Hinweise:

  • setCamera und setStyle sind Methoden des Handles, nicht des Elements.
  • setStyle gibt es nur bei Tile. Für andere Produkte gibt es eine Warnung aus und bewirkt nichts.
  • Nach der Rückgabe von Kaleidr.mount dürfen Sie die Handle-Methoden jederzeit aufrufen. Aufrufe, die vor der Bereitschaft der Karte im iframe eintreffen, werden zwischengespeichert und in derselben Reihenfolge ausgeführt, sobald die Karte bereit ist. Auf die Meldung kaleidr-embed:ready aus Schritt 6 müssen Sie nicht warten. Für Startkamera und Anfangsstil sind die Mount-Optionen vorgesehen.
  • Bei einem bereits eingebundenen Element bewegen Änderungen an center, zoom, pitch oder bearing die Karte. Eine Änderung an style-id bewirkt nichts.

Schritt 5: Chat-Panel mit der Karte verbinden (optional)​

Ein Kaleidr-Chat-Panel kann eine Tile-Karte steuern: Es platziert Orte aus Antworten als Marker und richtet die Kamera darauf aus. Platzieren Sie das Tile-Element in einem positionierten Container, legen Sie das Chat-Element darüber und verweisen Sie mit map-target auf das Tile-Element.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

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

Erwartetes Ergebnis: Das Chat-Panel sitzt oben links auf der Karte. Fragen Sie „coffee near Covent Garden“; auf der Tile-Karte erscheinen Marker.

Bedeutung der Attribute und CSS-Regeln des Chat-Elements:

BestandteilZweck
map-target="#basemap"CSS-Selektor für das Tile-Element, das der Chat steuern soll.
containedVerankert das Panel im Chat-Element. Ohne diese Option sitzt es fest oben links im Browserfenster.
position:absolute; inset:0Legt das Chat-Element über die gesamte Karte, sodass das Panel an der Kartenecke sitzt.
z-index:1Hält die Chat-Ebene über der Karte.
pointer-events:noneLässt Ziehen und Zoomen der Karte außerhalb des Panels zu. Das Panel selbst bleibt anklickbar.

Anmerkungen:

  • Derselbe Schlüssel eignet sich für beide Elemente, weil neue Standardschlüssel die Berechtigungen maps und ai enthalten. Das Chat-Element fordert eine eigene Sitzung an; jede Frage verbraucht KI-Guthaben.
  • Die Reihenfolge der Elemente ist beliebig. Der Chat sucht die Karte erst, wenn er sie benötigt.

Layout- und Designoptionen finden Sie unter Theming und Layout. Funktionen und Grenzen beschreibt, was der Assistent kann und was nicht.

Schritt 6: Erkennen, wann die Karte geladen ist (optional)​

Das SDK bietet kein ready-Promise, und das Element sendet keine Ereignisse. Stattdessen meldet der iframe Ihrer Seite, wenn die Karte gezeichnet wurde beziehungsweise wenn etwas nicht gezeichnet werden konnte:

const target = document.getElementById('basemap');

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') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

Schlägt der Sitzungsabruf fehl, kommt keine Nachricht, weil kein iframe erzeugt wird. Der Fehler erscheint stattdessen in der Konsole. Siehe Fehlerbehebung.

Vollständige Beispielseite​

Speichern Sie dies als index.html, tragen Sie Ihren Schlüssel ein und stellen Sie das Verzeichnis über HTTP unter einer erlaubten Origin bereit.

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

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

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

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    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 && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

Verhalten​

ThemaVerhalten
SitzungVor der Erzeugung des iframes tauscht das SDK den Schlüssel gegen eine kurzlebige Tile-Sitzung und erneuert sie, solange die Karte eingebunden ist. Der Austausch prüft den Schlüssel und zählt einen Kartenladevorgang. Die Sitzung wird nicht an den iframe übergeben, dessen URL nur Stil und Kamera enthält.
StartansichtDie angegebene Kamera oder die Standardansicht des Stils.
ScrollenScrollen mit dem Mauszeiger über der Karte zoomt die Karte. Befindet sich der Mauszeiger außerhalb der Karte, bewegt Scrollen die Seite. Auf Touchscreens wird die Karte durch Ziehen verschoben und mit einer Pinch-Geste gezoomt.
HöheEntspricht der Höhe des Mount-Ziels zum Einbindungszeitpunkt; ohne Höhe feste 500 Pixel.
LadenDer iframe wird verzögert geladen, wenn er in die Nähe des sichtbaren Bereichs kommt.
Entfernenhandle.destroy() entfernt den iframe und beendet die Sitzungserneuerung. Das Entfernen eines <kaleidr-map>-Elements bewirkt dasselbe.
Erneutes EinfügenWird ein entferntes Element erneut eingefügt oder zu einem anderen übergeordneten Element verschoben, wird es neu eingebunden und eine neue Sitzung angelegt.

Zählung der Kartenladevorgänge​

Jedes Mal, wenn das SDK eine Tile-Sitzung erhält, zählt dies als ein Kartenladevorgang:

EreignisKartenladevorgänge
Karte wird eingebunden1
Sitzung wird erneuert, während die Karte eingebunden bleibt1 je Erneuerung
Karte wird entfernt und erneut eingebunden oder Element erneut eingefügt1
setCamera, setStyle, Verschieben, Zoomen0

Sitzungen gelten standardmäßig 15 Minuten. Das SDK erneuert sie 90 Sekunden vor Ablauf, im Vorder- wie im Hintergrund. Wer die Seite nur wenige Minuten besucht, verbraucht einen Kartenladevorgang. Eine Stunde geöffnete Seite benötigt ungefähr fünf.

So verringern Sie den Verbrauch:

  • Entfernen Sie die Einbindung, wenn die Karte dauerhaft verborgen wird: beim Schließen eines Dialogs, Routenwechsel oder Entfernen eines Tab-Panels.
  • Erzeugen Sie das Element nicht bei jedem Rendern neu. Siehe Framework-Integration für React, Vue und andere.
  • Wechseln Sie den Stil mit setStyle, statt die Karte neu einzubinden.

Sind die Kartenladevorgänge für den Abrechnungszeitraum aufgebraucht, wird eine neue Sitzung mit HTTP 429 und {"detail":"map_load_quota_exceeded"} abgewiesen. Bereits angezeigte Karten bleiben sichtbar; neue Einbindungen zeigen nichts. Siehe Kontingente und Ratenlimits. ({"detail":"map_load_quota_exceeded"})

Funktion überprüfen​

  • Auf der Seite: Die Karte ist interaktiv und zeigt unten die Kartenquellenangabe.
  • In der Konsole: Keine Zeile enthält [kaleidr.
  • Im Netzwerk-Tab: kaleidr.js und tile.js von https://cdn.kaleidr.com; ein POST …/sdk/sessions mit Status 200 und JSON-Feldern session_token und expires_in; eine Dokumentanfrage an https://map-embed.kaleidr.com/?style=….
  • Im Listener: Eine Meldung kaleidr-embed:ready mit source gleich "tile".

Wenn es nicht funktioniert​

Das SDK protokolliert fehlgeschlagene Einbindungen als [kaleidr:tile] … in der Konsole. Bei einer verweigerten Sitzung erscheint nur der HTTP-Status. Der genaue Grund steht in der Antwort auf die Anfrage sessions im Netzwerk-Tab. Ein 403 führt seinen Code in detail, ebenso map_load_quota_exceeded; ein 429 rate_limited führt ihn in error.

SymptomUrsacheAbhilfe
Nichts erscheint; CORS-Fehler bei …/sdk/sessions und [kaleidr:tile]-FehlerDer Schlüssel ist unbekannt oder widerrufen, oder die Origin ist nicht erlaubt. Die Antwort auf die Ablehnung enthält keine CORS-Header.Prüfen Sie den Schlüssel und tragen Sie die exakte Origin (Schema, Host, Port) unter kaleidr.com/api-keys ein. Warten Sie einige Minuten und laden Sie neu. Im Netzwerk-Tab steht 401 oder 403.
[kaleidr:tile] kaleidr session exchange failed (403)Dem Schlüssel fehlt maps (insufficient_scope), er ist auf andere Produkte beschränkt (product_not_allowed), oder der Tarif erlaubt die Anfrage nicht (tier_capability_not_allowed).Lesen Sie detail im Netzwerk-Tab und erstellen Sie einen Schlüssel mit den Standardberechtigungen.
[kaleidr:tile] kaleidr session exchange failed (429)Kartenkontingent erschöpft (map_load_quota_exceeded) oder zu viele Anfragen (rate_limited).Prüfen Sie für Ersteres detail, für Letzteres error. Siehe Kontingente und Ratenlimits.
sessions gibt 404 zurückEin api-base-Override lässt /inference-api aus.Entfernen Sie den Override oder setzen Sie https://api.kaleidr.com/inference-api.
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…Ein Serverschlüssel wurde angegeben; das SDK verweigert ihn vor einer Anfrage.Verwenden Sie einen veröffentlichbaren Schlüssel. Tauschen Sie den Serverschlüssel aus, falls er veröffentlicht wurde.
[kaleidr:tile] Kaleidr tile: invalid style "…"…style-id enthält unerlaubte Zeichen wie Leerzeichen oder ?.Verwenden Sie eine Stil-ID aus Schritt 2.
Der Frame zeigt „Couldn't find a map id in the URL.“; der Listener erhält code: 'no_id' und id: nullstyle-id fehlt und die Organisation hat keine Standard-Basiskarte.Setzen Sie style-id.
Leerer Frame und kaleidr-embed:error mit maplibre_errorDer Stil existiert nicht, meist wegen einer falsch geschriebenen ID.Wählen Sie eine ID aus Schritt 2.
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"product fehlt oder ist falsch geschrieben.Setzen Sie product="tile".
Karte bleibt 500 Pixel hochBeim Einbinden fehlte die Höhe, display:inline wurde gesetzt, oder Safari vor 16.4 kennt display:block nicht für das Element.Geben Sie Höhe und display:block an. height
Leerer Bereich und CSP-Verstoß in der KonsoleDie Richtlinie blockiert Loader, Sitzungsanfrage oder Frame.Lassen Sie die drei Hosts unter Voraussetzungen zu.
setStyle oder setCamera bleibt wirkungslosDer Aufruf erfolgte am Element, oder die Karte wurde noch nicht geladen.Rufen Sie die Methode am Handle von Kaleidr.mount auf. Prüfen Sie kaleidr-embed:error und die Konsole; frühe Aufrufe werden nach 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.
Änderung von style-id am Element bleibt wirkungslosErwartet: style-id wird nur einmal beim Einbinden gelesen.Nutzen Sie handle.setStyle oder fügen Sie ein neues Element ein.

Grenzen​

  • Ihre Seite kann auf einer Tile-Karte keine Marker, Ebenen oder Popups hinzufügen und erhält keine Klick- oder Kameraereignisse. Ein verbundenes Chat-Panel kann jedoch Orte markieren.
  • Es gibt keine Methode, um die aktuelle Kamera auszulesen.
  • Tile ist das unterstützte Produkt zum Anzeigen einer Kaleidr-Basiskarte.
  • Tile-Karten werden nicht dargestellt, wenn die Origin der Seite nicht im Schlüssel erlaubt ist.

Nächste Schritte​