Schnellstart

Diese Seite führt Sie durch die drei kürzesten funktionsfähigen Integrationen, in der Reihenfolge, in der Teams sie meist benötigen:

Chat auf einer vorhandenen Karte. Ein Chatfenster beantwortet Fragen zu Orten und zeigt Antworten als Marker, Kamerabewegungen und Routen auf Ihrer Karte.
Eine veröffentlichte Karte. Eine in Kaleidr Studio gestaltete Karte, eingebettet in Ihre Seite.
Eine Basiskarte. Eine von Kaleidr entworfene, sofort verwendbare Basiskarte auf Ihrer Seite.

Jede Variante besteht aus einer HTML-Datei. Alle drei funktionieren im Tarif Free.

Variante	Produkt	Benötigter Schlüssel	Darstellung
Chat auf Ihrer Karte	`chat`	Veröffentlichbarer Schlüssel	Auf Ihrer Seite über der Karte
Veröffentlichte Karte	`viewer`	Keiner	In einem Kaleidr-iframe
Basiskarte	`tile`	Veröffentlichbarer Schlüssel	In einem Kaleidr-iframe

Wenn Sie zuerst das System verstehen möchten, lesen Sie So funktioniert Kaleidr. Bei der Produktwahl hilft Wählen Sie Ihren Weg.

Vorbereitung

Ein Kaleidr-Konto. Registrieren Sie sich unter kaleidr.com. Der Free-Tarif reicht für alle Beispiele.
Ein veröffentlichbarer Schlüssel für Chat und Basiskarte. Erstellen Sie ihn unter kaleidr.com/api-keys; er beginnt mit kld_pk_live_. API-Schlüssel erhalten erklärt die Schritte. Für die veröffentlichte Karte ist kein Schlüssel erforderlich.
Ein Webserver für die Seite. Stellen Sie die Datei auch lokal über HTTP bereit. Im Ordner mit der Datei funktioniert eine dieser Methoden:
```
python -m http.server 8000
# or
npx serve -l 8000
```
Öffnen Sie dann http://localhost:8000/your-file.html. Öffnen Sie die Datei nicht direkt von der Festplatte: Eine file://-Seite hat keine Origin, die der Schlüsselliste hinzugefügt werden könnte.
Ihre Seiten-Origin in der Schlüsselliste, falls diese gesetzt ist. Ein Schlüssel ohne Origin-Liste funktioniert von jeder Website. Mit Liste sind nur die aufgeführten Origins erlaubt; fügen Sie für Tests http://localhost:8000 hinzu.
Eine Content Security Policy, die Kaleidr zulässt, sofern Ihre Site eine solche verwendet. Ohne Header Content-Security-Policy ist keine Änderung erforderlich. Andernfalls lesen Sie Content Security Policy.

Jede Variante beginnt mit demselben Skript-Tag. Dies ist die einzige Datei, die Sie selbst laden; sie holt beim Mounten den Code des jeweiligen Produkts.

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

Chat auf Ihrer Karte

Das Ergebnis ist eine MapLibre-GL-JS-Karte mit einem angedockten Chatfenster. Auf die Frage „Wo bekomme ich Ramen in der Nähe des Bryant Park?“ wird die Antwort gestreamt, Orte werden markiert und die Kamera zeigt sie an.

Das Beispiel verwendet MapLibre GL JS. Chat lässt sich auch mit Mapbox GL JS, der Google Maps JavaScript API und Leaflet verbinden. Siehe Unterstützte Karten.

1. Seite erstellen

Speichern Sie die Datei als chat.html und ersetzen Sie kld_pk_live_… durch Ihren veröffentlichbaren Schlüssel.

<!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; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <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', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

Drei Details dieser Datei sind wichtig:

Die Kartenbibliothek ist global auf der Seite. Der Chat findet MapLibre unter window.maplibregl. Ein MapLibre-Skript-Tag setzt diese globale Variable. Wenn Sie die Bibliothek über npm importieren, setzen Sie sie vor dem Mounten selbst: window.maplibregl = maplibregl.
map ist das Kartenobjekt. Übergeben Sie die erstellte Instanz statt eines CSS-Selektors.
contained: true benötigt einen positionierten Container mit Höhe. Das Fenster wird im Mount-Ziel gerendert. Ohne contained erscheint es als festes Fenster oben links im Browser.

Der Demo-Stil ist eine wenig detaillierte Weltkarte. Marker erscheinen an korrekten Koordinaten; verwenden Sie Ihren eigenen Stil, um Straßen zu sehen.

2. Bereitstellen und Frage stellen

Starten Sie einen lokalen Server im Dateiordner und öffnen Sie http://localhost:8000/chat.html.

Erwartetes Ergebnis:

Die Karte füllt das Fenster aus, oben links liegt ein Chatfenster mit Texteingabe.
Im Netzwerk-Tab liefert eine Anfrage an https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions den Status 200. Der SDK tauscht den Schlüssel gegen eine kurzlebige Sitzung.
Geben Sie eine Ortsfrage wie Where can I get ramen near Bryant Park? ein. Die Antwort erscheint nach und nach, für jeden Ort wird ein Marker erstellt und die Kamera darauf ausgerichtet. Im Netzwerk-Tab bleibt eine Anfrage an …/b2b/v1/chat/control/stream während des Streams geöffnet.
Die Konsole enthält keine Zeilen mit [kaleidr.

3. Wenn es nicht funktioniert

Anzeige	Ursache	Lösung
Kein Fenster; die Konsole zeigt einen CORS-Fehler für `…/sdk/sessions` und danach einen Fehler `[kaleidr:chat]`	Der Schlüssel ist falsch oder widerrufen oder die Seiten-Origin fehlt in der erlaubten Liste. Die API sendet keine CORS-Header, daher meldet der Browser einen CORS-Fehler.	Prüfen Sie den Schlüssel. Ergänzen Sie unter kaleidr.com/api-keys die genaue Origin einschließlich Port oder leeren Sie die Liste für den Test.
Das Fenster steht oben links im Browser, nicht auf der Karte	`contained: true` fehlt oder das Mount-Ziel ist nicht positioniert	Übergeben Sie `contained: true` und geben Sie dem Ziel `position: relative` sowie eine Höhe.
Das Fenster antwortet, aber Marker fehlen	Die Kartenbibliothek ist nicht global auf der Seite, sodass der Chat keine Marker erstellen kann	Laden Sie die Bibliothek per Skript-Tag oder setzen Sie `window.maplibregl` vor `Kaleidr.mount`.

Fehlerbehebung erklärt alle Symptome anhand der genauen Konsolenmeldungen.

Als Nächstes: Chat mit MapLibre verbinden ist die ausführliche Anleitung; Funktionen und Grenzen beschreibt die Möglichkeiten und Einschränkungen.

Eine veröffentlichte Karte

Sie zeigen eine in Kaleidr Studio gestaltete Karte auf Ihrer eigenen Seite. Es ist kein API-Schlüssel erforderlich – die öffentliche Karten-ID reicht.

1. Karte veröffentlichen und ID kopieren

Öffnen Sie die Karte in Kaleidr Studio und wählen Sie Veröffentlichen.
Wählen Sie auf der Seite Veröffentlichen und einbetten die Option Live schalten.
Kopieren Sie den Abschnitt unter Einbettungscode. Die ID ist der letzte Adressteil: Bei https://map-embed.kaleidr.com/embed/abc123 lautet sie abc123.

Erwartetes Ergebnis: Der Projektstatus lautet live. Die Vorschau unter dem Einbettungscode zeigt die Besucheransicht.

2. Seite erstellen

Speichern Sie die Datei als map.html und ersetzen Sie YOUR_SHARE_ID durch die kopierte ID.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

Das Element benötigt eine Höhe; andernfalls ist die Karte 500 Pixel hoch. <kaleidr-map> verwendet standardmäßig display:block, daher wirkt die Höhe. Das Beispiel setzt display:block auch für Safari vor 16.4, wo das Element inline bleibt und eine Höhe nicht wirkt.

Wenn Sie kein Skript hinzufügen können (Website-Builder oder CMS-Feld), verwenden Sie den einfachen iframe aus Studios Register iFrame. Er benötigt keinen Loader:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_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>

3. Seite bereitstellen

Öffnen Sie http://localhost:8000/map.html.

Erwartetes Ergebnis:

Ihre Karte ist 480 Pixel hoch und so breit wie die Seite. Sie startet in der in Studio gespeicherten Ansicht.
Scrollen mit dem Mauszeiger über der Karte zoomt sie. Mit dem Mauszeiger neben der Karte bewegt Scrollen die Seite.
Im Elemente-Tab befindet sich ein <iframe> im Element <kaleidr-map>; dessen Adresse beginnt mit https://map-embed.kaleidr.com/embed/.

Zeigt der Frame "This map isn't available — it may have been unpublished, paused, or the link is incorrect.", ist die ID falsch oder die Karte nicht live. Bei "This map isn't allowed to render on this site. Please contact the map owner." ist die Karte auf andere Domains beschränkt.

Als Nächstes: Karte einbetten erläutert Domainbeschränkungen, und Chat auf einer veröffentlichten Karte fügt einen schlüssellosen Besucherchat hinzu.

Eine Basiskarte

Sie erhalten eine Kaleidr-Basiskarte auf Ihrer Seite: eine fertige interaktive Karte, ohne Kartenbibliothek installieren oder Stile schreiben zu müssen.

1. Seite erstellen

Speichern Sie die Datei als basemap.html und ersetzen Sie kld_pk_live_… durch Ihren veröffentlichbaren Schlüssel.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

style-id bezeichnet die Basiskarte. Setzen Sie den Wert immer. kaleidr-morning ist ein allgemeiner Stil; Tile führt die anderen auf.
center verwendet longitude,latitude. Setzen Sie center immer, wenn Sie zoom angeben: zoom ohne center wird ignoriert.

2. Seite bereitstellen

Öffnen Sie http://localhost:8000/basemap.html.

Erwartetes Ergebnis:

Die 480 Pixel hohe Basiskarte mit Mittelpunkt Midtown Manhattan.
Im Netzwerk-Tab liefert eine Anfrage an https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions den Status 200, gefolgt von einem iframe, der von https://map-embed.kaleidr.com geladen wird.
Scrollen mit dem Mauszeiger über der Karte zoomt sie.

Wenn nichts erscheint und die Konsole für …/sdk/sessions einen CORS-Fehler zeigt, ist der Schlüssel falsch oder Ihre Origin nicht erlaubt, genau wie bei Chat.

Jede Tile-Sitzung zählt als ein Kartenladen gegen das monatliche Kontingent Ihrer Organisation. Siehe Kontingente und Ratenlimits.

Als Nächstes: Tile verwenden erklärt das Wechseln des Kartenstils zur Laufzeit und die Kamerasteuerung.

Was Sie geladen haben

Alle drei Varianten verwenden dieselben zwei Bausteine:

Kaleidr.mount(target, options) mountet ein Produkt über JavaScript und liefert sofort ein Handle zurück. Der Produktcode lädt im Hintergrund; zuvor ausgeführte Handle-Aufrufe werden gespeichert und nach der Bereitschaft angewendet.
<kaleidr-map> macht dasselbe in HTML. Die Attribute sind die Mount-Optionen mit Bindestrichen (share-id, style-id, publishable-key), mit zwei Ausnahmen: enabled heißt als Attribut flag, und die Chat-Option title heißt chat-title.

Verwenden Sie Kaleidr.mount für Chat auf Ihrer eigenen Karte, weil es das aktive Kartenobjekt benötigt. Für die anderen Produkte funktionieren beide Varianten.

Jedes Handle verfügt über destroy(). Andere Methoden sind produktspezifisch: setCamera funktioniert bei viewer, tile und editor, nicht jedoch bei chat. Dort bewegt der Assistent die Karte selbst, während Sie die Kameramethoden Ihrer Kartenbibliothek weiterverwenden. Die Matrix steht unter Das Element <kaleidr-map>.

Wichtige Grenzen

Chat fügt eigene Marker, Routen und Kamerabewegungen hinzu. Er verändert Ihre Ebenen oder Marker nicht, sendet sie nicht an Kaleidr und übermittelt Ihrer Seite keine Ereignisse. Siehe Funktionen und Grenzen.
Viewer und Tile laufen im iframe. Eigene Ebenen oder Marker lassen sich dort nicht hinzufügen. Falls nötig, behalten Sie Ihre Karte und binden Chat daran an.
Eine Kaleidr-Basiskarte wird mit Tile angezeigt. Das Laden von Kaleidr-Stilen oder -Kacheln in Ihrer eigenen Kartenbibliothek wird nicht unterstützt.
Der SDK ist für Webseiten. Es gibt kein npm-Paket und keinen nativen Mobile-SDK. Backends verwenden die Server-API.
Schlüsselgebundene Mounts verbrauchen Kontingent. Chat-Antworten kosten KI-Guthaben der Organisation, jede Tile-Sitzung ein Kartenladen. Siehe So funktioniert Kaleidr.

Nächster Schritt

Sie möchten	Lesen Sie
Chat an Mapbox GL JS anbinden	Chat mit Mapbox verbinden
Chat an MapLibre GL JS anbinden	Chat mit MapLibre verbinden
Chat an Google Maps anbinden	Chat mit Google Maps verbinden
Chat an Leaflet anbinden	Chat mit Leaflet verbinden
Fenster platzieren und Markenfarben anpassen	Design und Layout
Besucher auf veröffentlichter Karte chatten lassen	Chat auf veröffentlichter Karte
Veröffentlichte Karte einbetten und auf Domains beschränken	Karte einbetten
Basiskarte zeigen und Stil wechseln	Tile verwenden
Karteneditor in die Seite integrieren	Editor anbinden
SDK mit React, Next.js oder Vue verwenden	Frameworks
Kaleidr vom Backend aufrufen	Server-Schnellstart
Antworten mit eigenen Unternehmensdaten erzeugen	Ihre Daten
Produktiv gehen	Produktions-Checkliste

Vorbereitung​

Chat auf Ihrer Karte​

1. Seite erstellen​

2. Bereitstellen und Frage stellen​

3. Wenn es nicht funktioniert​

Eine veröffentlichte Karte​

1. Karte veröffentlichen und ID kopieren​

2. Seite erstellen​

3. Seite bereitstellen​

Eine Basiskarte​

1. Seite erstellen​

2. Seite bereitstellen​

Was Sie geladen haben​

Wichtige Grenzen​

Nächster Schritt​

Vorbereitung

Chat auf Ihrer Karte

1. Seite erstellen

2. Bereitstellen und Frage stellen

3. Wenn es nicht funktioniert

Eine veröffentlichte Karte

1. Karte veröffentlichen und ID kopieren

2. Seite erstellen

3. Seite bereitstellen

Eine Basiskarte

1. Seite erstellen

2. Seite bereitstellen

Was Sie geladen haben

Wichtige Grenzen

Nächster Schritt