Kaleidr Chat an eine Mapbox-Karte anbinden

Am Ende dieser Anleitung enthält Ihre Seite eine Mapbox-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.

Voraussetzungen

Ein veröffentlichbarer Kaleidr-Schlüssel (kld_pk_live_…) von kaleidr.com/api-keys. Neue Schlüssel besitzen den für Chat nötigen Umfang ai. Siehe API-Schlüssel erstellen.
Die Origin der Seite muss im Schlüssel erlaubt sein, sofern dieser Origins einschränkt. Für lokale Entwicklung tragen Sie beispielsweise http://localhost:8080 ein.
Ein Mapbox-Zugriffstoken (pk.…) aus Ihrem Mapbox-Konto. Mapbox rechnet die Karte ab, Kaleidr die Fragen. Beides ist unabhängig.
Mapbox GL JS über ein Script-Tag geladen, sodass window.mapboxgl existiert. Wenn Sie Mapbox aus npm importieren, lesen Sie Eine npm-Bibliothek als globales Objekt verfügbar machen.
Ein HTTP-Server wie npx serve oder python -m http.server 8080. Das Öffnen einer Datei direkt von der Festplatte funktioniert nicht.
Falls die Seite eine Content Security Policy hat, erlauben Sie die Hosts auf Content Security Policy.

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: Mapbox GL JS laden und Karte erzeugen

Laden Sie das Stylesheet im Seitenkopf und das Script vor Ihrem eigenen Code. Das Stylesheet ist erforderlich: Ohne es wird die Karte nicht korrekt dargestellt.

<link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
<script>
  mapboxgl.accessToken = 'pk.…';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

Erwartetes Ergebnis: eine verschiebbare und zoombare Mapbox-Karte der Londoner Innenstadt.

Schritt 3: `kaleidr.js` laden

Fügen Sie den Kaleidr-Loader nach dem Mapbox-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 beide 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 Mapbox</title>
    <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-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://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      mapboxgl.accessToken = 'pk.…';

      const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v12',
        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 Mapbox-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 Mapbox GL JS:

Die Marker sind Mapbox-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 `mapboxgl.Map`. Siehe Unterstützte Karten.
Die Kamera fliegt zu einem einzelnen Ort, aber Marker fehlen und mehrere Orte werden nicht eingerahmt	`window.mapboxgl` fehlt. Für die Bewegung zu einem Ort reicht die Instanz; Marker und Mehrfachanpassung brauchen das globale Objekt.	Stellen Sie bei npm-Import `window.mapboxgl` 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 Mapbox selbst.
In einer Single-Page-App sollten Sie handle.destroy() beim Verlassen der Kartenansicht aufrufen und das Panel beim Zurückkehren neu einbinden.

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: Mapbox 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​