Usar un mapa base de Kaleidr

Al terminar esta guía, tu página mostrará un mapa base interactivo de Kaleidr con el estilo y la cámara que elijas, y tu código podrá mover la cámara y cambiar de estilo. Funciona en todos los planes, incluido Free. Necesitas una clave publicable con el permiso maps, incluido por defecto en las claves nuevas.

Antes de empezar

Una clave publicable (kld_pk_live_…) de kaleidr.com/api-keys. Consulta Obtener una clave API.
El origen de la página de prueba, por ejemplo http://localhost:3000, debe figurar entre los orígenes permitidos de la clave. Una clave sin restricciones de origen funciona en cualquier sitio.
Una forma de servir la página mediante HTTP, por ejemplo npx serve .. Una página abierta desde el disco no tiene un origen válido, por lo que una clave con restricciones lo rechazará.
Si tu sitio utiliza una Política de seguridad de contenido, incluye https://cdn.kaleidr.com en script-src, https://api.kaleidr.com en connect-src y https://map-embed.kaleidr.com en frame-src. Consulta Política de seguridad de contenido.

Paso 1: Añadir el mapa

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

Resultado esperado: aparece «Loading map…» y después un mapa base luminoso. En la pestaña Network se ve un POST a https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions con estado 200, seguido de una solicitud de documento a https://map-embed.kaleidr.com/. La URL del marco contiene el identificador de estilo, pero ninguna credencial: la clave se envía solo al solicitar la sesión y el token de sesión no se incluye en la URL del marco.

El elemento necesita una altura; de lo contrario, el mapa adopta una altura fija de 500 píxeles. <kaleidr-map> usa display:block por defecto, por lo que se aplica la altura. Mantén display:block también en el estilo: no perjudica y cubre Safari anterior a 16.4, donde el elemento sigue siendo inline e ignora height.

Paso 2: Elegir un estilo

Configura style-id con uno de los estilos generales:

`style-id`	Aspecto
`kaleidr-morning`	Claro: fondo blanco, agua cian y carreteras blancas.
`kaleidr-afternoon`	Fondo de tono medio, vegetación verde y carreteras grises.
`kaleidr-evening`	Luz de atardecer: arena cálida y tonos oliva.
`kaleidr-night`	Azul marino y carbón oscuros, con autopistas ámbar.
`kaleidr-plain`	Lienzo blanco con fronteras 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.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

Resultado esperado: la misma zona del mapa con una paleta oscura.

Indica siempre style-id. Si lo omites, se usará el mapa base predeterminado de tu organización, si existe. Si no hay ninguno configurado, el marco mostrará «Couldn't find a map id in the URL.».

Los identificadores de estilo deben coincidir exactamente: no existen alias abreviados; night no equivale a kaleidr-night.

Paso 3: Configurar la cámara

Sin indicar una cámara, el mapa se abre con la vista predeterminada del estilo, que suele mostrar el mundo entero. Usa center (longitud primero, latitud después) y zoom para abrir una zona específica. pitch inclina la vista y bearing la gira.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

Resultado esperado: el centro de Londres con inclinación y rotación.

zoom se ignora si no indicas también center. pitch y bearing pueden usarse por separado.

Paso 4: Mover la cámara y cambiar de estilo desde el código

El elemento ofrece la modalidad declarativa. Para controlarlo desde JavaScript, monta el mapa mediante Kaleidr.mount y conserva el objeto de control que devuelve.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

Resultado esperado: cada botón modifica el mapa sin reemplazarlo. El iframe no se vuelve a cargar y no aparece otra solicitud de sesión en Network.

Ten en cuenta lo siguiente:

setCamera y setStyle son métodos del objeto de control, no del elemento.
setStyle solo existe en Tile. En otros productos emite una advertencia y no hace nada.
Puedes llamar a los métodos del objeto de control en cualquier momento después de que Kaleidr.mount regrese. Las llamadas anteriores a que el mapa del iframe esté listo se guardan y aplican en orden cuando llega la señal de disponibilidad; no necesitas esperar el mensaje kaleidr-embed:ready del paso 6. Para elegir el estilo y la cámara iniciales, usa las opciones de montaje.
En un elemento ya montado, cambiar center, zoom, pitch o bearing mueve el mapa. Cambiar style-id no tiene efecto.

Paso 5: Asociar un panel de chat al mapa (opcional)

Un panel Kaleidr Chat puede utilizar un mapa Tile como destino: dibuja los lugares mencionados en sus respuestas como marcadores y ajusta la cámara para mostrarlos. Envuelve el elemento Tile en un contenedor posicionado, coloca encima un elemento de chat e indica el elemento Tile en map-target.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               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>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

Resultado esperado: el panel de chat aparece en la esquina superior izquierda del mapa. Pregunta «coffee near Covent Garden» y aparecerán marcadores en el mapa Tile.

Qué hacen los atributos y estilos del elemento de chat:

Parte	Finalidad
`map-target="#basemap"`	Selector CSS del elemento Tile que controlará el chat.
`contained`	Sitúa el panel dentro del elemento de chat. Si se omite, el panel se fija en la esquina superior izquierda de la ventana.
`position:absolute; inset:0`	Extiende el elemento de chat sobre el mapa para colocar el panel en su esquina.
`z-index:1`	Mantiene la capa de chat por encima del mapa.
`pointer-events:none`	Permite arrastrar y ampliar el mapa fuera del panel. El panel sigue siendo interactivo.

Notas:

La misma clave sirve para ambos elementos porque una clave predeterminada contiene los permisos maps y ai. El elemento de chat solicita su propia sesión y cada pregunta consume créditos de IA.
El orden de los dos elementos es indiferente. El chat busca su mapa cuando lo necesita.

Las opciones de diseño y tema del panel se explican en Temas y disposición. Consulta Capacidades y límites para saber qué puede y qué no puede hacer el asistente.

Paso 6: Saber cuándo se ha cargado el mapa (opcional)

El SDK no proporciona una promesa ready y el elemento no emite eventos. El iframe envía un mensaje a la página cuando el mapa se ha dibujado y otro si alguna parte no se puede dibujar:

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

Si falla la solicitud de sesión, no se genera ningún mensaje porque no se crea el iframe. El fallo aparece en la consola. Consulta Si no funciona.

Una página completa

Guarda esto como index.html, introduce tu clave y sirve la carpeta por HTTP desde un origen permitido por la clave.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

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

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

Cómo funciona

Tema	Comportamiento
Sesión	Antes de crear el iframe, el SDK intercambia la clave por una sesión Tile de corta duración y la renueva mientras el mapa siga montado. El intercambio valida la clave y contabiliza una carga de mapa. La sesión no se transmite al iframe, cuya URL solo contiene el estilo y la cámara.
Vista inicial	La cámara indicada o, en su defecto, la vista predeterminada del estilo.
Desplazamiento	Con el puntero sobre el mapa, la rueda del ratón amplía el mapa. Con el puntero fuera del mapa, el desplazamiento mueve la página. En pantallas táctiles, arrastrar mueve el mapa y pellizcar lo amplía.
Altura	Usa la altura del elemento de montaje si existe al montarlo; si no, 500 píxeles fijos.
Carga	El iframe se carga de forma diferida cuando se aproxima al área visible.
Eliminación	`handle.destroy()` elimina el iframe y detiene las renovaciones de sesión. Quitar un elemento `<kaleidr-map>` hace lo mismo.
Reinserción	Volver a insertar o mover a otro contenedor un elemento eliminado lo monta de nuevo y crea otra sesión.

Cómo se cuentan las cargas de mapa

Se registra una carga de mapa cada vez que el SDK obtiene una sesión Tile:

Evento	Cargas de mapa
Se monta el mapa	1
Se renueva la sesión mientras el montaje sigue activo	1 por renovación
Destruyes el montaje y lo vuelves a crear, o reinsertas el elemento	1
`setCamera`, `setStyle`, desplazamiento o zoom	0

Las sesiones duran 15 minutos por defecto y el SDK las renueva 90 segundos antes de que caduquen, tanto en primer plano como en segundo plano. Una visita de pocos minutos consume una carga; una página abierta una hora consume aproximadamente cinco.

Para reducir el consumo:

Destruye el montaje cuando el mapa quede oculto definitivamente, por ejemplo al cerrar un diálogo, cambiar de ruta o eliminar una pestaña.
No vuelvas a crear el elemento en cada renderizado. Para React, Vue y otros frameworks, consulta Integración con frameworks.
Usa setStyle para cambiar el estilo, en vez de montar el mapa de nuevo.

Si tu organización agota sus cargas de mapa durante el período, el sistema rechaza nuevas sesiones con HTTP 429 y {"detail":"map_load_quota_exceeded"}. Un mapa que ya esté visible permanece en pantalla; un montaje nuevo no muestra nada. Consulta Cuotas y límites de frecuencia. ({"detail":"map_load_quota_exceeded"})

Comprobar que funciona

En la página: el mapa es interactivo y muestra los créditos cartográficos en la parte inferior.
En la consola: no hay líneas que contengan [kaleidr.
En Network: se cargan kaleidr.js y tile.js desde https://cdn.kaleidr.com; hay un POST …/sdk/sessions con estado 200 y un JSON con session_token y expires_in; además, una solicitud de documento a https://map-embed.kaleidr.com/?style=….
En el listener: un mensaje kaleidr-embed:ready cuyo source es "tile".

Si no funciona

El SDK registra los fallos de montaje como [kaleidr:tile] … en la consola. Si se rechaza una sesión, solo registra el estado HTTP. El motivo figura en la respuesta, que puedes leer seleccionando la solicitud sessions en Network. Un 403 incluye el código en detail, al igual que map_load_quota_exceeded. Un 429 rate_limited lo incluye en error.

Síntoma	Causa	Solución
No aparece nada; la consola indica un error CORS de `…/sdk/sessions` y un error `[kaleidr:tile]`	La clave es desconocida o está revocada, o el origen no está permitido. El rechazo no incluye cabeceras CORS.	Comprueba la clave y añade el origen exacto (protocolo, host y puerto) en kaleidr.com/api-keys. Espera unos minutos y vuelve a intentarlo. Network mostrará 401 o 403.
`[kaleidr:tile] kaleidr session exchange failed (403)`	Falta el permiso `maps` (`insufficient_scope`), la clave se limita a otros productos (`product_not_allowed`) o el plan no admite la solicitud (`tier_capability_not_allowed`).	Consulta `detail` en Network y crea una clave con los permisos predeterminados.
`[kaleidr:tile] kaleidr session exchange failed (429)`	Se agotó la cuota de cargas (`map_load_quota_exceeded`) o hubo demasiadas solicitudes (`rate_limited`).	Comprueba `detail` en el primer caso y `error` en el segundo. Consulta Cuotas y límites de frecuencia.
La solicitud `sessions` devuelve 404	La sobrescritura de `api-base` no incluye `/inference-api`.	Elimina la sobrescritura o utiliza `https://api.kaleidr.com/inference-api`.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Se proporcionó una clave de servidor que el SDK rechaza antes de hacer solicitudes.	Usa una clave publicable. Rota la de servidor si alguna vez se publicó.
`[kaleidr:tile] Kaleidr tile: invalid style "…"…`	`style-id` contiene un carácter no permitido, como espacio o `?`.	Usa uno de los identificadores del paso 2.
El marco muestra «Couldn't find a map id in the URL.» y el listener recibe `code: 'no_id'` e `id: null`	No hay `style-id` ni mapa base predeterminado para la organización.	Indica `style-id`.
El marco está vacío y llega `kaleidr-embed:error` con `maplibre_error`	El estilo no existe, normalmente por un identificador mal escrito.	Usa uno del paso 2.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	Falta `product` o está mal escrito.	Usa `product="tile"`.
El mapa siempre mide 500 píxeles de alto	El elemento no tenía altura al montarse, tiene `display:inline` o Safari es anterior a 16.4 sin `display:block`.	Establece `display:block` y una altura. `height`
Un recuadro vacío con errores de Política de seguridad de contenido	La política bloquea el loader, la sesión o el iframe.	Autoriza los tres dominios de Antes de empezar.
`setStyle` o `setCamera` no funciona	Se llamó en el elemento o el mapa aún no está listo.	Llama al método en el objeto de control de `Kaleidr.mount`. Consulta `kaleidr-embed:error` y la consola; las llamadas previas se aplican cuando el mapa esté listo. Si el mapa no comunica que está listo tras una espera limitada, normalmente 10 segundos desde la carga del iframe, la llamada se envía igualmente y la consola muestra `[kaleidr] the map frame has not reported ready`: si el marco muestra un error, no hay ningún mapa que mover o modificar.
Cambiar `style-id` en el elemento no funciona	El elemento solo lee `style-id` al montarse.	Usa `handle.setStyle` o crea un elemento nuevo.

Limitaciones

Tu página no puede añadir marcadores, capas ni ventanas emergentes a un mapa Tile y no recibe eventos de clic o de cámara. Un panel de chat asociado sí puede ubicar lugares.
No existe un método para leer el estado actual de la cámara.
Tile es el producto admitido para mostrar un mapa base de Kaleidr.
Un mapa Tile no se muestra si el origen de la página no está autorizado por la clave.

Próximos pasos

Referencia de Tile para todas las opciones, atributos y mensajes.
Integración con frameworks para montar y desmontar mapas desde React, Next.js y Vue sin cargas adicionales.
Chat para añadir el asistente al mapa.
Cuotas y límites de frecuencia para consultar las cuotas de cargas de mapa.

Antes de empezar​

Paso 1: Añadir el mapa​

Paso 2: Elegir un estilo​

Paso 3: Configurar la cámara​

Paso 4: Mover la cámara y cambiar de estilo desde el código​

Paso 5: Asociar un panel de chat al mapa (opcional)​

Paso 6: Saber cuándo se ha cargado el mapa (opcional)​

Una página completa​

Cómo funciona​

Cómo se cuentan las cargas de mapa​

Comprobar que funciona​

Si no funciona​

Limitaciones​

Próximos pasos​