Viewer-Referenz

product="viewer" zeigt eine in Kaleidr Studio veröffentlichte Karte. Das SDK ersetzt den Inhalt des Einbindungsziels durch einen iframe, der https://map-embed.kaleidr.com/embed/<id> lädt. Die Karte wird innerhalb dieses iframes gezeichnet.

Schlüssel	Keiner. Übergib keinen Schlüssel.
Tarif	Alle Tarife, auch Free.
Darstellung	In einem iframe von https://map-embed.kaleidr.com.
Abrechnung	Ein Kartenaufruf pro Ansicht, zulasten der Organisation des Karteninhabers.
CSP	script-src https://cdn.kaleidr.com und frame-src https://map-embed.kaleidr.com.

Eine Anleitung findest du unter Veröffentlichte Karte einbetten.

Einbindung

Mit dem Element:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

Aus JavaScript:

const handle = Kaleidr.mount('#map', {
  product: 'viewer',
  shareId: 'YOUR_MAP_ID',
});

Ganz ohne SDK:

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

Chatleiste

layout="bar" macht den Viewer zu einer Chatleiste: ein einzelnes Fragefeld für deine Seite, ohne Karte, bis ein Besucher fragt. Eine Frage öffnet die veröffentlichte Karte, und die Kaleidr AI der Karte beantwortet sie dort.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
             chat-title="Ask about the neighborhood"
             prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>

Antworten öffnen sich an einem von zwei Orten:

Einstellung	Was eine Frage bewirkt
Kein results-url (Standard)	Die Karte öffnet sich fensterfüllend über der Seite und stellt die Frage. Besucher schließen sie mit der Schließen-Schaltfläche. Eine spätere Frage geht an dieselbe Karte, sodass das Gespräch weitergeht.
results-url="/map"	Der Browser wechselt mit ?q=<question> zu dieser Seite. Ein Viewer dort mit prompt-param="q" stellt die Frage, wenn sich die Karte öffnet, sofern der Besucher von einer Seite desselben Ursprungs kam.

Eine Ergebnisseite:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
             style="display:block; height:600px"></kaleidr-map>

• Die Karte antwortet. Die Frage geht an das eigene Ask-Kaleidr-Panel der Karte. Daher muss Control Tower für die Karte aktiviert sein (Studio, Kaleidr AI), und es gelten die Regeln von Kaleidr AI auf einer veröffentlichten Karte: Der Inhaber bezahlt, und die erlaubten Domains der Karte bestimmen, wo sie antwortet. Bei einer Karte ohne Control Tower öffnet sich die Karte, die Frage wird aber nicht gestellt.
• Die Leiste lädt keine Karte. Die Karte wird erst geladen, wenn ein Besucher fragt, und zählt dann als Kartenaufruf.
• Die Leiste zeichnet sich in einem eigenen Shadow Root, sodass das CSS deiner Seite sie nicht umgestaltet und ihre Stile keine style-src-Berechtigung brauchen. Sie ist so breit wie das Element und so hoch wie ihr Inhalt.
• Ihre eigenen Beschriftungen folgen lang, oder der Browsersprache des Besuchers, wenn lang nicht gesetzt ist: Englisch, Spanisch, Französisch, Deutsch, Portugiesisch, Japanisch, Koreanisch, vereinfachtes und traditionelles Chinesisch sowie Arabisch. Dein chat-title, placeholder und prompts werden so angezeigt, wie du sie schreibst.
• prompt füllt das Feld vor, und handle.send() fragt aus Code. handle.send('Parks nearby') stellt diese Frage; handle.send() stellt die Frage, die im Feld steht.

Der Builder auf template.kaleidr.com schreibt beide Snippets für eine Karte deiner Wahl.

Orts-Layouts

layout="locator" und layout="listings" zeigen die veröffentlichte Karte neben einer Liste einer Sammlung aus der Ortsbibliothek, die die Karte zeichnet, mit den Filtern und Ortskarten der Sammlung.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
             filters="search|category|open_now"
             style="display:block; height:600px"></kaleidr-map>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
             filters="price|beds|baths"
             style="display:block; height:720px"></kaleidr-map>

Layout	Die Liste	Die Pins
locator	Orte nach Entfernung sortiert, mit einem Suchfeld, einer Schaltfläche In meiner Nähe, den Filtern und einer Anzahl. Eine Suche, die keinen Ort der Liste trifft, bewegt die Karte zum gesuchten Ort.	Die Ebene der Sammlung, wie in Studio gestaltet.
listings	Fotokarten, in einem breiten Rahmen zweispaltig, sortiert nach Entfernung, Preis: aufsteigend oder Preis: absteigend.	Preisschilder.

• Die Liste steht neben der Karte, wenn der Rahmen mindestens 768 Pixel breit ist, darunter als Blatt über der Karte, das der Besucher nach oben zieht.
• Liste und Karte bleiben synchron. Wer einen Ort in der Liste auswählt, bewegt die Karte dorthin und öffnet seine Karte; wer einen Pin auswählt, scrollt die Liste zu ihm. Liste, Pins und Anzahl zeigen immer dieselben Orte.
• Die Liste zeigt 50 Orte auf einmal, mit Mehr anzeigen.
• In meiner Nähe fragt den Besucher nach seinem Standort. Das iframe, das das SDK erstellt, erlaubt das; ein direktes iframe braucht allow="geolocation".
• Auf einer Karte ohne Sammlung zeigen beide Layouts nur die Karte.

filters wählt aus, welche der eigenen Besucherfilter der Sammlung angezeigt werden, getrennt durch |. Sie erscheinen in der Reihenfolge der Sammlung, egal in welcher Reihenfolge du sie schreibst, und ein Filter, den die Sammlung nicht anbietet, wird ignoriert. Ohne filters zeigt das Layout alle Filter der Sammlung.

Filter	Zeigt	Trifft
search	Ein Textfeld	Orte, deren Name, Adresse oder Kategorie den Text enthält.
category	Kategorie-Schaltflächen, bis zu den 30 häufigsten	Orte in einer der ausgewählten Kategorien.
price	Minimum und Maximum	Orte mit einem Preis in diesem Bereich. Ein Ort ohne Preis wird ausgeblendet, sobald der Bereich eingeschränkt ist.
beds, baths	Beliebig, 1+, 2+, 3+, 4+	Orte mit mindestens so vielen.
open_now	Ein Schalter	Orte, die gerade geöffnet sind, in ihrer eigenen Zeitzone. Orte ohne Öffnungszeiten sind ausgeblendet, solange er an ist.

Alle Filter, die ein Besucher setzt, gelten zusammen.

card legt fest, wie viel die Karte eines Ortes zeigt. auto, der Standard, ist die in Studio gestaltete Karte. compact zeigt nur Titel, Untertitel und Aktionen, für einen kleinen Rahmen.

Ortsaktionen funktionieren so, wie die Sammlung sie festlegt. Route zeichnet die Route in der Karte und bietet Apple Maps und Google Maps an; ein Link öffnet sich in einem neuen Tab; Anrufen öffnet einen Telefonlink; eine Anfrageaktion wie Schedule a Tour öffnet das Anfrageformular des Unternehmens über der Karte.

Guide-Layout

layout="guide" öffnet eine Karte mit Locations und daneben ihr Ask-Kaleidr-Panel: den Viertelführer eines Hotels oder die Umgebungskarte einer Location. Es listet eine Sammlung vom Typ Locations (collection, sonst die erste Locations-Sammlung, die die Karte zeichnet) und braucht aktiviertes Control Tower. Auf einer Karte, die keine Locations-Sammlung zeichnet, zeigt das Layout nur die Karte.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
             style="display:block; height:640px"></kaleidr-map>

• Der Chat steht an erster Stelle. In einem Rahmen ab 769 Pixel Breite ist das Panel 400 Pixel breit, links neben der Karte. Schmaler ist es ein Blatt über der Karte auf 45 % ihrer Höhe, das der Besucher bis auf 85 % hochzieht. Der Hinweis, dass Antworten von KI erzeugt werden, bleibt unter dem Feld.
• Kategorie-Chips über dem Feld sind die acht häufigsten Kategorien der Sammlung. Ein Chip zeigt die Pins dieser Kategorie und fragt „Zeig mir Kategorie in der Nähe von Ankerpunkt“ in der Sprache des Besuchers. Plan My Day fragt „Plane meinen Tag rund um Ankerpunkt“.
• Der Ankerpunkt ist der Ankerpunkt der Karte, festgelegt in den Karteneinstellungen in Studio: ein Ort einer Sammlung, die die Karte zeichnet, oder ein auf die Karte gesetzter Punkt, etwa dein Hotel. Er wird als eigener Pin mit seinem Namen gezeichnet, und „in der Nähe“ bedeutet im Guide: in seiner Nähe. Eine Karte ohne Ankerpunkt nimmt ihre Mitte.
• Der Tagesplan. Gebeten, einen Tag zu planen, zeichnet der Guide eine Route, die am Ankerpunkt beginnt und zuerst Orte aus deinen eigenen Sammlungen und danach Kaleidrs eigene Ortsdaten besucht, und zeigt sie als Karte mit benannten Stationen und ihren Uhrzeiten, in der Sprache des Besuchers.
• Location-Karten zeigen die in Studio gestaltete Ortskarte, mit Staff Pick bei den Orten, die du markierst, und darunter die Karten deiner Verbindungen. Verbundene Inhalte erscheinen nur auf Karten, nie in den Antworten des Guides.
• Anfragen. Die Aktion Reserve einer Location öffnet das Anfrageformular des Unternehmens.

Der Guide im Chat-Stream

Der Viewer teilt der Kaleidr AI der Karte mit, welches Layout er zeigt. Ein Client von POST /chat/control/stream sieht zwei Felder, die zum Guide gehören:

Feld	Wo	Form
layout	Der Anfrage-Body	"guide", solange ein Guide-Layout gezeigt wird; sonst weggelassen, was eine gewöhnliche Karten-Runde ist. Höchstens 16 Zeichen, sonst wird die Anfrage mit 422 invalid_layout abgelehnt.
itinerary	Ein Ereignis des Streams, wiederholt im Ereignis end	{ title, stops: [{ name, time?, note? }] }: der Titel des Tagesplans und 1 bis 12 benannte Stationen, bereits in der Sprache des Besuchers. Eine note erscheint nur bei deinen eigenen Orten.

Ein Client, der keine Tagespläne zeigt, kann das Ereignis ignorieren.

Live-Layout

layout="live" zeigt, wo deine Fahrzeuge gerade sind und wo sie heute halten: die Route eines Foodtrucks, ein Shuttle, ein mobiler Service. Es liest zwei Sammlungen: eine Sammlung vom Typ Fahrzeuge, deren Positionen aus dem Live-Tracking stammen, und eine Sammlung vom Typ Haltestellen mit dem Fahrplan.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
             collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
             style="display:block; height:640px"></kaleidr-map>

Option	Standard	Liest
collection	Die erste Fahrzeuge-Sammlung, die die Karte zeichnet	Die live gezeigten Fahrzeuge.
stops	Die erste Haltestellen-Sammlung, die die Karte zeichnet	Die Haltestellen und ihre Servicezeiten.

Auf einer Karte, die keine der beiden zeichnet, zeigt das Layout nur die Karte. Das Panel steht in einem Rahmen ab 769 Pixel Breite neben der Karte, darunter ist es ein Blatt über der Karte.

• Eine Live-Plakette steht oben im Panel, oder Derzeit nicht unterwegs, wenn kein Fahrzeug im Dienst ist.
• Eine Zeile pro gezeigtem Fahrzeug: sein Name; Unterwegs, Steht, An und die Haltestelle, oder Zuletzt gesehen vor 5 Min., sobald seine letzte Meldung älter ist als Als Veraltet Markieren Nach der Flotte; und Nächste Haltestelle mit Etwa 12 Min. und dem Hinweis Schätzung.
• Heutige Route: die heutigen Haltestellen in der Reihenfolge ihrer Zeitfenster, jede mit ihrem Zeitfenster, dem Fahrzeug, das sie bedient, und einem Badge.
• Wie lange bis zu mir? fragt nach dem Standort des Besuchers oder nimmt, wenn er ablehnt, eine ungefähre Position seiner Stadt, und zeigt, wie lange die gezeigten Fahrzeuge bis zu ihm bräuchten. Der Standort dient nur dieser Schätzung und wird nie gespeichert.
• Ein ausgewähltes Fahrzeug wird verfolgt, bis der Besucher die Karte bewegt. Eine ausgewählte Haltestelle öffnet ihre Ortskarte mit den heutigen Zeitfenstern oder dem nächsten Servicedatum.

Badge	Wann
Jetzt hier	Das Fahrzeug hat sich an der Haltestelle angemeldet.
Heute geschlossen	Der Fahrer hat das Fahrzeug für heute als geschlossen markiert.
Jetzt geöffnet	Ein Zeitfenster der Haltestelle umfasst diesen Moment.
Als Nächstes: 11:00–14:00	Die Haltestelle hat heute ein späteres Zeitfenster.
Heute nicht	Die Haltestelle hat heute kein Zeitfenster. Ihre Ortskarte nennt das nächste Servicedatum innerhalb von 14 Tagen.

Was der Besucher sieht, bewegt sich flüssig und rät nie. Ein Fahrzeug gleitet von einer gemeldeten Position zur nächsten und läuft seiner letzten Meldung nie voraus. Positionen werden alle 10 Sekunden aktualisiert, sofern der Autor der Karte kein anderes Intervall gewählt hat (5 bis 60 Sekunden), und pausieren, solange die Seite verborgen ist. Die heutigen Status und die Schätzungen werden jede Minute aktualisiert. Eine fehlgeschlagene Aktualisierung behält das letzte Bild.

Nur Fahrzeuge im Dienst werden gezeigt, so genau, wie es die öffentliche Genauigkeit der Flotte erlaubt. Ein Fahrzeug, dessen Schicht endet, ist bei der nächsten Aktualisierung verschwunden.

Jede Zeit ist eine Schätzung. Sie wird aus der Straßenentfernung und üblichen Geschwindigkeiten berechnet; Verkehr ist nicht berücksichtigt. Sie wird auf die Minute aufgerundet und als Etwa 12 Min. oder Etwa 1 Std. 20 Min. gezeigt, nie als Ankunftszeit. Gibt es keine Straßenroute zwischen beiden, steht in der Zeile Keine Schätzung. Straßenrouten werden aus OpenStreetMap-Daten erstellt, © OpenStreetMap-Mitwirkende, unter der ODbL.

Request Pickup ist die Anfrageaktion der Haltestellen-Sammlung. Hat ihr Autor Besucher Abholort und Ziel wählen lassen aktiviert, legt der Besucher zuerst einen Abholort fest, die Haltestelle selbst, sofern er ihn nicht ändert, und ein Ziel, jeweils per Adresssuche oder Tippen auf die Karte, und füllt dann das Anfrageformular aus. Beide Punkte gehen mit der Anfrage mit.

Die Beschriftungen des Panels folgen der Sprache des Viewers, in denselben zehn Sprachen wie die Chatleiste.

Optionen

Einbindungsoption	Attribut	Typ	Standard	Erforderlich	Beschreibung
product	product	'viewer'	keiner	ja	Wählt Viewer aus.
shareId	share-id	Zeichenfolge	keiner	ja	ID der veröffentlichten Karte aus dem Studio-Einbettungscode. Muss ^[A-Za-z0-9._~-]{1,100}$ entsprechen.
mapId	map-id	Zeichenfolge	keiner	nein	Alias von shareId, wenn shareId fehlt.
center	center	[longitude, latitude]; Attribut "longitude,latitude"	gespeicherte Ansicht	nein	Anfänglicher Mittelpunkt.
zoom	zoom	Zahl	gespeicherte Ansicht	nein	Anfänglicher Zoom, wird beim Einbinden ohne center ignoriert.
pitch	pitch	Zahl in Grad	gespeicherte Ansicht	nein	Anfängliche Neigung.
bearing	bearing	Zahl in Grad	gespeicherte Ansicht	nein	Anfängliche Drehung.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	nein	Ursprung, von dem der iframe geladen wird. Nur der Ursprung zählt. In Produktion unnötig.
base	base	URL	https://cdn.kaleidr.com	nein	Ursprung, von dem das SDK viewer.js lädt. Es wird nur der Ursprung verwendet und nur die in Base-Überschreibung genannten werden akzeptiert.
enabled	flag	boolesch	keiner	nein	Einbindungsspezifische Aktivierungssperre.
prompt	prompt	Zeichenfolge	keiner	nein	Eine Frage, die der Kaleidr AI der Karte beim Öffnen der Karte gestellt wird. Bei einer Chatleiste der vorausgefüllte Text des Felds. Höchstens 500 Zeichen.
promptParam	prompt-param	Zeichenfolge	keiner	nein	Liest prompt aus diesem Abfrageparameter der eigenen URL der Seite: q auf der Ergebnisseite einer Chatleiste. Wird nur gelesen, wenn der Besucher von einer Seite desselben Ursprungs kam, sodass ein Link von anderswo Ihre Karte nichts fragen lassen kann.
layout	layout	'map', 'bar', 'locator', 'listings', 'guide' oder 'live'	'map'	nein	bar bindet die Chatleiste ein. locator und listings zeigen die Karte neben einer Liste einer Sammlung: siehe Orts-Layouts. guide öffnet den Chat neben einer Karte mit Locations: siehe Guide-Layout. live zeigt Fahrzeuge und die heutigen Haltestellen: siehe Live-Layout.
collection	collection	string	die erste Sammlung vom Typ des Layouts, die die Karte zeichnet	nein	Filialfinder, Angebotsliste und Guide: die ID der Sammlung, die aufgelistet wird. Live: die ID der Fahrzeuge-Sammlung.
stops	stops	string	die erste Haltestellen-Sammlung, die die Karte zeichnet	nein	Live: die ID der Haltestellen-Sammlung.
filters	filters	Array von Zeichenfolgen; das Attribut trennt sie mit |	alle Filter der Sammlung	nein	Filialfinder und Angebotsliste: welche von search, category, price, beds, baths und open_now angezeigt werden, aus denen, die die Sammlung anbietet.
card	card	'auto' oder 'compact'	'auto'	nein	compact-Karten zeigen nur Titel, Untertitel und Aktionen.
prompts	prompts	Array von Zeichenfolgen; das Attribut trennt sie mit |	keiner	nein	Chatleiste: Beispielfragen, als Schaltflächen angezeigt, die sie stellen.
title	chat-title	Zeichenfolge	keiner	nein	Chatleiste: die Beschriftung über dem Feld.
placeholder	placeholder	Zeichenfolge	„Ask about this map“, in der Sprache der Leiste	nein	Chatleiste: der Platzhalter des Felds.
accent	accent	CSS-Farbe	#2da84a	nein	Chatleiste: die Farbe der Senden-Schaltfläche, des Symbols und des Fokusrings.
theme	theme	'light', 'dark' oder 'auto'	'light'	nein	Chatleiste: ihre Farben. auto folgt der Systemeinstellung des Besuchers.
lang	lang	Sprachkennzeichen	Browsersprache des Besuchers	nein	Chatleiste: die Sprache ihrer eigenen Beschriftungen.
resultsUrl	results-url	URL	keiner	nein	Chatleiste: leitet Besucher mit ?q=<question> auf diese Seite, statt die Karte über der Seite zu öffnen.

publishableKey, styleId, map, mapTarget und contained haben auf Viewer keinen Einfluss. Ein Schlüssel ist hier sogar schädlich: Das SDK tauscht ihn gegen eine Sitzung, die Viewer nicht nutzt. Wird dieser Austausch abgewiesen, erscheint die Karte nicht.

Die ID

shareId akzeptiert die beiden ID-Arten, die Studio für eine Karte erstellt:

• ID der veröffentlichten Karte. Sie steht im Code unter Veröffentlichen und einbetten sowie im Tab Einbetten des Dialogs Teilen; an beiden Stellen ist es dieselbe ID.
• ID eines Freigabelinks. Die 16-stellige ID am Ende der URL im Tab Link teilen des Dialogs Teilen.

Die ID der veröffentlichten Karte zeigt immer den aktuell gespeicherten Stand. Ein Freigabelink zeigt den Schnappschuss zum Zeitpunkt seiner Erstellung. Kaleidr AI akzeptiert beide IDs: Bei einem Freigabelink richtet sie sich nach den Schaltern von Kaleidr AI im Schnappschuss, solange die Karte veröffentlicht ist, und nach den aktuellen erlaubten Domains der Karte. Siehe Chat auf veröffentlichter Karte.

Eine leere oder ungültige ID löst keine Ausnahme aus. Das SDK protokolliert

[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.

und zeigt nichts an. Kaleidr.mount liefert trotzdem ein Handle, dessen Methoden nichts bewirken.

Direkte iframe-URL

https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>

Abfrageparameter	Wert	Wirkung
camera	longitude,latitude oder longitude,latitude,zoom	Anfänglicher Mittelpunkt und optional Zoom.
pitch	Zahl in Grad	Anfängliche Neigung.
bearing	Zahl in Grad	Anfängliche Drehung.
q	Text, höchstens 500 Zeichen	Eine Frage, die der Kaleidr AI der Karte beim Öffnen der Karte gestellt wird. Wird nur gestellt, wenn der Viewer in eine Seite eingebettet ist, und bei einer Karte ohne Control Tower ignoriert.
layout	locator, listings, guide oder live	Ein Orts-Layout, der Guide oder das Live-Layout. Jeder andere Wert zeigt die Karte.
collection	eine Sammlungs-ID	Die Sammlung, die das Layout auflistet; bei live die Fahrzeuge-Sammlung.
stops	eine Sammlungs-ID	Bei live die Haltestellen-Sammlung.
filters	Filternamen, getrennt durch |	Die Filter, die das Layout zeigt.
card	auto oder compact	Wie viel die Karte eines Ortes zeigt.

Das SDK erstellt dieselbe URL aus seinen Kameraoptionen, prompt, layout, collection, stops, filters und card.

Kamera

Die Anfangskamera entsteht aus diesen Quellen. Eine spätere Quelle ersetzt nur die von ihr gelieferten Felder.

1. Die Standardansicht der Grundkarte.
2. Die vom Autor in Studio gespeicherte Ansicht. Er kann für Desktop-, Tablet- und Smartphonebreiten getrennte Ansichten hinterlegen. Die passende Ansicht wird anhand der iframe-Breite gewählt. Alternativ kann er die Karte auf ihren Inhalt ausrichten lassen, sodass der Inhalt in den Rahmen passt.
3. Die von deiner Seite angegebene Kamera (center, zoom, pitch, bearing als Optionen oder Attribute beziehungsweise camera, pitch und bearing in einer direkten iframe-URL).

Eine von deiner Seite vorgegebene Kamera hat Vorrang vor der Autorenansicht, auch vor bildschirmbreitenabhängigen Ansichten oder automatischer Inhaltsausrichtung. Nicht angegebene Felder behalten die Werte des Autors.

Bei Karten mit Ansichten je Breite oder Inhaltsausrichtung wird die Ansicht bei Größenänderungen neu angepasst, bis der Besucher die Karte bewegt. Auch eine von deiner Seite vorgegebene Kamera beendet diese Automatik: Nach einer beim Laden angegebenen Kamera oder einem setCamera-Aufruf wird beim Ändern der Rahmengröße nicht mehr automatisch ausgerichtet. setCamera ändert nur die genannten Felder.

Bei center steht der Längengrad zuerst: [-0.1276, 51.5072] ist London.

Größe

• Der iframe ist 100 % so breit wie das Einbindungsziel, ohne Rahmen und mit abgerundeten Ecken.
• Seine Höhe entspricht 100 % des Ziels, wenn dieses beim Einbinden eine Höhe hat. Andernfalls beträgt sie fest 500 Pixel.
• Beim Einbinden werden die Kindelemente des Ziels ersetzt und position:relative (wenn keine Inline-Position vorhanden ist) sowie overflow:hidden gesetzt.
• <kaleidr-map> ist standardmäßig display:block, sodass height funktioniert. Lege eine Höhe fest. Die Beispiele setzen auch display:block für Safari vor 16.4, wo das Element sonst inline bleibt.

Handle

Kaleidr.mount liefert das Handle synchron. Siehe Handle-Matrix für alle Produkte.

Mitglied	Bei Viewer
handle.product	'viewer'
handle.setCamera(camera)	Bewegt die Karte.
handle.setTheme(theme)	Nicht unterstützt; warnt und bewirkt nichts.
handle.setStyle(style)	Nicht unterstützt; warnt und bewirkt nichts.
handle.send(text)	Fragt die Kaleidr AI der Karte, als hätte der Besucher text eingegeben. Bei einer Chatleiste stellt send() ohne Text die Frage, die im Feld steht. Eine Frage, die gesendet wird, während eine andere beantwortet wird, wartet darauf, und eine neuere ersetzt jede noch wartende.
handle.setFilters(filters)	Setzt die Besucherfilter eines Orts-Layouts. Bewirkt beim Layout map nichts.
handle.showVehiclesLayer(layer)	Zeichnet oder bewegt deine eigene Fahrzeugebene.
handle.clearVehiclesLayer()	Entfernt deine Fahrzeugebene.
handle.destroy()	Entfernt den iframe und beendet das Lauschen auf Nachrichten.

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 800,             // 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 sofortiger Sprung.

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

Du kannst setCamera sofort nach der Rückgabe von Kaleidr.mount aufrufen, auch in der nächsten Zeile. Aufrufe vor der Bereitschaft der Karte im iframe werden gespeichert und in Reihenfolge angewendet, sobald die Karte Bereitschaft meldet. Die letzten 256 Aufrufe bleiben erhalten. Meldet die Karte nach einer begrenzten Wartezeit, gewöhnlich 10 Sekunden nach dem Laden des iframes, keine Bereitschaft, werden die Aufrufe dennoch gesendet; es erscheint eine Konsolenwarnung. Du musst kaleidr-embed:ready nicht abwarten. Für die Startansicht sind Einbindungsoptionen direkter: So öffnet die Karte bereits mit der gewünschten Ansicht, statt erst dorthin zu fahren.

Es gibt keine Methode zum Auslesen der aktuellen Kamera.

setFilters(filters)

handle.setFilters({
  q: 'downtown',
  category: ['Outlet', 'Flagship'],
  price: [250000, null],     // [min, max]; null leaves that end open
  beds: 2,
  baths: 1,
  open_now: true,
});

Feld	Typ	Setzt
q	Zeichenfolge	Das Suchfeld.
category	Array von Zeichenfolgen	Die ausgewählten Kategorien.
price	[number | null, number | null]	Minimal- und Maximalpreis.
beds	Zahl	Die Mindestzahl an Schlafzimmern.
baths	Zahl	Die Mindestzahl an Bädern.
open_now	Boolescher Wert	Den Schalter Jetzt geöffnet.

Alle Felder sind optional. Der Besucher sieht die Filter sich ändern, als hätte er sie selbst gesetzt, und kann sie wieder ändern. Ein Feld für einen Filter, den das Layout nicht zeigt, und jedes andere Feld werden ignoriert. Wie bei setCamera wird ein Aufruf vor der Bereitschaft der Karte gespeichert und angewendet, sobald sie bereit ist. Ein Viewer-Bundle, das älter ist als die Orts-Layouts, hat kein setFilters; der Aufruf bewirkt dann nichts und protokolliert eine Konsolenwarnung, dass die Einbindung es nicht bereitgestellt hat.

showVehiclesLayer(layer)

Zeichnet Fahrzeuge, die deine Seite bereits verfolgt, etwa Positionen aus deinem eigenen Disponentensystem, auf die eingebettete Karte. Die Daten gehen von deiner Seite in den iframe und nirgendwo sonst hin: Nichts läuft über Kaleidrs Server, und der Viewer lädt für diese Ebene nichts nach.

handle.showVehiclesLayer({
  layer_id: 'shuttles',
  vehicles: [
    { id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
    { id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
  ],
});

// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });

handle.clearVehiclesLayer();

Feld	Typ	Beschreibung
layer_id	string	Benennt die Ebene. Dieselbe ID aktualisiert sie an Ort und Stelle.
vehicles	array, höchstens 2.000	Die zu zeichnenden Fahrzeuge.
vehicles[].id	string	Pflicht. Kennzeichnet ein Fahrzeug von einem Aufruf zum nächsten.
vehicles[].lat, vehicles[].lng	number	Pflicht. Die Position des Fahrzeugs.
vehicles[].name	string	Die Beschriftung neben dem Fahrzeug.
vehicles[].color	CSS-Hexfarbe	Die Farbe des Fahrzeugs. Ohne sie wird es grau gezeichnet.
vehicles[].bearing	number, Grad	Die Richtung, in die das Fahrzeug zeigt.
attribution	string	Eine Quellenangabe für deine Daten, im Infofenster eines Fahrzeugs gezeigt, wenn man es antippt.

• Dieselbe layer_id aktualisiert an Ort und Stelle. Jedes Fahrzeug gleitet von seiner gezeichneten Position zu seinem neuen Punkt, über die Zeit seit deinem vorigen Aufruf, höchstens 30 Sekunden. Ein Fahrzeug, das im neuen Aufruf fehlt, verschwindet.
• Eine neue layer_id, oder keine, ersetzt die Ebene. Die Karte zeigt jeweils eine Fahrzeugebene.
• Ein Fahrzeug ohne id oder ohne endliche lat und lng wird verworfen, ebenso jedes Fahrzeug nach dem 2.000.
• Um die Fahrzeuge zu bewegen, rufe die Methode erneut auf. Der Viewer fragt für diese Ebene nie selbst Daten ab.
• Wie bei setCamera wird ein Aufruf vor der Bereitschaft der Karte gespeichert und angewendet, sobald sie bereit ist.

Die SDK-Typen LiveLayerData und LiveVehicle deklarieren die Form der Ebene. showVehiclesLayer und clearVehiclesLayer sind Viewer-Methoden: Bei chat, editor und tile protokollieren sie eine Warnung und tun nichts. Ein Viewer-Bundle, das älter ist als diese Ebene, hat keine der beiden; der Aufruf bewirkt dann nichts und protokolliert eine Konsolenwarnung, dass die Einbindung sie nicht bereitgestellt hat.

Elementattribute nach dem Einbinden

Bei einem eingebundenen <kaleidr-map product="viewer"> bewegen Änderungen an center, zoom, pitch oder bearing die Karte ohne Animation. Änderungen an share-id oder anderen Attributen bewirken nichts. Für eine andere Karte muss das Element entfernt und neu eingefügt werden.

Nachrichten aus dem iframe

Der iframe sendet Nachrichten an die einbettende Seite. Zwei davon sind öffentliche Signale für „geladen“ und „fehlgeschlagen“:

// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }

// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }

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

Beim SDK ist iframe der erste <iframe> innerhalb des Einbindungsziels: target.querySelector('iframe').

Fehlercodes

code	Abschließend	Bedeutung
no_id	ja	Die iframe-URL hat keine Karten-ID. id ist null.
not_found	ja	Keine veröffentlichte Karte und kein Freigabelink hat diese ID: Die Karte wurde nie veröffentlicht oder zurückgezogen, die Karte des Freigabelinks wurde gelöscht oder Kaleidr hat den Link entfernt, oder die ID ist falsch geschrieben.
domain_not_allowed	ja	Die Karte beschränkt Domains, und die Seite ist nicht zugelassen oder sendete keinen Referrer.
map_loads_exhausted	ja	Die Eigentümerorganisation hat ihr Kartenaufrufkontingent verbraucht.
fetch_failed	ja	Die Karte konnte nicht abgerufen werden.
maplibre_error	nein	Die Karte startete, aber ein Teil konnte nicht gezeichnet werden. Kann vor oder nach ready mehrfach eintreffen.

Nach einem abschließenden Fehlercode zeigt der iframe statt der Karte eine kurze Meldung und sendet kein ready.

Regeln

• ready wird einmal pro Laden gesendet, nachdem die Karte gezeichnet und die Ansicht gezählt wurde.
• Das SDK erstellt den iframe mit loading="lazy"; Nachrichten kommen erst, wenn er in die Nähe des sichtbaren Bereichs gelangt.
• Der iframe sendet weitere Nachrichten mit einem type, der mit kaleidr-embed: beginnt. Das SDK verbindet damit Chat und Karte. Sie gehören nicht zum öffentlichen Vertrag und können sich ändern; baue nicht darauf.
• Steuerungsnachrichten, etwa die Kamerabewegung hinter setCamera, verarbeitet der iframe nur von der Seite, die ihn unmittelbar einbettet. Nachrichten aus anderen Fenstern oder Frames werden ignoriert. Rufe daher setCamera auf der einbettenden Seite auf.
• SDK und Element senden keine DOM-Ereignisse und bieten kein ready-Promise.

Sichtbare Nachrichten für Besucher

Sie erscheinen anstelle der Karte im iframe:

Text	Code
"Loading map…"	keiner: Karte lädt
"Couldn't find a map id in the URL."	no_id
"This map isn't available — it may have been unpublished, paused, or the link is incorrect."	not_found
"This map isn't allowed to render on this site. Please contact the map owner."	domain_not_allowed
"This map has reached its map load limit. It will be available again when the owner's allowance resets."	map_loads_exhausted
"Could not load the map. Please try again in a moment."	fetch_failed
"Unexpected error loading the map."	keiner: unerwarteter Fehler beim Start

Hochgeladene Daten

Eine veröffentlichte Karte zeichnet die Datensätze und Bildüberlagerungen, die ihr Autor im Studio-Datenbereich hinzugefügt hat. Der iframe lädt sie selbst. Es sind keine Optionen, Attribute oder Schlüssel nötig, und die Daten laufen nie über deine Seite.

Verhalten	Einzelheiten
Was gezeigt wird	Alle Datensätze und Bildüberlagerungen der veröffentlichten Karte als vom Autor gestaltete Ebenen.
Wer sie lesen kann	Jeder, der die Karte öffnen kann. Zugelassene Domains machen die Daten nicht vertraulich.
Was der Browser erhält	Jeden Datensatz vollständig mit allen Spalten. Große Datensätze laden langsamer.
Wenn ein Datensatz nicht geladen werden kann	Der Rest der Karte wird ohne die betreffende Ebene gezeichnet.
Datensatz im Studio-Datenbereich löschen	Der Datensatz wird gelöscht und nicht mehr über die veröffentlichte Karte oder Freigabelinks ausgeliefert. Bereits geladene Daten bleiben im Browser; ein zuvor erstellter Downloadlink kann bis zu eine Stunde gültig sein.
Karte zurückziehen	Über die veröffentlichte ID werden Karte und Datensätze nicht mehr ausgeliefert. Der iframe zeigt not_found. Erneutes Veröffentlichen stellt dieselbe ID wieder her.
Freigabelinks	Ein Link enthält einen Schnappschuss des Kartendesigns zum Erstellungszeitpunkt und zeigt seine Karte auch nach dem Zurückziehen der Karte weiter, ohne Kaleidr AI, bis die Karte erneut veröffentlicht wird. Studio hat keine Funktion zum Löschen oder Pausieren solcher Links; sie funktionieren, bis die Karte gelöscht oder der Link auf Eigentümerwunsch durch Kaleidr entfernt wird. Siehe Freigabelinks.

Hochgeladene Daten auf veröffentlichter Karte erläutert diese Fälle.

Erlaubte Domains

Der Eigentümer kann in Studio unter Teilen, Einbetten, Bestimmte Domains festlegen, auf welchen Websites die Karte erscheint.

• Eine gelistete Domain umfasst auch ihre Subdomains.
• Die Prüfung vergleicht die Liste mit dem Hostnamen des Referrers, den der Browser für den iframe sendet. Ohne Referrer schlägt sie fehl.
• Bei Ablehnung erscheint die Meldung „nicht erlaubt“ und domain_not_allowed wird gesendet.
• Eine wegen der Domain abgewiesene Ansicht zählt nicht als Kartenaufruf.

Abrechnung

• Eine Ansicht zählt einen Kartenaufruf für die Eigentümerorganisation.
• Sieht derselbe Besucher dieselbe Karte innerhalb von 24 Stunden erneut, wird sie nicht erneut gezählt.
• Ansichten auf Kaleidrs eigenen Seiten werden nicht gezählt.
• Ist das Kontingent erschöpft, zeigt der iframe die Grenzmeldung bis zur Rücksetzung. Siehe Kontingente und Ratenbegrenzung.

Konsolenmeldungen

Nachricht	Bedeutung
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	Das Element hat kein gültiges product und wird nicht eingebunden.
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$.	Die ID ist leer oder ungültig.
[kaleidr:viewer] mount target not found: <selector>	Kaleidr.mount fand kein zum Selektor passendes Element.
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js	Das Viewer-Bundle konnte wegen Netzwerkfehler, Blocker oder script-src-Richtlinie nicht geladen werden.
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. …	Eine von Viewer nicht unterstützte Handle-Methode wurde aufgerufen.

Nicht verfügbar

• Ereignisse für Klicks, Kamerabewegungen oder Auswahlen, einschließlich Ortskarten und Ortsaktionen.
• Kamerawerte, Ebenen oder Kartendaten auslesen.
• Eigene Marker oder Ebenen zur eingebetteten Karte hinzufügen, außer einer Fahrzeugebene.
• Grundkarte oder Design über die Einbindung ändern.

Verwandte Themen

• Veröffentlichte Karte einbetten
• Das Element <kaleidr-map>
• Der Loader kaleidr.js
• Chat auf veröffentlichter Karte