Kaleidr Chat an eine Google-Karte anbinden

Am Ende dieser Anleitung haben Sie eine Seite mit einer Google-Karte und einem darin angedockten Chat-Panel. Ein Besucher stellt eine Frage, die Antwort erscheint fortlaufend im Panel, und die Orte der Antwort werden als Marker auf Ihrer Google-Karte angezeigt, während sich die Kamera dorthin bewegt. Das funktioniert mit allen Tarifen, auch Free, mit einem veröffentlichbaren Schlüssel. Fragen verbrauchen das KI-Guthaben Ihrer Organisation.

Ihr Google-Maps-Schlüssel und Ihr Kaleidr-Schlüssel sind getrennt. Google berechnet die Karte, Kaleidr die Fragen. Kaleidr erhält Ihren Google-Schlüssel niemals.

Voraussetzungen

Ein veröffentlichbarer Kaleidr-Schlüssel (kld_pk_live_…) von kaleidr.com/api-keys. Neue Schlüssel haben den für Chat benötigten Umfang ai. Siehe API-Schlüssel erstellen.
Die Origin der Seite in den erlaubten Origins des Schlüssels, falls der Schlüssel diese einschränkt. Lokal zum Beispiel http://localhost:8080.
Ein Google-Maps-JavaScript-API-Schlüssel aus Ihrem Google-Cloud-Projekt, mit aktivierter Maps JavaScript API und für Ihre Origin erlaubten Referrern.
Ein HTTP-Server wie npx serve oder python -m http.server 8080. Eine Datei von der Festplatte zu öffnen funktioniert nicht.
Falls Ihre Website eine Content Security Policy besitzt, müssen zusätzlich zu den von Google Maps benötigten Hosts die Hosts der Content Security Policy erlaubt sein.

Die Google Maps JavaScript API definiert stets das globale Objekt google.maps. Sie müssen die Bibliothek daher nicht gesondert für das Chat-Bundle verfügbar machen.

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:relative; height:100%; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

Das Kartenelement füllt den Container mit height:100%. Durch position:relative und z-index:0 bleiben die Google-Ebenen innerhalb des Kartenelements und unter der Chat-Ebene.

Erwartetes Ergebnis: noch keine Karte, nur ein 520 px hoher leerer Bereich.

Schritt 3: `kaleidr.js` laden

Laden Sie den Kaleidr-Loader in einem normalen Script-Tag, damit Kaleidr verfügbar ist, wenn der Karten-Callback aufgerufen wird.

<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 3: Callback zum Erzeugen der Karte und Einbinden des Panels definieren

Das Google-Maps-Script ruft nach dem Laden eine von Ihnen benannte Funktion auf. Erzeugen Sie die Karte und binden Sie das Panel innerhalb dieser Funktion ein, da google.maps zuvor noch nicht existiert.

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

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

Erwartetes Ergebnis: weiterhin nichts. Die Funktion ist definiert, wurde aber noch nicht aufgerufen.

Schritt 4: Google-Maps-Script nach dem Callback laden

Fügen Sie das Google-Script-Tag unter dem Script ein, das initMap definiert.

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

Die Reihenfolge ist wichtig. Das Google-Script trägt async und wird vom Browser ausgeführt, sobald es geladen ist; dabei ruft es unmittelbar initMap auf. Steht es vorher, kann es fertig sein, bevor der Browser die initMap-Definition erreicht. Google meldet dann, initMap sei keine Funktion. Durch die vorherige Definition vermeiden Sie diesen Wettlauf.

Erwartetes Ergebnis: eine Google-Karte der Londoner Innenstadt mit einer Eingabeleiste „Ask Kaleidr“ oben links.

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 Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; 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>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

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

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

Verhalten

Besucher	Panel	Google-Karte
Stellt eine Frage	Öffnet ein Chat-Fenster und zeigt die Antwort fortlaufend als Text.	Noch keine Änderung.
Wartet	Zeigt für jeden Ort der Antwort eine Karteikarte.	Marker erscheinen, sobald die Orte lokalisiert sind. Bei einem Ort verschiebt sich die Karte dorthin und ändert den Zoom; bei mehreren werden alle mit 56 px Rand eingerahmt.
Klickt auf Marker oder Ergebnis	Öffnet eine Ortskarte mit Überblick, Fotos und Wegbeschreibung.	Ein Ergebnisklick bewegt die Karte zum Ort.
Fordert eine Route an	Zeigt Strecke und Dauer.	Die Route wird gezeichnet und eingerahmt.
Stellt noch eine Frage	Ergänzt dieselbe Unterhaltung.	Weitere Marker werden hinzugefügt, bisherige bleiben.
Schließt den Chat	Kehrt zur Eingabeleiste zurück und beendet das Gespräch.	Marker und Route werden entfernt.

Besonderheiten von Google Maps:

Marker sind HTML-Elemente, die über ein benutzerdefiniertes Overlay gezeichnet werden. Hierfür ist keine Map ID nötig. Wird die Google-Bibliothek marker geladen, nutzt das Chat-Bundle stattdessen Advanced Markers; Google verlangt dafür ein mapId.
Die Bewegung zu einem Ort erfolgt durch Verschieben und anschließendes Zoomen, nicht durch einen einzigen animierten Flug.
Beim Einpassen verwendet die Karte 56 px Rand an jeder Seite. Das Chat-Panel wird dabei nicht berücksichtigt, sodass ein Marker dahinter liegen kann. Besucher können die Karte verschieben oder das Panel minimieren.
Die Route besteht aus zwei Polylinien: eine weiße Umrandung unter einer farbigen Linie.
Die Karte wird als flach und nach Norden ausgerichtet behandelt. Der Assistent setzt weder Neigung noch Ausrichtung.
Solange das Panel eingebunden ist, wird die Sitzung im Hintergrund erneuert; Tokens verwalten Sie nicht.

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, und die Google Maps API meldet ebenfalls keinen Fehler.

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
Keine Karte; Google meldet `initMap is not a function`	Das Google-Script wurde ausgeführt, bevor `initMap` definiert war.	Fügen Sie das Google-Script wie in Schritt 4 unter dem Callback ein.
Keine Karte oder graue Karte mit Google-Fehlerdialog	Problem mit Ihrem Google-Schlüssel: Maps JavaScript API nicht aktiviert, Abrechnung nicht eingerichtet oder Origin nicht erlaubt.	Korrigieren Sie es in Google Cloud. Es ist unabhängig von Kaleidr.
`Kaleidr is not defined` innerhalb von `initMap`	`kaleidr.js` hat `async` oder `defer`, oder steht hinter dem Google-Script.	Laden Sie `kaleidr.js` zuerst mit einem normalen Script-Tag.
Karte erscheint, Panel aber nicht; CORS-Fehler bei `…/sdk/sessions` und `[kaleidr:chat]`	Kaleidr-Schlüssel unbekannt, widerrufen oder die Origin ist nicht erlaubt. Ohne CORS-Header verbirgt der Browser die Antwort.	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)`	Schlüssel gültig, aber `detail` lautet `insufficient_scope` (kein `ai`), `product_not_allowed` oder `tier_capability_not_allowed`.	Verwenden Sie einen Schlüssel mit `ai`, der `chat` erlaubt.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	Ein Serverschlüssel wurde übergeben. Es wurde keine Anfrage gesendet.	Verwenden Sie einen veröffentlichbaren Schlüssel (`kld_pk_live_…`), und widerrufen Sie den Serverschlüssel, falls er veröffentlicht war.
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	Das Bundle ist meist durch CSP oder einen Adblocker gesperrt.	Erlauben Sie `https://cdn.kaleidr.com` in `script-src`.
Panel sitzt oben links im Browserfenster statt auf der Karte	`contained` fehlt oder `#chat` ist nicht positioniert.	Verwenden Sie `contained: true` und die Styles aus Schritt 1.
Das Panel liegt hinter der Karte	Das Kartenelement hat keinen eigenen Stacking-Kontext.	Behalten Sie `z-index:0` auf `#map` und `z-index:1` auf `#chat`.
Das Panel antwortet, aber Marker und Kamerabewegung fehlen	`map` verweist nicht auf die tatsächliche `google.maps.Map`-Instanz, sondern z. B. ein DOM-Element oder Wrapper.	Übergeben Sie das Objekt von `new google.maps.Map(…)`. Siehe Unterstützte Karten.
Das Panel antwortet und die Karte bewegt sich, aber Marker fehlen	Die Bibliothek `marker` wurde ohne `mapId` geladen.	Setzen Sie `mapId` in den Kartenoptionen oder laden Sie `marker` nicht.
Das Panel zeigt immer „Sorry — that didn't go through. Please try again.“	Sitzung ungültig, weil Schlüssel widerrufen oder erlaubte 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 des Schlüssels erreicht. Alle Besucher teilen sich das Limit.	Siehe Kontingente und Ratenlimits.

Weitere Symptome stehen auf Fehlerbehebung.

Grenzen

Ihre Seite erhält vom Panel keine Callbacks oder Ereignisse; Fragen, Antworten und Markerklicks können nicht per Code verarbeitet werden.
Der Assistent kennt weder Ihre Overlays und Marker noch den sichtbaren Kartenausschnitt. Nur die Zoomstufe wird mit der Frage gesendet.
Eigene Daten oder Anweisungen können Sie dem Assistenten nicht über dieses Panel geben.
Antwortsprache, Titel und Platzhalter sind Mount-Optionen (lang, title, placeholder): siehe Chat-Referenz. Die übrigen Bezeichnungen bleiben englisch.
Einpassen vermeidet das Chat-Panel bei Google Maps nicht.
handle.setCamera() bewirkt auf Chat-Mounts nichts und gibt eine Warnung aus. Bewegen Sie die Karte über die Google-API.
Rufen Sie in einer Single-Page-App handle.destroy() auf, wenn die Kartenansicht entfernt wird, und binden Sie sie beim Zurückkehren neu ein.

Die vollständige Liste steht unter Funktionen und Grenzen.

Nächste Schritte

Theming und Layout: Panel an die Website anpassen.
Unterstützte Karten: Funktionen auf Google Maps.
Chat-Referenz: Optionen, Handle und Fehler.
Produktions-Checkliste: Prüfungen vor der Veröffentlichung.

Voraussetzungen​

Schritt 1: Karte und Chat-Ebene anordnen​

Schritt 3: kaleidr.js laden​

Schritt 3: Callback zum Erzeugen der Karte und Einbinden des Panels definieren​

Schritt 4: Google-Maps-Script nach dem Callback laden​

Vollständige Beispielseite​

Verhalten​

Funktion überprüfen​

Wenn es nicht funktioniert​

Grenzen​

Nächste Schritte​