Zum Hauptinhalt springen

Tile

Tile bindet eine Kaleidr-Basiskarte in Ihre Seite ein. Sie wählen einen Stil wie kaleidr-morning oder kaleidr-night, und das SDK zeigt die Karte in einem von Kaleidr gehosteten iframe. Ihre Seite lädt keine Kartenbibliothek.

Verwenden Sie Tile, wenn Sie eine ansprechende, interaktive Basiskarte möchten, auf der Sie selbst nichts zeichnen müssen: als Standorthintergrund, als „Hier finden Sie uns“-Fenster oder als Karte für die Antworten eines Kaleidr-Chatfensters.

Wenn Sie bereits eine eigene Mapbox-, MapLibre-, Google-Maps- oder Leaflet-Karte verwenden, benötigen Sie Tile nicht. Verbinden Sie Chat mit Ihrer vorhandenen Karte.

Auf einen Blick​

FrageAntwort
Was brauche ich?Einen veröffentlichbaren Schlüssel (kld_pk_live_…) mit der Berechtigung maps. Neue Schlüssel enthalten diese standardmäßig.
Welcher Tarif?Alle Tarife, einschließlich Free.
Wie wird die Karte dargestellt?In einem iframe von https://map-embed.kaleidr.com.
Wie wähle ich das Aussehen?Über style-id. Unten sind sechs allgemeine Stile aufgeführt.
Was kostet es?Einen Kartenaufruf pro Tile-Sitzung. Siehe Zählweise der Kartenaufrufe.
Kann die Seite die Karte steuern?Sie kann die Kamera einstellen und bewegen, den Stil wechseln und Lade- und Fehlermeldungen empfangen.

Kleinste Einbindung​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Drei Dinge sind dafür nötig:

  1. Ein Schlüssel. Erstellen Sie unter kaleidr.com/api-keys einen veröffentlichbaren Schlüssel. Siehe API-Schlüssel erstellen.
  2. Ein erlaubter Ursprung. Falls der Schlüssel erlaubte Ursprünge enthält, muss der Ursprung Ihrer Seite dazugehören. Die Seite muss über HTTP oder HTTPS bereitgestellt werden, nicht direkt von der Festplatte geöffnet.
  3. Eine Höhe. Das Element verwendet standardmäßig display:block, sodass height greift. Auch der Beispielcode setzt display:block, um Safari vor Version 16.4 abzudecken, wo das Element inline bleibt.

Stile​

style-idErscheinungsbild
kaleidr-morningHell: weißer Boden, cyanfarbenes Wasser, weiße Straßen.
kaleidr-afternoonMitteltonfarbener Boden, grüne Vegetation und graue Straßen.
kaleidr-eveningGoldene Stunde: warmer Sand und Olivtöne.
kaleidr-nightDunkles Marineblau und Anthrazit mit bernsteinfarbenen Autobahnen.
kaleidr-plainWeiße Fläche mit Grenzen und Ortsbeschriftungen. 3D-Gebäude erscheinen ab Zoomstufe 15.
kaleidr-editorialNachmittagspalette ohne Beschriftungen, für kleine oder dekorative Karten.

Geben Sie immer style-id an. Ohne diese Angabe verwendet das Embed die voreingestellte Basiskarte Ihrer Organisation, falls vorhanden; andernfalls zeigt es einen Fehler.

Funktionsweise​

  1. Das SDK sendet Ihren veröffentlichbaren Schlüssel an Kaleidr und erhält eine kurzlebige Tile-Sitzung. Dabei werden Schlüssel, Berechtigung und Seitenursprung geprüft sowie ein Kartenaufruf gezählt. Die Antwort enthält auch die voreingestellte Basiskarte der Organisation, sofern eine festgelegt ist. Die Sitzung dient nur diesem Zweck: Die Karte führt damit keine weiteren Aufrufe aus.
  2. Das SDK ersetzt den Inhalt des Elements durch ein iframe mit dem gewünschten Stil. Dessen URL enthält nur die Stil-ID und die angegebene Kamera, weder den veröffentlichbaren Schlüssel noch das Sitzungstoken.
  3. Die Karte wird im iframe gezeichnet. Die Content Security Policy Ihrer Seite muss lediglich Loader, Sitzungsanfrage und iframe zulassen.
  4. Sobald die Karte gezeichnet ist, sendet das iframe eine Nachricht kaleidr-embed:ready an Ihre Seite.

Was Besucher tun können​

Die Karte verschieben, drehen und neigen sowie über Schaltflächen, Zwei-Finger-Geste oder Mausrad zoomen. Scrollen mit dem Mauszeiger über der Karte zoomt die Karte; mit dem Mauszeiger außerhalb der Karte bewegt Scrollen die Seite.

Was Ihre Seite steuern kann​

  • Anfangskamera festlegen mit center, zoom, pitch und bearing.
  • Kamera später bewegen mit handle.setCamera(...).
  • Stil wechseln mit handle.setStyle('kaleidr-night'), ohne Neuladen.
  • Chatfenster verknüpfen. Ein Chat kann auf ein Tile-Element zeigen und seine Antworten dort markieren.
  • Ladevorgang erkennen anhand der Nachricht kaleidr-embed:ready.

Zählweise der Kartenaufrufe​

Der Tile-Verbrauch wird in Kartenaufrufen gemessen, wie bei Ansichten Ihrer veröffentlichten Karten. Jedes Mal, wenn das SDK eine Tile-Sitzung erhält, wird ein Kartenaufruf gezählt:

  • einmal beim Einbinden der Karte;
  • erneut bei jeder Sitzungserneuerung durch das SDK, kurz vor Ablauf und solange das Embed besteht. Sitzungen dauern standardmäßig 15 Minuten;
  • erneut, wenn Sie das Embed zerstören und neu einbinden oder das Element entfernen und wieder einsetzen.

Ein Besucher, der wenige Minuten auf der Seite bleibt, benötigt einen Kartenaufruf. Eine Stunde geöffnete Seite verbraucht ungefähr fünf. Es gilt also nicht „einer pro Seitenaufruf“. Entfernen Sie Tile-Instanzen, die nicht mehr angezeigt werden.

Sobald die Organisation ihre Kartenaufrufe für den Zeitraum aufgebraucht hat, werden neue Tile-Sitzungen mit HTTP 429 abgelehnt. Neue Einbindungen zeigen nichts. Bereits angezeigte Karten bleiben sichtbar. Kontingente stehen unter Kontingente und Ratenlimits.

Grenzen​

  • Tile ist eine Basiskarte. Ihre Seite kann keine eigenen Markierungen, Ebenen oder Pop-ups hinzufügen und erhält keine Klick- oder Kameraereignisse. Ein verknüpftes Chatfenster kann Orte einzeichnen.
  • Das Tile-Produkt ist der unterstützte Weg, eine Kaleidr-Basiskarte anzuzeigen.
  • Eine Änderung von style-id an einem eingebundenen Element hat keine Wirkung. Verwenden Sie handle.setStyle oder fügen Sie ein neues Element ein.
  • Es gibt keinen gesonderten Tile-Schlüssel. Ihr veröffentlichbarer Schlüssel für andere Kaleidr-Produkte funktioniert auch mit Tile.

Nächste Schritte​