Kaleidr Chat an eine MapLibre-Karte anbinden

Am Ende dieser Anleitung enthält Ihre Seite eine MapLibre-GL-JS-Karte mit einem darin angedockten Chat-Panel. Wenn ein Besucher eine Frage stellt, erscheint die Antwort fortlaufend im Panel, die erwähnten Orte werden als Marker auf der Karte angezeigt und die Kamera bewegt sich, um sie zu zeigen. Das funktioniert mit jedem Tarif, auch Free, mit einem veröffentlichbaren Schlüssel. Fragen verbrauchen das KI-Guthaben Ihrer Organisation.

Das Panel arbeitet mit dem Stil, den Ihre Karte bereits verwendet. Es ändert weder den Stil noch die Kachelquelle.

Voraussetzungen

Ein veröffentlichbarer Kaleidr-Schlüssel (kld_pk_live_…) von kaleidr.com/api-keys, mit ai für Chat. Siehe API-Schlüssel erstellen.
Die Seiten-Origin muss zugelassen sein, falls der Schlüssel Origins einschränkt, zum Beispiel http://localhost:8080.
Eine MapLibre-Stil-URL. Das Beispiel nutzt den öffentlichen MapLibre-Demostil; für den Produktivbetrieb verwenden Sie Ihren eigenen.
MapLibre GL JS als Script geladen, sodass window.maplibregl existiert. Bei npm-Import siehe npm-Bibliothek als globales Objekt bereitstellen.
Ein HTTP-Server wie npx serve oder python -m http.server 8080. Das Öffnen von der Festplatte funktioniert nicht.
Falls eine Content Security Policy aktiv ist, müssen die Hosts von Content Security Policy erlaubt sein.

Schritt 1: Karte und Chat-Ebene anordnen

Fügen Sie die Karte und das Mount-Ziel des Chats in einen gemeinsamen positionierten Container ein. Die Chat-Ebene liegt über der Karte, lässt aber Pointer-Ereignisse hindurch.

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:absolute; inset:0; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

Erwartetes Ergebnis: noch nichts, nur ein 520 px hoher leerer Bereich. Theming und Layout erklärt die CSS-Deklarationen.

Schritt 2: MapLibre GL JS laden und Karte erzeugen

Laden Sie das Stylesheet im Seitenkopf und das Script vor dem eigenen Code. Beide URLs müssen dieselbe Version verwenden.

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json', // your own style here
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

Erwartetes Ergebnis: eine verschiebbare und zoombare Karte. Der Demostil ist eine einfache Länderkarte mit wenig Stadt-Detail; Marker und Kamerabewegungen funktionieren trotzdem.

Schritt 3: `kaleidr.js` laden

Fügen Sie den Kaleidr-Loader nach dem MapLibre-Script, aber vor dem Code zum Einbinden des Panels ein.

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

Erwartetes Ergebnis: keine sichtbare Änderung. In der Konsole liefert Kaleidr.version eine Versionszeichenfolge.

Schritt 4: Chat-Panel einbinden

Übergeben Sie den Schlüssel und das tatsächliche Kartenobjekt.

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

Auf das load-Ereignis der Karte müssen Sie nicht warten. Kaleidr.mount kehrt sofort zurück; das Panel erscheint, nachdem das Chat-Bundle geladen und der Schlüssel gegen eine Sitzung eingetauscht wurde.

Erwartetes Ergebnis: eine Eingabeleiste mit „Ask Kaleidr“ oben links auf der Karte.

Vollständige Beispielseite

Speichern Sie die Datei als index.html, ersetzen Sie den Schlüssel 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>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      const handle = Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

Verhalten

Besucher	Panel	Ihre MapLibre-Karte
Stellt eine Frage	Erweitert sich zum Chat-Fenster; die Antwort erscheint fortlaufend als Text.	Noch keine Änderung.
Wartet	Zeigt für jeden Ort in der Antwort eine Karteikarte an.	Für jeden gefundenen Ort erscheint ein Marker. Bei einem Ort fliegt die Kamera dorthin; bei mehreren passt sie den Ausschnitt mit Abstand zum Panel an.
Klickt auf Marker oder Ergebnis	Öffnet eine Ortskarte mit Überblick, Fotos und Wegbeschreibung.	Ein Klick auf ein Ergebnis bewegt die Karte dorthin.
Fordert eine Route an	Zeigt Strecke und Dauer.	Zeichnet die Route und passt den Kartenausschnitt an.
Stellt eine weitere Frage	Fügt sie zur bestehenden Unterhaltung hinzu.	Neue Marker kommen hinzu; ältere bleiben bestehen.
Schließt den Chat	Kehrt zur Eingabeleiste zurück; die Unterhaltung endet.	Marker und Route werden entfernt.

Besonderheiten von MapLibre GL JS:

Die Marker sind MapLibre-Objekte vom Typ Marker mit HTML-Element. Sie bleiben von Ihren eigenen Markern getrennt.
Die Route wird mit Sources und Layers gezeichnet, die das Panel dem Stil hinzufügt und wieder entfernt. Ihre eigenen Sources und Layers werden nicht verändert.
Die Sitzung wird im Hintergrund verlängert, solange das Panel eingebunden ist. Tokens müssen Sie nicht verwalten.

Funktion überprüfen

Auf der Seite

Die Ask Kaleidr-Leiste liegt oben links über der Karte.
Geben Sie Show me three museums in London ein und drücken Sie Enter. Die Antwort erscheint, drei Marker werden gesetzt und der Kartenausschnitt umfasst alle drei.

In der Konsole

Keine Fehlermeldung oder Warnung enthält [kaleidr.

Im Netzwerk-Tab

Anfrage	Erwartung
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200 mit einem JSON-Body wie im folgenden Beispiel
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (nach einer Frage)	200, `content-type: text/event-stream`

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat" }

Wenn es nicht funktioniert

Das SDK protokolliert einen kurzen Hinweis ohne die Serverbegründung zu wiederholen. Schlägt eine Anfrage fehl, öffnen Sie sie im Netzwerk-Tab und lesen ihre JSON-Antwort. Bei 403 oder 404 steht der Code in detail; bei 429 in error, ergänzt durch einen Satz in detail.

Symptom	Ursache	Lösung
Kein Panel, CORS-Fehler bei `…/sdk/sessions` und Fehler mit `[kaleidr:chat]`	Der Schlüssel ist unbekannt, widerrufen oder die Seiten-Origin nicht erlaubt. CORS-Header erhalten nur zugelassene Origins.	Prüfen Sie den Schlüssel und tragen Sie die genaue Origin einschließlich Schema und Port unter kaleidr.com/api-keys ein.
`[kaleidr:chat] kaleidr session exchange failed (403)`	Der Schlüssel ist gültig, darf aber Chat nicht starten. `detail` lautet `insufficient_scope` (kein `ai`), `product_not_allowed` (andere Produkte) oder `tier_capability_not_allowed`.	Verwenden Sie einen Schlüssel mit `ai`, der `chat` zulässt.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	Ein Serverschlüssel wurde angegeben; keine Anfrage wurde gesendet.	Verwenden Sie einen veröffentlichbaren Schlüssel (`kld_pk_live_…`). Widerrufen Sie den Serverschlüssel, falls er in einer öffentlich erreichbaren Seite stand.
`[kaleidr:chat] mount target not found: #chat`	Der Selektor findet das Ziel nicht.	Rufen Sie `mount` erst auf, wenn das Element existiert, oder übergeben Sie es direkt. `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	Das Bundle wurde meist durch eine Content Security Policy oder einen Adblocker blockiert.	Erlauben Sie `https://cdn.kaleidr.com` in `script-src`.
`Kaleidr is not defined`	Ihr Code wurde vor `kaleidr.js` ausgeführt, etwa wegen `async` oder `defer`.	Laden Sie `kaleidr.js` vorher mit einem normalen Script-Tag oder starten Sie Ihren Code nach dessen `load`-Ereignis.
`[kaleidr] embed is disabled — …`	Die Freigabesperre hält Mounts zurück.	Die Meldung benennt den Schalter. Siehe kaleidr.js.
Panel sitzt oben links im Browserfenster statt auf der Karte	`contained` fehlt oder `#chat` hat keine Positionierung.	Setzen Sie `contained: true` und verwenden Sie die Styles aus Schritt 1.
Das Panel antwortet, aber keine Marker erscheinen und die Karte bewegt sich nicht	Das an `map` übergebene Objekt wird nicht erkannt.	Übergeben Sie die eigentliche Instanz von `maplibregl.Map`. Siehe Unterstützte Karten.
Die Kamera fliegt zu einem einzelnen Ort, aber Marker fehlen und mehrere Orte werden nicht eingerahmt	`window.maplibregl` fehlt. Für die Bewegung zu einem Ort reicht die Instanz; Marker und Mehrfachanpassung brauchen das globale Objekt.	Stellen Sie bei npm-Import `window.maplibregl` vor dem Mount bereit. Siehe npm-Imports.
Das Panel zeigt stets „Sorry — that didn't go through. Please try again.“	Die Sitzung ist ungültig, weil der Schlüssel widerrufen oder die Origins geändert wurden.	Prüfen Sie den Schlüssel und laden Sie die Seite neu.
Das Panel zeigt „You've reached your usage limit for now.“	HTTP 429: KI-Guthaben aufgebraucht oder Rate-Limit erreicht. Alle Besucher teilen sich die Rate-Begrenzung des Schlüssels.	Siehe Kontingente und Ratenlimits.
Karte lässt sich nicht ziehen	Die Chat-Ebene fängt die Ereignisse ab.	Setzen Sie `pointer-events:none` für `#chat`.

Weitere Symptome stehen auf Fehlerbehebung.

Grenzen

Ihre Seite erhält vom Panel keine Callbacks oder Ereignisse. Sie können nicht per Code auf Fragen, Antworten oder Markerklicks reagieren.
Der Assistent kennt weder Ihre Ebenen und Marker noch den sichtbaren Kartenausschnitt. Nur die Zoomstufe wird mit einer Frage übermittelt.
Eigene Anweisungen oder Daten lassen sich dem Assistenten über dieses Panel nicht geben.
Antwortsprache, Titel und Platzhalter sind Mount-Optionen (lang, title, placeholder): siehe Chat-Referenz. Die übrigen Bezeichnungen sind englisch.
handle.setCamera() hat bei Chat-Einbindungen keine Wirkung und gibt eine Warnung aus. Bewegen Sie die Karte über MapLibre selbst.
In einer Single-Page-App sollten Sie handle.destroy() beim Verlassen der Kartenansicht aufrufen und das Panel beim Zurückkehren neu einbinden.
Das Chat-Panel liefert keine Basiskarte. Für eine Kaleidr-Basiskarte verwenden Sie Tile, das in einem eigenen Element dargestellt wird und über map-target vom Chat gesteuert werden kann.

Die vollständige Liste steht unter Funktionen und Grenzen.

Nächste Schritte

Theming und Layout: Panel an Ihre Website anpassen.
Chat-Referenz: Optionen, Handle und Fehlermeldungen.
Produktions-Checkliste: Prüfungen vor der Veröffentlichung.
Frameworks: Einbindung unter React, Next.js und Vue.

Voraussetzungen​

Schritt 1: Karte und Chat-Ebene anordnen​

Schritt 2: MapLibre GL JS laden und Karte erzeugen​

Schritt 3: kaleidr.js laden​

Schritt 4: Chat-Panel einbinden​

Vollständige Beispielseite​

Verhalten​

Funktion überprüfen​

Wenn es nicht funktioniert​

Grenzen​

Nächste Schritte​