Referencia de Tile

product="tile" muestra un mapa base de Kaleidr seleccionado mediante un identificador de estilo. El SDK intercambia tu clave publicable por una sesión de Tile y sustituye el contenido del destino de montaje por un iframe que carga https://map-embed.kaleidr.com/?style=<style>. El mapa se dibuja dentro de ese iframe.

La sesión permite que Kaleidr compruebe la clave, su permiso y el origen de tu página, contabilice una carga de mapa y entregue el mapa base predeterminado de tu organización. La sesión no se pasa al iframe. La URL del iframe contiene el identificador de estilo y la cámara indicada (camera, pitch, bearing): no incluye ninguna clave publicable ni token de sesión, y el mapa del iframe no realiza llamadas con ellos.

Clave	Una clave publicable (kld_pk_live_…). Obligatoria.
Permiso	maps. Las claves nuevas lo incluyen por defecto.
Plan	Todos los planes, incluido Free.
Se muestra en	Un iframe de https://map-embed.kaleidr.com.
Contabilización	Una carga de mapa por sesión de Tile.
CSP	script-src https://cdn.kaleidr.com, connect-src https://api.kaleidr.com, frame-src https://map-embed.kaleidr.com.

Para ver una guía paso a paso, consulta Usar un mapa base de Kaleidr.

Montaje

Con el elemento:

<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>

Desde JavaScript:

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

Opciones

Opción de montaje	Atributo	Tipo	Predeterminado	Obligatorio	Descripción
product	product	'tile'	ninguno	sí	Selecciona Tile.
publishableKey	publishable-key	cadena	ninguno	sí	Clave kld_pk_… con el permiso maps. Las claves de servidor (kld_sk_…) se rechazan en el navegador antes de enviar cualquier solicitud.
styleId	style-id	cadena	mapa base predeterminado de la organización, si existe	recomendado	Identificador de estilo de la tabla siguiente o URL completa https:// de un documento de estilo. Debe coincidir con ^[A-Za-z0-9._:/~-]{1,200}$.
center	center	[longitude, latitude]; el atributo usa "longitude,latitude"	vista predeterminada del estilo	no	Centro inicial.
zoom	zoom	número	vista predeterminada del estilo	no	Zoom inicial. Se ignora en el montaje si no se proporciona también center.
pitch	pitch	número, grados	vista predeterminada del estilo	no	Inclinación inicial.
bearing	bearing	número, grados	vista predeterminada del estilo	no	Rotación inicial.
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	no	Destino del intercambio de sesión. Debe incluir la ruta /inference-api. No hace falta en producción.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	no	Origen desde el que se carga el iframe; solo se usa el origen. Es el servidor de la página del mapa, no de sus datos.
base	base	URL	https://cdn.kaleidr.com	no	Origen desde el que el SDK carga tile.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.

shareId, theme, map, mapTarget, contained y tileBase no tienen efecto sobre un montaje de Tile.

Identificadores de estilo

style-id	Aspecto
kaleidr-morning	Luminoso: fondo blanco, agua cian y carreteras blancas.
kaleidr-afternoon	Fondo de tono medio, vegetación verde y carreteras grises.
kaleidr-evening	Hora dorada: tonos cálidos de arena y oliva.
kaleidr-night	Azul marino y carbón oscuros, con autopistas ámbar.
kaleidr-plain	Lienzo blanco con límites y nombres de lugares. Los edificios 3D aparecen desde el zoom 15.
kaleidr-editorial	Paleta de tarde sin etiquetas, para mapas pequeños o decorativos.

Reglas:

• Los identificadores deben coincidir exactamente y distinguen mayúsculas y minúsculas. No existen alias cortos.
• Si se omite styleId, se utiliza el mapa base predeterminado configurado por la organización y recibido en la sesión. Si no existe, el iframe muestra «Couldn't find a map id in the URL.». Proporciona styleId para no depender de la configuración de la cuenta.
• Un styleId explícito siempre prevalece sobre el predeterminado de la organización.
• Un identificador inexistente produce un iframe vacío y un mensaje kaleidr-embed:error con el código maplibre_error.
• Un valor con caracteres no permitidos impide el montaje. La consola muestra [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.. Por eso una URL de estilo no puede llevar una cadena de consulta.

Cámara

La cámara inicial usa la vista predeterminada del estilo, y cada campo que proporciones sustituye el valor correspondiente. Si el estilo no tiene vista predeterminada, muestra todo el mundo: centro [0, 20], zoom 2, sin inclinación ni rotación.

• center indica primero la longitud: [-0.1276, 51.5072] corresponde a Londres.
• Durante el montaje, zoom solo se utiliza junto con center.
• pitch y bearing son independientes de center.

Dimensiones

• El iframe ocupa el 100 % del ancho del destino de montaje, carece de bordes y tiene esquinas redondeadas.
• Su altura ocupa el 100 % del destino si este tiene altura en el momento del montaje; de lo 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) y overflow:hidden.
• <kaleidr-map> usa display:block por defecto, de modo que se le puede dar una height. Asigna una altura. Los ejemplos también declaran display:block para Safari anterior a la versión 16.4, donde el elemento permanece en línea.

Controlador

Kaleidr.mount devuelve el controlador de forma síncrona. Consulta la matriz del controlador para todos los productos.

Miembro	En Tile
handle.product	'tile'
handle.setCamera(camera)	Mueve el mapa.
handle.setStyle(style)	Cambia el mapa base sin volver a montarlo.
handle.setTheme(theme)	No compatible; muestra una advertencia y no hace nada.
handle.destroy()	Elimina el iframe y detiene las renovaciones de sesión.

setStyle(style)

handle.setStyle('kaleidr-night');

Acepta un identificador de estilo o una URL completa, resueltos como styleId en el montaje. El iframe no se vuelve a cargar, la cámara mantiene su posición y no se contabiliza ninguna carga de mapa. Tile es el único producto que admite setStyle.

setCamera(camera)

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

Campo	Tipo	Descripción
center	[number, number]	Longitud, latitud.
zoom	número	Nivel de zoom. A diferencia del montaje, aquí 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. Si se omite o es 0, el cambio es instantáneo.

Todos los campos son opcionales; los omitidos mantienen su valor actual.

Momento de ejecución

Puedes llamar a setCamera y setStyle en cualquier momento después de que Kaleidr.mount devuelva el controlador, incluso en la línea siguiente. Las llamadas realizadas antes de que el mapa del iframe esté listo se conservan y aplican en orden cuando el mapa informa que está preparado. Se guardan las últimas 256. Si no hay confirmación tras una espera limitada, normalmente 10 segundos desde que se carga el iframe, se envían igualmente y aparece una advertencia en consola. No necesitas esperar al mensaje kaleidr-embed:ready. Para definir la vista y el estilo iniciales, sigue siendo preferible usar opciones de montaje, de modo que el mapa se abra directamente con ellos.

Atributos del elemento después del montaje

En un <kaleidr-map product="tile"> montado, cambiar center, zoom, pitch o bearing mueve el mapa sin animación. Cambiar style-id, publishable-key u otro atributo no produce ningún efecto.

Mensajes del 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 es el identificador o URL del estilo proporcionado. Con no_id vale null, el iframe muestra «Couldn't find a map id in the URL.» y no envía 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 se envía una vez cuando el mapa ya se ha dibujado; no se repite tras setStyle.
• maplibre_error puede recibirse varias veces, antes o después de ready.
• El iframe se crea con loading="lazy", por lo que los mensajes no llegan hasta que se aproxima al área visible.
• Una sesión rechazada no produce mensajes porque no se crea el iframe; consulta el error de la consola.
• El iframe envía otros mensajes cuyo type empieza por kaleidr-embed:. El SDK los usa para conectar un panel de Chat al mapa; no forman parte del contrato público.

Sesiones y contabilización

Por cada montaje de Tile, el SDK envía

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

{"product":"tile"}

y recibe

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

basemap_style_id es el mapa base predeterminado de tu organización; vale null cuando no hay ninguno definido.

Cada intercambio correcto con "product":"tile" contabiliza una carga de mapa para tu organización. Los intercambios ocurren:

Cuándo	Recuento
Al montar	1
90 segundos antes de que expire la sesión, mientras permanezca montado	1 cada vez
Cuando la pestaña vuelve a estar visible y faltan 90 segundos o menos para expirar, o ya expiró	1
En un nuevo montaje después de destroy(), o al volver a insertar un elemento eliminado	1

Notas:

• Una renovación fallida se reintenta cada 30 segundos; no elimina el mapa ya visible.
• Si falla el primer intercambio, falla el montaje y no se reintenta automáticamente. Vuelve a montar para intentarlo de nuevo.
• destroy() detiene las renovaciones.
• Los movimientos de cámara, cambios de estilo e interacciones del visitante no se contabilizan.

Un intercambio de Tile se rechaza por la primera causa aplicable de esta lista:

Estado	detail	Causa
403	publishable_key_required	La clave no es publicable.
403	origin_required	La solicitud no incluía un origen.
403	origin_not_allowed	El origen de la página no está en la lista de orígenes permitidos de la clave.
403	product_not_allowed	La clave está limitada a otros productos.
403	tier_capability_not_allowed	El plan no permite este producto.
403	insufficient_scope	La clave carece del permiso maps.
429	map_load_quota_exceeded	Se agotaron las cargas de mapa de la organización.

Antes de aplicar esas comprobaciones, el intercambio responde 404 sessions_disabled si está desactivado en la plataforma, o 503 sessions_not_configured si hay un fallo de plataforma. Ninguno de esos errores se debe a la clave. Consulta la lista completa en Errores.

Integración con Chat

Un montaje de Chat puede controlar un elemento Tile. Asigna un id al elemento Tile y dirige a él el atributo map-target de Chat (opción mapTarget):

<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>

En un mapa Tile, el asistente dibuja pines con ventanas emergentes, encuadra los lugares con la cámara y dibuja rutas, el contorno de áreas como una ciudad y posiciones de vehículos en tiempo real. Consulta Usar un mapa base de Kaleidr para el tutorial, Temas y diseño para la disposición y Referencia de Chat para sus opciones.

Mensajes de consola

Mensaje	Significado
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	El elemento no tiene un product válido; no se monta.
[kaleidr:tile] kaleidr session exchange failed (<status>)	Intercambio rechazado. Consulta el motivo en la respuesta de la pestaña Red: detail para 403 y map_load_quota_exceeded; error para 429 rate_limited.
Un error CORS para …/sdk/sessions, seguido de un error de obtención de [kaleidr:tile]	Clave desconocida o revocada, u origen no permitido. Como una denegación por origen carece de cabeceras CORS, el navegador oculta la respuesta al 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.	Se proporcionó una clave de servidor; no se envía ninguna solicitud.
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId tiene un carácter no permitido.
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount no encontró ningún elemento para el selector.
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	No se pudo cargar el paquete de Tile.
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	Se llamó a un método no admitido por Tile.
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	La página usa un tile.js antiguo de la caché. Recarga sin caché.

No disponible

• Añadir marcadores, capas o ventanas emergentes propios al mapa.
• Eventos de clics, movimientos de cámara o selecciones.
• Leer de vuelta la posición de la cámara.
• Usar el mapa sin el iframe.

Relacionado

• Usar un mapa base de Kaleidr
• El elemento <kaleidr-map>
• El cargador, kaleidr.js
• Cuotas y límites de tasa