Tile-Referenz

product="tile" zeigt eine Kaleidr-Grundkarte, die über eine Stil-ID ausgewählt wird. Das SDK tauscht deinen veröffentlichbaren Schlüssel gegen eine Tile-Sitzung aus und ersetzt den Inhalt des Einbindungsziels durch einen iframe, der https://map-embed.kaleidr.com/?style=<style> lädt. Die Karte wird in diesem iframe gezeichnet.

Über die Sitzung prüft Kaleidr den Schlüssel, seine Berechtigung und den Ursprung deiner Seite, zählt den Kartenaufruf und liefert die Standardgrundkarte deiner Organisation. Die Sitzung wird nicht an den iframe weitergegeben. Die iframe-URL enthält nur die Stil-ID und die angegebene Kamera (camera, pitch, bearing), weder den veröffentlichbaren Schlüssel noch das Sitzungstoken. Auch die Karte im iframe verwendet diese nicht für Aufrufe.

Schlüssel	Ein veröffentlichbarer Schlüssel (kld_pk_live_…). Erforderlich.
Berechtigung	maps. Neue Schlüssel enthalten sie standardmäßig.
Tarif	Alle Tarife, einschließlich Free.
Darstellung	In einem iframe von https://map-embed.kaleidr.com.
Abrechnung	Ein Kartenaufruf pro Tile-Sitzung.
CSP	script-src https://cdn.kaleidr.com, connect-src https://api.kaleidr.com, frame-src https://map-embed.kaleidr.com.

Eine Schritt-für-Schritt-Anleitung findest du unter Kaleidr-Grundkarte verwenden.

Einbindung

Mit dem Element:

<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="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

Aus JavaScript:

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

Optionen

Einbindungsoption	Attribut	Typ	Standard	Erforderlich	Beschreibung
product	product	'tile'	keiner	ja	Wählt Tile aus.
publishableKey	publishable-key	Zeichenfolge	keiner	ja	kld_pk_…-Schlüssel mit Berechtigung maps. Ein Serverschlüssel (kld_sk_…) wird im Browser vor jeder Anfrage abgewiesen.
styleId	style-id	Zeichenfolge	Standardgrundkarte der Organisation, falls vorhanden	empfohlen	Stil-ID aus der folgenden Tabelle oder vollständige https://-URL eines Stildokuments. Muss ^[A-Za-z0-9._:/~-]{1,200}$ entsprechen.
center	center	[longitude, latitude]; Attribut "longitude,latitude"	Standardansicht des Stils	nein	Anfänglicher Mittelpunkt.
zoom	zoom	Zahl	Standardansicht des Stils	nein	Anfänglicher Zoom; wird beim Einbinden ohne center ignoriert.
pitch	pitch	Zahl in Grad	Standardansicht des Stils	nein	Anfängliche Neigung.
bearing	bearing	Zahl in Grad	Standardansicht des Stils	nein	Anfängliche Drehung.
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	nein	Ziel des Sitzungsaustauschs. Muss /inference-api enthalten. In Produktion nicht nötig.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	nein	Ursprung des iframes; nur der Ursprung wird verwendet. Dies ist der Host der Kartenseite, nicht ihrer Daten.
base	base	URL	https://cdn.kaleidr.com	nein	Ursprung, von dem das SDK tile.js lädt. Nur die unter Base-Überschreibung aufgeführten Ursprünge sind zulässig.
enabled	flag	boolesch	keiner	nein	Einbindungsspezifische Steuerung der Aktivierungssperre.

shareId, theme, map, mapTarget, contained und tileBase wirken sich auf eine Tile-Einbindung nicht aus.

Stil-IDs

style-id	Erscheinungsbild
kaleidr-morning	Hell: weißer Untergrund, cyanfarbenes Wasser, weiße Straßen.
kaleidr-afternoon	Mittlerer Grundton mit grüner Vegetation und grauen Straßen.
kaleidr-evening	Goldene Stunde: warme Sand- und Olivtöne.
kaleidr-night	Dunkles Marineblau und Anthrazit mit bernsteinfarbenen Fernstraßen.
kaleidr-plain	Weiße Fläche mit Grenzen und Ortsnamen. 3D-Gebäude erscheinen ab Zoomstufe 15.
kaleidr-editorial	Nachmittagspalette ohne Beschriftung, für kleine oder dekorative Karten.

Regeln:

• IDs müssen exakt übereinstimmen und unterscheiden Groß- und Kleinschreibung. Kurze Aliasnamen gibt es nicht.
• Ohne styleId nutzt die Einbindung die mit der Sitzung übermittelte Standardgrundkarte der Organisation. Ist keine eingerichtet, zeigt der iframe „Couldn't find a map id in the URL.“. Gib styleId an, um nicht von einer Kontoeinstellung abhängig zu sein.
• Eine explizite styleId hat immer Vorrang vor der Organisationsvorgabe.
• Eine nicht vorhandene ID führt zu einem leeren iframe und zu kaleidr-embed:error mit dem Code maplibre_error.
• Ein unzulässiges Zeichen verhindert die Einbindung. Die Konsole zeigt [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.. Deshalb darf eine Stil-URL keine Abfragezeichenfolge enthalten.

Kamera

Die Anfangskamera basiert auf der Standardansicht des Stils. Jeder angegebene Wert überschreibt den entsprechenden Stilwert. Hat der Stil keine Standardansicht, wird die ganze Welt angezeigt: Mittelpunkt [0, 20], Zoom 2, keine Neigung oder Drehung.

• Bei center steht der Längengrad zuerst: [-0.1276, 51.5072] ist London.
• Beim Einbinden wirkt zoom nur zusammen mit center.
• pitch und bearing sind unabhängig von center.

Größe

• Der iframe ist 100 % so breit wie sein Einbindungsziel, hat keinen Rahmen und besitzt abgerundete Ecken.
• Seine Höhe entspricht 100 % des Ziels, wenn dieses beim Einbinden eine Höhe hat; andernfalls beträgt sie fest 500 Pixel.
• Die Einbindung ersetzt die Kindelemente des Ziels und setzt position:relative (wenn keine Inline-Position gesetzt ist) sowie overflow:hidden.
• <kaleidr-map> verwendet standardmäßig display:block, sodass height greift. Lege eine Höhe fest. Die Beispiele setzen zusätzlich display:block, da das Element in Safari vor Version 16.4 andernfalls inline bleibt.

Handle

Kaleidr.mount gibt das Handle synchron zurück. Die Handle-Matrix zeigt alle Produkte.

Mitglied	Bei Tile
handle.product	'tile'
handle.setCamera(camera)	Bewegt die Karte.
handle.setStyle(style)	Wechselt die Grundkarte ohne erneutes Einbinden.
handle.setTheme(theme)	Nicht unterstützt; protokolliert eine Warnung und bewirkt nichts.
handle.destroy()	Entfernt den iframe und stoppt die Sitzungserneuerungen.

setStyle(style)

handle.setStyle('kaleidr-night');

Akzeptiert eine Stil-ID oder vollständige Stil-URL, die wie styleId beim Einbinden aufgelöst wird. Der iframe wird nicht neu geladen, die Kamera bleibt stehen und es wird kein Kartenaufruf gezählt. Nur Tile unterstützt setStyle.

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // milliseconds
});

Feld	Typ	Beschreibung
center	[number, number]	Längengrad, Breitengrad.
zoom	Zahl	Zoomstufe. Anders als beim Einbinden funktioniert zoom hier ohne center.
pitch	Zahl	Neigung in Grad.
bearing	Zahl	Drehung in Grad.
duration	Zahl	Animationsdauer in Millisekunden. Ohne Angabe oder mit 0 erfolgt der Sprung sofort.

Alle Felder sind optional. Ausgelassene Felder behalten ihren aktuellen Wert.

Zeitpunkt

setCamera und setStyle können jederzeit nach der Rückgabe von Kaleidr.mount aufgerufen werden, auch direkt in der nächsten Zeile. Aufrufe vor der Bereitschaft der Karte im iframe werden zwischengespeichert und in ihrer Reihenfolge ausgeführt, sobald die Karte bereit ist. Die letzten 256 Aufrufe bleiben gespeichert. Meldet die Karte ihre Bereitschaft auch nach einer begrenzten Wartezeit nicht, normalerweise 10 Sekunden nach dem Laden des iframes, werden die Aufrufe dennoch gesendet und es erscheint eine Konsolenwarnung. Du musst nicht auf kaleidr-embed:ready warten. Für die anfängliche Ansicht und den Stil sind Einbindungsoptionen direkter: Die Karte öffnet sich bereits damit.

Elementattribute nach dem Einbinden

Bei einem eingebundenen <kaleidr-map product="tile"> bewegen Änderungen an center, zoom, pitch oder bearing die Karte ohne Animation. Änderungen an style-id, publishable-key oder anderen Attributen bewirken nichts.

Nachrichten aus dem iframe

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id bezeichnet die angegebene Stil-ID oder URL. Bei no_id ist der Wert null, der iframe zeigt „Couldn't find a map id in the URL.“ und sendet kein ready.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

• ready wird einmal gesendet, sobald die Karte gezeichnet wurde, nicht nochmals nach setStyle.
• maplibre_error kann mehrfach vor oder nach ready auftreten.
• Der iframe hat loading="lazy"; Nachrichten kommen daher erst, wenn er sich dem sichtbaren Bereich nähert.
• Eine abgewiesene Sitzung erzeugt keine Nachricht, da kein iframe erstellt wird. Prüfe die Konsole.
• Der iframe sendet weitere Nachrichten, deren type mit kaleidr-embed: beginnt. Das SDK verwendet sie zur Verbindung von Chat und Karte; sie gehören nicht zum öffentlichen Vertrag.

Sitzung und Nutzungszählung

Bei jeder Tile-Einbindung sendet das SDK

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

und erhält

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id bezeichnet die Standardgrundkarte deiner Organisation; ohne Vorgabe ist der Wert null.

Jeder erfolgreiche Austausch mit "product":"tile" zählt einen Kartenaufruf für deine Organisation. Ein Austausch erfolgt:

Zeitpunkt	Zählung
Beim Einbinden	1
90 Sekunden vor Sitzungsablauf, solange die Einbindung besteht	jedes Mal 1
Wenn der Tab wieder sichtbar wird und die Sitzung innerhalb von 90 Sekunden abläuft oder bereits abgelaufen ist	1
Bei erneuter Einbindung nach destroy() oder erneutem Einfügen eines entfernten Elements	1

Hinweise:

• Eine fehlgeschlagene Erneuerung wird alle 30 Sekunden wiederholt. Eine bereits sichtbare Karte bleibt bestehen.
• Schlägt der erste Austausch fehl, misslingt die Einbindung ohne automatischen Wiederholungsversuch. Binde erneut ein.
• destroy() stoppt die Erneuerungen.
• Kamerabewegungen, Stilwechsel und Interaktionen der Besucher werden nicht gezählt.

Ein Tile-Sitzungsaustausch wird aufgrund des ersten zutreffenden Grundes verweigert:

Status	detail	Ursache
403	publishable_key_required	Der Schlüssel ist nicht veröffentlichbar.
403	origin_required	Die Anfrage hatte keinen Ursprung.
403	origin_not_allowed	Der Seitenursprung steht nicht auf der Liste erlaubter Ursprünge.
403	product_not_allowed	Der Schlüssel ist auf andere Produkte beschränkt.
403	tier_capability_not_allowed	Der Tarif erlaubt das Produkt nicht.
403	insufficient_scope	Dem Schlüssel fehlt die Berechtigung maps.
429	map_load_quota_exceeded	Das Kartenaufrufkontingent der Organisation ist erschöpft.

Noch vor diesen Prüfungen antwortet der Austausch mit 404 sessions_disabled, wenn er plattformweit deaktiviert ist, oder mit 503 sessions_not_configured bei einem Plattformfehler. Beides liegt nicht am Schlüssel. Alle Codes stehen unter Fehler.

Mit Chat verbinden

Eine Chat-Einbindung kann ein Tile-Element steuern. Gib dem Tile-Element eine ID und verweise im Chat-Attribut map-target (Option mapTarget) darauf:

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

Auf Tile-Karten setzt der Assistent Pins mit Pop-ups, richtet die Kamera auf Orte aus und zeichnet Routen, Gebietsumrisse etwa einer Stadt sowie Live-Fahrzeugpositionen. Die Anleitung steht unter Kaleidr-Grundkarte verwenden, das Layout unter Design und Anordnung und die Chat-Optionen unter Chat-Referenz.

Konsolenmeldungen

Nachricht	Bedeutung
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	Das Element hat kein gültiges product; es wird nicht eingebunden.
[kaleidr:tile] kaleidr session exchange failed (<status>)	Austausch verweigert. Die Ursache steht in der Antwort im Netzwerk-Tab: detail bei 403 und map_load_quota_exceeded, error bei 429 rate_limited.
CORS-Fehler für …/sdk/sessions, danach ein [kaleidr:tile]-Abruffehler	Unbekannter oder widerrufener Schlüssel oder nicht zugelassener Ursprung. Ohne CORS-Header verbirgt der Browser die Ablehnungsantwort vor dem SDK.
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	Ein Serverschlüssel wurde übergeben; es erfolgt keine Anfrage.
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId enthält ein unzulässiges Zeichen.
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount fand für den Selektor kein Element.
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	Das Tile-Bundle konnte nicht geladen werden.
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	Du hast eine von Tile nicht unterstützte Handle-Methode aufgerufen.
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	Die Seite nutzt ein altes zwischengespeichertes tile.js. Ohne Cache neu laden.

Nicht verfügbar

• Eigene Marker, Ebenen oder Pop-ups hinzufügen.
• Ereignisse für Klicks, Kamerabewegungen oder Auswahlen.
• Die Kameraposition auslesen.
• Die Karte ohne iframe verwenden.

Verwandte Themen

• Kaleidr-Grundkarte verwenden
• Das Element <kaleidr-map>
• Der Loader kaleidr.js
• Kontingente und Ratenbegrenzung