Karteneditor einbinden

Am Ende dieser Anleitung zeigt Ihre Seite Kaleidrs Kartenbearbeitungswerkzeuge auf einer Kaleidr-Basiskarte, angepasst an Ihre Marke. Das funktioniert mit jedem Tarif, auch Free. Sie benötigen einen veröffentlichbaren Schlüssel mit dem Berechtigungsumfang design, der bei neuen Schlüsseln standardmäßig enthalten ist.

Änderungen werden nicht gespeichert

Der eingebettete Editor hält seine Arbeit nur im Arbeitsspeicher der Seite. Aus dem Embed wird nichts gespeichert, exportiert oder veröffentlicht; Ihre Seite erhält bei Änderungen keinen Callback. Beim Neuladen oder durch handle.destroy() gehen die Änderungen verloren. Für dauerhaft gespeicherte Karten erstellen Sie diese in Kaleidr Studio und betten sie mit Viewer ein.

Voraussetzungen

Ein veröffentlichbarer Schlüssel (kld_pk_live_…) von kaleidr.com/api-keys. Siehe API-Schlüssel erstellen.
Der Origin Ihrer Testseite, beispielsweise http://localhost:3000, steht auf der Liste zulässiger Origins des Schlüssels. Ohne Einschränkung ist der Schlüssel auf jeder Website nutzbar.
Ein HTTP-Server für die Seite, beispielsweise npx serve ..
Falls Ihre Website eine Content Security Policy verwendet, die Editor-Direktiven aus Content Security Policy. Der Editor läuft auf Ihrer Seite und benötigt deshalb Einträge für connect-src, img-src, worker-src, font-src und style-src, die iframe-Produkte nicht brauchen.
Kein zweiter Kaleidr-Editor auf derselben Seite.

Schritt 1: Container dimensionieren und Editor einbinden

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

Erwartetes Ergebnis: Eine Kaleidr-Basiskarte in Weltansicht füllt den Container (kaleidr-morning, sofern Ihre Organisation keinen anderen Standard festgelegt hat), mit der Schaltfläche Create auf der Karte. Über Create öffnen Sie die Editor-Seitenleiste mit Text-, Bild-, Marker- und Popup-Werkzeugen.

Der Container benötigt eine feste Höhe. Der Editor nimmt 100 % seiner Breite und Höhe ein; alle Bedienfelder bleiben innerhalb des Containers.

Sie können auch das Element verwenden. Standardmäßig gilt display:block, sodass die Höhe greift. Das Beispiel setzt display:block zusätzlich für Safari vor Version 16.4:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

Schritt 2: Basiskarte und Startkamera wählen

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

Erwartetes Ergebnis: Die dunkle Basiskarte zeigt das Zentrum Londons, geneigt und gedreht.

So wird die Basiskarte ausgewählt:

styleId, wenn Sie diese Option übergeben. Möglich sind etwa kaleidr-morning, kaleidr-afternoon, kaleidr-evening, kaleidr-night, kaleidr-plain oder kaleidr-editorial. Beschreibungen stehen in der Tile-Referenz.
Ansonsten die Standard-Basiskarte Ihrer Organisation, sofern festgelegt.
Andernfalls kaleidr-morning.

Die Kamera startet mit Mittelpunkt [0, 0], Zoom 2, Neigung 0 und Ausrichtung 0. Anders als Viewer und Tile akzeptiert der Editor zoom ohne center.

Eine an Kaleidr.mount übergebene Kameraoption ohne endliche Zahl wird ignoriert und in der Konsole gemeldet. Ein nichtnumerisches Kameraattribut des Elements wird ohne Meldung verworfen.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

Schritt 3: Bedienfelder gestalten (optional)

Übergeben Sie theme, damit die Editor-Bedienfelder zu Ihrem Produkt passen. Das Objekt akzeptiert bis zu 17 benannte Schlüssel; andere Schlüssel werden ignoriert.

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

Erwartetes Ergebnis: Aktives Werkzeug, Fokusringe und primäre Schaltflächen verwenden Ihre Markenfarbe, die Bedienfelder Ihre Schriftart.

Alle 17 Schlüssel stehen in der Editor-Referenz.

Drei wichtige Hinweise:

Die Werte sind CSS-Werte. brandColor akzeptiert jede CSS-Farbe, cardRadius jede CSS-Länge und fontPrimary jeden font-family-Wert. Laden Sie die Schrift selbst.
Das Theme gilt während der Editor-Einbindung für das gesamte Dokument und wird beim Entfernen wiederhergestellt. Eigene Stile bleiben unverändert, außer sie nutzen dieselben benutzerdefinierten Eigenschaften.
Das Theme wird ausschließlich beim Einbinden gelesen. handle.setTheme wird beim Editor nicht unterstützt. Um es zu ändern, entfernen Sie den Editor und binden ihn erneut ein; dabei gehen die Änderungen verloren.

Beim Element ist theme eine JSON-Zeichenfolge:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

Schritt 4: Kamera von Ihrer Seite bewegen (optional)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

Erwartetes Ergebnis: Die Karte fliegt nach Paris. Alle vom Benutzer platzierten Elemente bleiben an ihrem jeweiligen Ort.

Mit setCamera kann Ihre Seite ausschließlich die Editor-Kamera steuern. Das Handle stellt das Kartenobjekt nicht bereit.

Schritt 5: Editor entfernen

handle.destroy();

destroy() entfernt Editor, Karte und Bedienfelder aus dem Container und stellt die Theme-Werte wieder her. Änderungen werden verworfen.

Rufen Sie in einer Single-Page-App destroy() auf, sobald die Route oder Komponente, die den Editor enthält, entfernt wird. Beim Element hat das Entfernen aus dem Dokument dieselbe Wirkung. Siehe Framework-Integration.

Da höchstens ein Editor je Seite existieren kann, entfernen Sie den aktuellen immer, bevor Sie einen weiteren einbinden.

Vollständige Beispielseite

Speichern Sie die Datei als index.html, tragen Sie Ihren Schlüssel ein und stellen Sie den Ordner per HTTP von einem zugelassenen Origin bereit.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

Verhalten

Thema	Verhalten
Ausführungsort	Im Dokument. Karten-Canvas und Editor-Bedienfelder sind Elemente innerhalb des Einbindungsziels.
Sitzung	Das SDK tauscht den Schlüssel gegen eine kurzlebige Sitzung aus, bevor der Editor startet, und verlängert diese während der Einbindung.
Änderungen	Nur im Speicher; nicht gespeichert, exportiert, veröffentlicht oder an Ihre Seite gemeldet.
Basiskarte	Wird von der Seite über `https://tile.kaleidr.com` geladen und beim Einbinden festgelegt.
Theme	Gilt beim Einbinden dokumentweit und wird durch destroy() zurückgesetzt.
Kamera	Beim Einbinden festgelegt, später durch `handle.setCamera` bewegbar.
Nutzung	Die Editor-Sitzungsanfrage zählt nicht als Kartenladung; der eingebettete Editor enthält keine KI-Funktionen, die Credits verbrauchen. Die mit Ihrem Schlüssel ausgeführten Basiskartenanfragen zählen gebündelt als Kartenaufrufe: jeweils 20 Anfragen innerhalb einer Stunde ergeben einen Kartenaufruf. Siehe Kartenaufrufe.
Signale	Keine: kein Bereitschafts-, Änderungs- oder Fehlercallback.

Informieren Sie Ihre Benutzer

Der Editor selbst warnt nicht, dass die Arbeit nur vorübergehend gespeichert wird. Wenn Benutzer länger darin arbeiten, weisen Sie in Ihrer Oberfläche darauf hin, wie in der vollständigen Beispielseite, damit niemand mit einer später wieder auffindbaren Karte rechnet.

Funktion prüfen

Auf der Seite: Die Basiskarte füllt den Container, Create öffnet die Seitenleiste und Sie können Text oder Marker setzen.
In der Konsole: Keine Zeile enthält [kaleidr.
Im Netzwerk-Tab: kaleidr.js und editor.js von https://cdn.kaleidr.com, eine POST …/sdk/sessions-Anfrage mit Status 200 sowie Anfragen an https://tile.kaleidr.com für Stil und Kacheln.

Fehlerbehebung

Das SDK protokolliert fehlgeschlagene Einbindungen als [kaleidr:editor] … in der Konsole. Bei verweigerten Sitzungen erscheint nur der HTTP-Status; den Grund finden Sie in der Antwort der sessions-Anfrage im Netzwerk-Tab. Bei 403 steht der Code in detail, bei 429 in error und eine Erläuterung in detail.

Symptom	Ursache	Lösung
Nichts erscheint. Konsole: `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	Kein Schlüssel übergeben.	`publishableKey` übergeben.
Nichts erscheint. CORS-Fehler für `…/sdk/sessions` und `[kaleidr:editor]`-Abruffehler.	Schlüssel unbekannt oder widerrufen, oder der Origin ist nicht zugelassen.	Schlüssel prüfen. Genauen Origin einschließlich Schema, Host und Port unter kaleidr.com/api-keys zulassen; die Änderung kann einige Minuten benötigen.
Konsole: `[kaleidr:editor] kaleidr session exchange failed (403)`	Der Schlüssel hat keinen `design`-Scope (`insufficient_scope`), ist auf andere Produkte eingeschränkt (`product_not_allowed`) oder der Tarif erlaubt die Anfrage nicht (`tier_capability_not_allowed`).	`detail` im Netzwerk-Tab prüfen und einen Schlüssel mit Standard-Scopes erstellen.
Konsole: `[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Sie haben einen Serverschlüssel übergeben.	Veröffentlichbaren Schlüssel verwenden. Serverschlüssel ersetzen, wenn die Seite öffentlich war.
Container bleibt leer und hat keine Höhe.	Einbindungsziel hat keine Höhe.	Höhe setzen; bei Safari vor 16.4 zusätzlich `display:block`.
Bedienfelder erscheinen, Karte bleibt leer; Status 429 von `https://tile.kaleidr.com` mit `"error":"tile_access_restricted"`.	Der Basiskartenserver verweigert den Zugriff.	Gültigen veröffentlichbaren Schlüssel und erlaubten Origin prüfen, nach Erstellung oder Änderung kurz warten und neu laden; ggf. Support kontaktieren. `[kaleidr:editor] …`
Bedienfelder erscheinen, die Karte bleibt leer und CSP-Fehler stehen in der Konsole.	Die Richtlinie blockiert Basiskarte, Karten-Worker oder Bilder.	Editor-Direktiven aus Content Security Policy ergänzen.
Editor hat kein Styling.	CSP blockiert Inline-Stile.	`'unsafe-inline'` in `style-src` zulassen.
Zweiter Editor verhält sich fehlerhaft oder der erste stoppt.	Zwei Editoren gleichzeitig eingebunden.	Den ersten vor dem zweiten entfernen.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	Theme wird nur beim Einbinden gelesen.	`theme` beim Einbinden übergeben.
`[kaleidr] theme string must be JSON…`	Das `theme`-Attribut enthält kein JSON-Objekt.	Attribut in einfache und die JSON-Schlüssel in doppelte Anführungszeichen einschließen.
Theme-Schlüssel ohne Wirkung.	Schlüssel unbekannt oder falsch geschrieben; unbekannte werden ignoriert.	Mit der Liste abgleichen.
Änderungen verschwunden.	Seite neu geladen, Editor zerstört oder Element verschoben/entfernt.	Erwartetes Verhalten; siehe Hinweis oben.

Einschränkungen

Im Embed wird nichts gespeichert, exportiert oder veröffentlicht.
Kein Änderungs-, Bereitschafts- oder Fehlercallback.
Kein Zugriff auf das Kartenobjekt, deshalb keine eigenen Ebenen und kein Auslesen von Zeichnungen.
Kein Daten-Tab, Designkatalog, KI-Panel, 3D-Modellbibliothek, Teilen oder Projekte. Die Werkzeugleiste umfasst Text, Image, Marker, Popup, Background, Layer, Design und Legend; siehe Umfang.
Nur ein Editor pro Seite.
Basiskarte und Theme lassen sich nach dem Einbinden nicht ändern.

Nächste Schritte

Editor-Referenz: sämtliche Optionen und Theme-Schlüssel.
Framework-Integration: Editor mit React, Next.js oder Vue einbinden und entfernen.
Content Security Policy: Editor-Direktiven.
Veröffentlichte Karte einbetten: für dauerhafte Karten.

Voraussetzungen​

Schritt 1: Container dimensionieren und Editor einbinden​

Schritt 2: Basiskarte und Startkamera wählen​

Schritt 3: Bedienfelder gestalten (optional)​

Schritt 4: Kamera von Ihrer Seite bewegen (optional)​

Schritt 5: Editor entfernen​

Vollständige Beispielseite​

Verhalten​

Informieren Sie Ihre Benutzer​

Funktion prüfen​

Fehlerbehebung​

Einschränkungen​

Nächste Schritte​