Referencia de Viewer
product="viewer" muestra un mapa publicado en Kaleidr Studio. El SDK sustituye el contenido del destino de montaje por un iframe que carga https://map-embed.kaleidr.com/embed/<id>. El mapa se dibuja dentro de ese iframe.
| Clave | Ninguna. No proporciones una. |
| Plan | Todos los planes, incluido Free. |
| Se muestra en | Un iframe de https://map-embed.kaleidr.com. |
| Contabilización | Una carga de mapa por visualización, a cargo de la organización propietaria del mapa. |
| CSP | script-src https://cdn.kaleidr.com y frame-src https://map-embed.kaleidr.com. |
Para un tutorial, consulta Incrustar un mapa publicado.
Montaje
Con el elemento:
<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>
Desde JavaScript:
const handle = Kaleidr.mount('#map', {
product: 'viewer',
shareId: 'YOUR_MAP_ID',
});
Sin usar el 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>
Barra de chat
layout="bar" convierte Viewer en una barra de chat: un único campo de pregunta para tu página, sin mapa hasta que un visitante pregunta. Una pregunta abre el mapa publicado, y la Kaleidr AI del mapa la responde allí.
<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>
Las respuestas se abren en uno de estos dos lugares:
| Ajuste | Qué hace una pregunta |
|---|---|
Sin results-url (predeterminado) | El mapa se abre sobre la página, ocupando toda la ventana, y hace la pregunta. El visitante lo cierra con su botón de cierre. Una pregunta posterior se dirige al mismo mapa, así que la conversación continúa. |
results-url="/map" | El navegador va a esa página con ?q=<question>. Un Viewer en esa página con prompt-param="q" hace la pregunta cuando se abre el mapa, si el visitante llegó desde una página del mismo origen. |
Una página de resultados:
<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>
- Responde el mapa. La pregunta llega al propio panel Ask Kaleidr del mapa, así que el mapa necesita Control Tower activado (Studio, Kaleidr AI), y se aplican las reglas de Kaleidr AI en un mapa publicado: paga el propietario, y los dominios permitidos del mapa deciden dónde responde. En un mapa sin Control Tower, el mapa se abre y la pregunta no se hace.
- La barra no carga ningún mapa. El mapa se carga, y cuenta como carga de mapa, cuando un visitante pregunta.
- La barra se dibuja en su propia shadow root, así que el CSS de tu página no la modifica y sus estilos no necesitan permiso
style-src. Ocupa el ancho del elemento y su altura se ajusta a su contenido. - Sus propias etiquetas siguen
lang, o el idioma del navegador del visitante cuandolangno está definido: inglés, español, francés, alemán, portugués, japonés, coreano, chino simplificado y tradicional, y árabe. Tuschat-title,placeholderypromptsse muestran tal como los escribes. promptrellena el campo de antemano, yhandle.send()pregunta desde el código.handle.send('Parks nearby')hace esa pregunta;handle.send()pregunta lo que haya en el campo.
El generador de template.kaleidr.com escribe ambos fragmentos para el mapa que elijas.
Diseños de lugares
layout="locator" y layout="listings" muestran el mapa publicado junto a una lista de una colección de la Biblioteca de lugares que dibuja el mapa, con los filtros y las fichas de la colección.
<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>
| Diseño | La lista | Los pines |
|---|---|---|
locator | Lugares ordenados por distancia, con un campo de búsqueda, un botón Cerca de mí, los filtros y un recuento. Una búsqueda que no coincide con ningún lugar de la lista mueve el mapa al lugar buscado. | La capa de la colección, con el estilo de Studio. |
listings | Fichas con foto, en dos columnas en un marco ancho, ordenadas por Distancia, Precio: de menor a mayor o Precio: de mayor a menor. | Etiquetas de precio. |
- La lista está junto al mapa en un marco de 768 píxeles de ancho o más, y por debajo de eso en una hoja sobre el mapa que el visitante arrastra hacia arriba.
- La lista y el mapa van a la par. Al seleccionar un lugar en la lista, el mapa se mueve hasta él y abre su ficha; al seleccionar un pin, la lista se desplaza hasta él. La lista, los pines y el recuento siempre muestran los mismos lugares.
- La lista muestra 50 lugares a la vez, con Mostrar más.
- Cerca de mí pide al visitante su ubicación. El iframe que crea el SDK lo permite; un iframe directo necesita
allow="geolocation". - En un mapa que no dibuja ninguna colección, ambos diseños muestran solo el mapa.
filters elige cuáles de los Filtros para visitantes de la colección se muestran, separados por |. Aparecen en el orden de la colección, sea cual sea el orden en que los escribas, y un filtro que la colección no ofrece se ignora. Sin filters, el diseño muestra todos los filtros de la colección.
| Filtro | Muestra | Coincide con |
|---|---|---|
search | Un campo de texto | Lugares cuyo nombre, dirección o categoría contiene el texto. |
category | Botones de categoría, hasta las 30 más frecuentes | Lugares de cualquiera de las categorías seleccionadas. |
price | Mínimo y máximo | Lugares con un precio dentro del rango. Un lugar sin precio se oculta en cuanto se acota el rango. |
beds, baths | Cualquiera, 1+, 2+, 3+, 4+ | Lugares con al menos esa cantidad. |
open_now | Un interruptor | Lugares abiertos en este momento, en su propia zona horaria. Los lugares sin horario se ocultan mientras está activado. |
Todos los filtros que establece un visitante se aplican a la vez.
card define cuánto muestra la ficha de un lugar. auto, el valor predeterminado, es la ficha diseñada en Studio. compact muestra solo el título, el subtítulo y las acciones, para un marco pequeño.
Las acciones de lugar funcionan como las define la colección. Cómo llegar dibuja la ruta en el mapa y ofrece Apple Maps y Google Maps; un Enlace se abre en una pestaña nueva; Llamar abre un enlace telefónico; una acción de solicitud, como Schedule a Tour, abre el formulario de solicitud del negocio sobre el mapa.
Diseño de guía
layout="guide" abre un mapa de establecimientos con su panel Ask Kaleidr al lado: la guía del barrio de un hotel, o el mapa de la zona de un local. Lista una colección de Establecimientos (collection, o si no la primera colección de Establecimientos que dibuja el mapa) y necesita Control Tower activado. En un mapa que no dibuja ninguna colección de Establecimientos, el diseño muestra solo el mapa.
<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>
- El chat va primero. En un marco de 769 píxeles de ancho o más, el panel mide 400 píxeles de ancho, a la izquierda del mapa. En marcos más estrechos es una hoja sobre el mapa al 45 % de su altura, que el visitante arrastra hasta el 85 %. La nota de que las respuestas las genera la IA sigue bajo el campo.
- Los chips de categoría sobre el campo son las ocho categorías más comunes de la colección. Un chip muestra los pines de esa categoría y pregunta "Muéstrame categoría cerca de ancla" en el idioma del visitante. Plan My Day pregunta "Planifica mi día alrededor de ancla".
- El ancla es el Pin de Referencia del mapa, definido en los ajustes del mapa en Studio: un lugar de una colección que dibuja el mapa, o un punto colocado en el mapa, como tu hotel. Se dibuja como un pin propio con su nombre, y "cerca" en la guía significa cerca de él. Un mapa sin ancla usa su centro.
- El plan del día. Cuando se le pide planificar un día, la guía dibuja una ruta que empieza en el ancla y visita primero lugares de tus propias colecciones y después datos de lugares propios de Kaleidr, y la muestra como una tarjeta de paradas con nombre y sus horas, en el idioma del visitante.
- Las fichas de los establecimientos muestran la ficha diseñada en Studio, con Staff Pick en los lugares que marques, y debajo las tarjetas de tus Conexiones. El contenido conectado aparece solo en las fichas, nunca en las respuestas de la guía.
- Solicitudes. La acción Reserve de un establecimiento abre el formulario de solicitud del negocio.
La guía en el flujo del chat
El viewer indica a la Kaleidr AI del mapa qué diseño muestra. Un cliente de POST /chat/control/stream ve dos campos que pertenecen a la guía:
| Campo | Dónde | Forma |
|---|---|---|
layout | El cuerpo de la solicitud | "guide" mientras se muestra un diseño de guía; se omite en otro caso, lo que es un turno de mapa normal. Como máximo 16 caracteres, o la solicitud se rechaza con 422 invalid_layout. |
itinerary | Un evento del flujo, repetido en el evento end | { title, stops: [{ name, time?, note? }] }: el título del plan del día y de 1 a 12 paradas con nombre, ya en el idioma del visitante. Una note aparece solo para tus propios lugares. |
Un cliente que no muestra planes del día puede ignorar el evento.
Diseño en vivo
layout="live" muestra dónde están ahora tus vehículos y dónde paran hoy: la ruta de un food truck, un servicio de lanzadera, un servicio móvil. Lee dos colecciones: una colección de Vehículos, cuyas posiciones vienen del seguimiento en vivo, y una colección de Paradas con el horario.
<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>
| Opción | Predeterminado | Lee |
|---|---|---|
collection | La primera colección de Vehículos que dibuja el mapa | Los vehículos que se muestran en vivo. |
stops | La primera colección de Paradas que dibuja el mapa | Las paradas y sus ventanas de servicio. |
En un mapa que no dibuja ninguna de las dos, el diseño muestra solo el mapa. El panel está junto al mapa en un marco de 769 píxeles de ancho o más, y es una hoja sobre el mapa por debajo de ese ancho.
- Una píldora En vivo encabeza el panel, o Sin servicio ahora cuando ningún vehículo está de turno.
- Una fila por cada vehículo mostrado: su nombre; En movimiento, Detenido, En y la parada, o Visto hace 5 min cuando su último informe es más antiguo que el Marcar como Desactualizado Tras de la flota; y Próxima parada con Unos 12 min y una etiqueta Estimación.
- Ruta de hoy: las paradas de hoy en el orden de sus ventanas, cada una con su ventana, el vehículo que la atiende y una insignia.
- ¿Cuánto tarda hasta mí? pide la ubicación del visitante, o usa una posición aproximada de la ciudad si la rechaza, y muestra cuánto tardarían en llegar los vehículos mostrados. La ubicación se usa solo para esa estimación y nunca se guarda.
- Al seleccionar un vehículo, el mapa lo sigue hasta que el visitante mueve el mapa. Al seleccionar una parada se abre su ficha, con las ventanas de hoy o la próxima fecha de servicio.
| Insignia | Cuándo |
|---|---|
| Aquí ahora | El vehículo registró su llegada a la parada. |
| Cerrado hoy | El conductor marcó el vehículo como cerrado por hoy. |
| Abierto ahora | Una ventana de la parada contiene este momento. |
| Siguiente: 11:00–14:00 | La parada tiene una ventana más tarde hoy. |
| Hoy no | La parada no tiene ninguna ventana hoy. Su ficha indica la próxima fecha de servicio en los próximos 14 días. |
Lo que ve el visitante se mueve con suavidad y nunca adivina. Un vehículo se desliza de una posición informada a la siguiente y nunca se adelanta a su último informe. Las posiciones se actualizan cada 10 segundos salvo que el autor del mapa haya elegido otro intervalo (de 5 a 60 segundos), y se pausan mientras la página está oculta. Los estados de hoy y las estimaciones se actualizan cada minuto. Una actualización fallida mantiene la última imagen.
Solo se muestran los vehículos de turno, con la precisión que permite la precisión pública de la flota. Un vehículo cuyo turno termina desaparece en la siguiente actualización.
Cada tiempo es una estimación. Se calcula a partir de la distancia por carretera y velocidades habituales, y no incluye el tráfico. Se redondea al minuto superior y se muestra como Unos 12 min o Unos 1 h 20 min, nunca como una hora de llegada. Si no hay ruta por carretera entre ambos, la fila dice Sin estimación. Las rutas por carretera se construyen con datos de OpenStreetMap, © colaboradores de OpenStreetMap, bajo la ODbL.
Request Pickup es la acción de solicitud de la colección de Paradas. Cuando su autor activó Permitir que los visitantes elijan recogida y destino, el visitante primero fija una recogida, la propia parada salvo que la cambie, y un destino, cada uno buscando una dirección o tocando el mapa, y después rellena el formulario de solicitud. Ambos puntos van con la solicitud.
Las etiquetas del panel siguen el idioma del viewer, en los mismos diez idiomas que la barra de chat.
Opciones
| Opción de montaje | Atributo | Tipo | Predeterminado | Obligatorio | Descripción |
|---|---|---|---|---|---|
product | product | 'viewer' | ninguno | sí | Selecciona Viewer. |
shareId | share-id | cadena | ninguno | sí | ID del mapa publicado obtenido del código de Studio. Debe cumplir ^[A-Za-z0-9._~-]{1,100}$. |
mapId | map-id | cadena | ninguno | no | Alias de shareId, utilizado cuando falta shareId. |
center | center | [longitude, latitude]; atributo "longitude,latitude" | vista guardada | no | Centro inicial. |
zoom | zoom | número | vista guardada | no | Zoom inicial; se ignora al montar si no se proporciona también center. |
pitch | pitch | número, grados | vista guardada | no | Inclinación inicial. |
bearing | bearing | número, grados | vista guardada | no | Rotación inicial. |
viewerBase | viewer-base | URL | https://map-embed.kaleidr.com | no | Origen desde el que se carga el iframe. Solo se utiliza el origen. No es necesario en producción. |
base | base | URL | https://cdn.kaleidr.com | no | Origen desde el que el SDK carga viewer.js. Solo se usa el origen y se aceptan únicamente los enumerados en La sustitución de base. |
enabled | flag | booleano | ninguno | no | Control por montaje de la puerta de activación. |
prompt | prompt | cadena | ninguno | no | Pregunta que se plantea a la Kaleidr AI del mapa al abrirse. En una barra de chat, el texto precargado del campo. Máximo 500 caracteres. |
promptParam | prompt-param | cadena | ninguno | no | Lee prompt de este parámetro de consulta de la URL de la propia página: q en la página de resultados de una barra de chat. Solo se lee cuando el visitante llegó desde una página del mismo origen, para que un enlace desde otro sitio no pueda hacer que tu mapa pregunte nada. |
layout | layout | 'map', 'bar', 'locator', 'listings', 'guide' o 'live' | 'map' | no | bar monta la barra de chat. locator y listings muestran el mapa junto a una lista de una colección: consulta Diseños de lugares. guide abre el chat junto a un mapa de establecimientos: consulta Diseño de guía. live muestra los vehículos y las paradas de hoy: consulta Diseño en vivo. |
collection | collection | string | la primera colección del tipo del diseño que dibuja el mapa | no | Localizador, anuncios y guía: el identificador de la colección que se lista. En vivo: el identificador de la colección de Vehículos. |
stops | stops | string | la primera colección de Paradas que dibuja el mapa | no | En vivo: el identificador de la colección de Paradas. |
filters | filters | matriz de cadenas; el atributo las separa con | | todos los filtros de la colección | no | Localizador y anuncios: cuáles de search, category, price, beds, baths y open_now se muestran, de entre los que ofrece la colección. |
card | card | 'auto' o 'compact' | 'auto' | no | Las fichas compact muestran solo el título, el subtítulo y las acciones. |
prompts | prompts | matriz de cadenas; el atributo las separa con | | ninguno | no | Barra de chat: preguntas de ejemplo, mostradas como botones que las formulan. |
title | chat-title | cadena | ninguno | no | Barra de chat: la etiqueta sobre el campo. |
placeholder | placeholder | cadena | «Ask about this map», en el idioma de la barra | no | Barra de chat: el marcador de posición del campo. |
accent | accent | color CSS | #2da84a | no | Barra de chat: el color del botón de envío, el icono y el anillo de foco. |
theme | theme | 'light', 'dark' o 'auto' | 'light' | no | Barra de chat: sus colores. auto sigue la configuración del sistema del visitante. |
lang | lang | etiqueta de idioma | el idioma del navegador del visitante | no | Barra de chat: el idioma de sus propias etiquetas. |
resultsUrl | results-url | URL | ninguno | no | Barra de chat: envía a los visitantes a esta página con ?q=<question> en lugar de abrir el mapa sobre la página. |
publishableKey, styleId, map, mapTarget y contained no afectan a un montaje de Viewer. Darle una clave es contraproducente: el SDK la intercambia por una sesión que Viewer nunca utiliza; si se rechaza ese intercambio, el mapa no aparece.
El identificador
shareId admite los dos tipos de identificador que Studio genera para un mapa:
- ID del mapa publicado. Es el identificador del fragmento de código en Publicar e incrustar y en la pestaña Incrustar del cuadro Compartir; ambos muestran el mismo.
- ID de un enlace compartido. Es el identificador de 16 caracteres al final de la URL en la pestaña Compartir enlace del cuadro Compartir.
El ID del mapa publicado muestra el mapa tal como está guardado actualmente. El ID de un enlace compartido muestra la instantánea creada cuando se generó ese enlace. Kaleidr AI admite cualquiera de los dos ID: en un enlace compartido sigue los interruptores de Kaleidr AI de la instantánea, mientras el mapa está publicado y con los dominios autorizados actuales del mapa; consulta Chat en un mapa publicado.
Un ID vacío o malformado no lanza una excepción. El SDK registra
[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.
y no muestra nada. Kaleidr.mount sigue devolviendo un controlador, pero sus métodos no hacen nada.
URL de iframe directo
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>
| Parámetro de consulta | Valor | Efecto |
|---|---|---|
camera | longitude,latitude o longitude,latitude,zoom | Centro inicial y, opcionalmente, zoom. |
pitch | número, grados | Inclinación inicial. |
bearing | número, grados | Rotación inicial. |
q | texto, máximo 500 caracteres | Pregunta que se plantea a la Kaleidr AI del mapa al abrirse. Solo se pregunta cuando el Viewer está incrustado en una página, y se ignora en un mapa sin Control Tower. |
layout | locator, listings, guide o live | Un diseño de lugares, la guía o el diseño en vivo. Cualquier otro valor muestra el mapa. |
collection | un identificador de colección | La colección que lista el diseño; en live, la colección de Vehículos. |
stops | un identificador de colección | En live, la colección de Paradas. |
filters | nombres de filtros separados por | | Los filtros que muestra el diseño. |
card | auto o compact | Cuánto muestra la ficha de un lugar. |
El SDK construye la misma URL a partir de sus opciones de cámara, prompt, layout, collection, stops, filters y card.
Cámara
La cámara inicial se obtiene de las siguientes fuentes. Cada fuente posterior sustituye solo los campos que aporta.
- La vista predeterminada del mapa base.
- La vista guardada por el autor en Studio. Puede guardar vistas distintas para anchos de escritorio, tableta y móvil, y el mapa elige la que corresponde al ancho del iframe. También puede configurar el encuadre automático del contenido, de modo que el mapa ajusta dicho contenido al marco.
- La cámara que tú pasas (
center,zoom,pitch,bearingen opciones o atributos, ocamera,pitchybearingen una URL de iframe directo).
La cámara proporcionada por tu página prevalece sobre la vista del autor, incluso si esta depende del ancho de pantalla o encuadra el contenido. Los campos no proporcionados conservan los valores del autor.
Un mapa con vistas según el ancho o encuadre del contenido vuelve a ajustarse al cambiar el tamaño del iframe, hasta que el visitante lo mueve. La cámara de tu página también desactiva ese reajuste: tras indicar una cámara al cargar o llamar a setCamera, el mapa ya no vuelve a encuadrarse automáticamente al redimensionar. setCamera modifica solo los campos indicados y conserva el resto.
En center va primero la longitud: [-0.1276, 51.5072] corresponde a Londres.
Dimensiones
- El iframe ocupa el 100 % del ancho del destino, no tiene borde y presenta esquinas redondeadas.
- Su altura es el 100 % del destino si este tiene altura al montar; en caso contrario, se fija en 500 píxeles.
- El montaje sustituye los hijos del destino y establece
position:relative(si no hay posición en línea) yoverflow:hidden. <kaleidr-map>esdisplay:blockde forma predeterminada, por lo que aceptaheight. Asígnale una altura. Los ejemplos también incluyendisplay:blockpara Safari anterior a 16.4, donde sigue siendo un elemento en línea.
Controlador
Kaleidr.mount devuelve el controlador de forma síncrona. Consulta la matriz del controlador de los cuatro productos.
| Miembro | En Viewer |
|---|---|
handle.product | 'viewer' |
handle.setCamera(camera) | Mueve el mapa. |
handle.setTheme(theme) | No admitido; muestra una advertencia y no hace nada. |
handle.setStyle(style) | No admitido; muestra una advertencia y no hace nada. |
handle.send(text) | Pregunta a la Kaleidr AI del mapa como si el visitante hubiera escrito text. En una barra de chat, send() sin texto pregunta lo que haya en el campo. Una pregunta enviada mientras se responde otra espera a que termine, y una más reciente sustituye a cualquiera que siga en espera. |
handle.setFilters(filters) | Establece los filtros para visitantes de un diseño de lugares. No hace nada en el diseño map. |
handle.showVehiclesLayer(layer) | Dibuja o mueve tu propia capa de vehículos. |
handle.clearVehiclesLayer() | Quita tu capa de vehículos. |
handle.destroy() | Elimina el iframe y deja de escuchar mensajes. |
setCamera(camera)
handle.setCamera({
center: [2.3522, 48.8566], // [longitude, latitude]
zoom: 12,
pitch: 45,
bearing: -20,
duration: 800, // milliseconds
});
| Campo | Tipo | Descripción |
|---|---|---|
center | [number, number] | Longitud, latitud. |
zoom | número | Nivel de zoom. A diferencia del montaje, zoom funciona sin center. |
pitch | número | Inclinación en grados. |
bearing | número | Rotación en grados. |
duration | número | Duración de la animación en milisegundos. Omitida o igual a 0 produce un salto inmediato. |
Todos los campos son opcionales; los que omitas conservan su valor actual.
Puedes llamar a setCamera en cualquier momento después de que Kaleidr.mount devuelva, incluso en la línea siguiente. Si el mapa dentro del iframe aún no está listo, la llamada se conserva y aplica en orden cuando el mapa anuncia su disponibilidad. Se guardan las últimas 256 llamadas. Si el mapa sigue sin informar que está listo tras una espera limitada, normalmente 10 segundos después de cargarse el iframe, las llamadas se envían igualmente y aparece una advertencia en consola. No necesitas esperar al mensaje kaleidr-embed:ready. Para definir la vista de apertura, las opciones de montaje siguen siendo la vía más directa: el mapa empieza en ella en vez de moverse hasta allí.
No existe ningún método para leer la cámara actual.
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,
});
| Campo | Tipo | Establece |
|---|---|---|
q | cadena | El campo de búsqueda. |
category | matriz de cadenas | Las categorías seleccionadas. |
price | [number | null, number | null] | El precio mínimo y máximo. |
beds | número | El número mínimo de habitaciones. |
baths | número | El número mínimo de baños. |
open_now | booleano | El interruptor Abierto ahora. |
Todos los campos son opcionales. El visitante ve cambiar los filtros como si los hubiera establecido él, y puede volver a cambiarlos. Un campo de un filtro que el diseño no muestra, y cualquier otro campo, se ignora. Como con setCamera, una llamada hecha antes de que el mapa esté listo se guarda y se aplica cuando lo está. Un paquete de viewer anterior a los diseños de lugares no tiene setFilters; la llamada entonces no hace nada y registra una advertencia en la consola indicando que el montaje no lo expone.
showVehiclesLayer(layer)
Dibuja en el mapa incrustado vehículos que tu página ya sigue, como las posiciones de tu propio sistema de despacho. Los datos van de tu página al iframe y a ningún otro sitio: nada pasa por los servidores de Kaleidr, y el viewer no descarga nada para esta capa.
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();
| Campo | Tipo | Descripción |
|---|---|---|
layer_id | string | Da nombre a la capa. El mismo id de nuevo la actualiza en su sitio. |
vehicles | array, como máximo 2.000 | Los vehículos que se dibujan. |
vehicles[].id | string | Obligatorio. Identifica un vehículo de una llamada a la siguiente. |
vehicles[].lat, vehicles[].lng | number | Obligatorio. La posición del vehículo. |
vehicles[].name | string | La etiqueta que se dibuja junto al vehículo. |
vehicles[].color | color hexadecimal de CSS | El color del vehículo. Sin él, se dibuja en gris. |
vehicles[].bearing | number, grados | La dirección hacia la que mira el vehículo. |
attribution | string | Un crédito para tus datos, mostrado en la tarjeta de un vehículo al tocarlo. |
- El mismo
layer_idactualiza la capa en su sitio. Cada vehículo se desliza desde donde está dibujado hasta su nuevo punto durante el tiempo transcurrido desde tu llamada anterior, como máximo 30 segundos. Un vehículo que falta en la nueva llamada desaparece. - Un
layer_idnuevo, o ninguno, sustituye la capa. El mapa muestra una sola capa de vehículos a la vez. - Un vehículo sin
id, o sinlatylngfinitos, se descarta, igual que todo vehículo a partir del 2.001. - Para mover los vehículos, vuelve a llamar. El viewer nunca consulta datos para esta capa.
- Como con
setCamera, una llamada hecha antes de que el mapa esté listo se guarda y se aplica cuando lo está.
Los tipos LiveLayerData y LiveVehicle del SDK declaran la forma de la capa. showVehiclesLayer y clearVehiclesLayer son métodos del viewer: en chat, editor y tile registran una advertencia y no hacen nada. Un paquete de viewer anterior a esta capa no tiene ninguno de los dos; la llamada entonces no hace nada y registra una advertencia en la consola indicando que el montaje no lo expone.
Atributos del elemento después del montaje
En un <kaleidr-map product="viewer"> montado, cambiar center, zoom, pitch o bearing mueve el mapa sin animación. Cambiar share-id u otro atributo no hace nada. Para mostrar otro mapa, elimina el elemento e inserta uno nuevo.
Mensajes del iframe
El iframe envía mensajes a la página que lo incrusta. Dos son señales públicas de «cargado» y «fallido»:
// 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);
});
Con el SDK, iframe es el primer <iframe> dentro del destino de montaje: target.querySelector('iframe').
Códigos de error
code | Terminal | Significado |
|---|---|---|
no_id | sí | La URL del iframe no contiene ID del mapa. id es null. |
not_found | sí | No existe un mapa publicado ni un enlace compartido con ese ID: el mapa nunca se publicó o se retiró, el mapa del enlace compartido se eliminó o Kaleidr quitó el enlace, o el ID tiene un error. |
domain_not_allowed | sí | El mapa restringe los dominios y la página no está permitida, o no envió referente. |
map_loads_exhausted | sí | La organización propietaria ha agotado sus cargas de mapa del período. |
fetch_failed | sí | No se pudo recuperar el mapa. |
maplibre_error | no | El mapa se inició, pero no se pudo dibujar algo. Puede llegar varias veces antes o después de ready. |
Tras un código terminal, el iframe muestra un mensaje breve en vez del mapa y no envía ready.
Reglas
readyse envía una vez por carga, tras dibujarse el mapa y contabilizar la visualización.- El SDK crea el iframe con
loading="lazy", así que los mensajes no llegan hasta que se acerca al área visible. - El iframe envía otros mensajes cuyo
typeempieza porkaleidr-embed:. El SDK los usa para vincular el panel de Chat con el mapa. No son un contrato público y pueden cambiar; no dependas de ellos. - El iframe solo acepta mensajes de control, como el movimiento de cámara de
setCamera, si vienen de la página que lo incrusta directamente. Ignora mensajes de otras ventanas o marcos, así que llama asetCameradesde la página que contiene el iframe. - Ni el SDK ni el elemento emiten eventos DOM ni ofrecen una promesa
ready.
Mensajes visibles para el visitante
Estos textos aparecen dentro del iframe en lugar del mapa:
| Texto | Código |
|---|---|
| "Loading map…" | ninguno: el mapa está cargándose |
| "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." | ninguno: error inesperado durante el inicio |
Datos cargados
Un mapa publicado dibuja los conjuntos de datos y las superposiciones de imágenes que su autor añadió en el panel Datos de Studio. El propio iframe los carga; no interviene ninguna opción, atributo ni clave, y los datos nunca atraviesan tu página.
| Comportamiento | Detalle |
|---|---|
| Qué se muestra | Todos los conjuntos de datos y superposiciones de imágenes incluidos en el mapa publicado, como capas diseñadas por su autor. |
| Quién puede leerlos | Cualquiera que pueda abrir el mapa. Los dominios permitidos no convierten los datos en confidenciales. |
| Qué recibe el navegador | Cada conjunto de datos completo, con todas sus columnas. Uno grande tarda más en aparecer. |
| Si falla la carga de un conjunto de datos | Se dibuja el resto del mapa sin esa capa. |
| Eliminación de un conjunto de datos en Studio | Se elimina y deja de servirse en el mapa publicado y en todos los enlaces que lo mostraban. Los navegadores que ya lo cargaron lo conservan y un enlace de descarga emitido puede funcionar hasta una hora. |
| Retirada de publicación del mapa | Deja de servirse todo el mapa, incluidos los datos, por su ID publicado. El iframe muestra not_found. Volver a publicarlo recupera el mismo ID. |
| Enlaces compartidos | Un enlace compartido es una instantánea del diseño al crearlo y sigue mostrando su mapa al retirar la publicación, sin Kaleidr AI hasta que el mapa se vuelva a publicar. Studio no permite eliminar ni pausar enlaces; siguen disponibles hasta que se elimina el mapa o Kaleidr retira el enlace a petición del propietario. Consulta Enlaces compartidos. |
Datos cargados en un mapa publicado explica cada caso.
Dominios permitidos
El propietario puede restringir los sitios que muestran el mapa desde Studio, en Compartir, Incrustar, Dominios específicos.
- Un dominio incluido también cubre sus subdominios.
- La comprobación compara la lista con el nombre de host del referente que el navegador envía para el iframe. Sin referente, falla.
- Si falla, muestra el mensaje de «no permitido» y envía
domain_not_allowed. - Una visualización rechazada por el dominio no se contabiliza como carga de mapa.
Contabilización
- Cada visualización cuenta una carga de mapa contra la organización propietaria.
- Si el mismo visitante vuelve a ver el mismo mapa dentro de 24 horas, no se vuelve a contabilizar.
- Las visualizaciones en los propios sitios de Kaleidr no cuentan.
- Cuando se agota la cuota, el iframe muestra el mensaje de límite hasta su restablecimiento. Consulta Cuotas y límites de tasa.
Mensajes de consola
| Mensaje | Significado |
|---|---|
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" | El elemento carece de un product válido. No se monta. |
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$. | El ID está vacío o mal formado. |
[kaleidr:viewer] mount target not found: <selector> | Kaleidr.mount no encontró el elemento del selector. |
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js | No se pudo cargar el paquete Viewer por un problema de red, un bloqueador o la política script-src. |
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. … | Se llamó a un método que Viewer no admite. |
No disponible
- Eventos de clics, movimientos de cámara o selecciones, incluidas las fichas y las acciones de lugar.
- Leer la cámara, las capas o los datos del mapa.
- Añadir tus marcadores o capas al mapa incrustado, salvo una capa de vehículos.
- Cambiar el mapa base o el tema desde la incrustación.