Integrar el editor de mapas

Al terminar esta guía, tu página mostrará las herramientas de edición de Kaleidr sobre un mapa base de Kaleidr, con el aspecto de tu marca. Funciona en todos los planes, incluido Free. Necesitas una clave publicable con el permiso design, incluido por defecto en las claves nuevas.

Las modificaciones no se guardan

El editor integrado conserva el trabajo únicamente en la memoria de la página. No se guarda, exporta ni publica nada desde el embed y tu página no recibe callbacks de los cambios. Recargar o llamar a handle.destroy() descarta las modificaciones. Si necesitas mapas persistentes, créalos en Kaleidr Studio e insértalos con Viewer.

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, como http://localhost:3000, debe estar entre los orígenes permitidos de la clave. Una clave sin orígenes permitidos funciona en cualquier sitio.
Una forma de servir la página por HTTP, como npx serve ..
Si hay una Política de seguridad de contenido, autoriza las directivas del editor de Política de seguridad de contenido. El editor se ejecuta en tu página, por lo que requiere entradas connect-src, img-src, worker-src, font-src y style-src que los productos iframe no necesitan.
No debe haber otro editor de Kaleidr en la misma página.

Paso 1: Añadir un contenedor con tamaño y montar el editor

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

Resultado esperado: un mapa base Kaleidr a escala mundial llena el contenedor (kaleidr-morning, salvo que la organización tenga otro predeterminado), con un botón Create sobre el mapa. Pulsa Create para abrir la barra lateral con herramientas de texto, imágenes, marcadores y ventanas emergentes.

El contenedor debe tener altura. El editor ocupa el 100 % del ancho y alto del contenedor y sus paneles permanecen dentro.

También puedes usar el elemento. Por defecto tiene display:block, por lo que la altura se aplica; el ejemplo escribe display:block y lo declara explícitamente para Safari anterior a 16.4:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

Paso 2: Elegir el mapa base y la cámara inicial

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

Resultado esperado: un mapa base oscuro sobre el centro de Londres, inclinado y girado.

Cómo se elige el mapa base:

styleId, si lo indicas. Utiliza un identificador como kaleidr-morning, kaleidr-afternoon, kaleidr-evening, kaleidr-night, kaleidr-plain o kaleidr-editorial. La lista con descripciones está en Referencia de Tile.
Si no, el mapa base predeterminado de tu organización, cuando exista.
En último caso, kaleidr-morning.

Los valores predeterminados de cámara son centro [0, 0], zoom 2, inclinación 0 y orientación 0. A diferencia de Viewer y Tile, el editor acepta zoom sin center.

Las opciones de cámara pasadas a Kaleidr.mount que no sean números finitos se ignoran y se informa en la consola. En el elemento, los atributos de cámara que no sean numéricos se descartan sin aviso.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

Paso 3: Personalizar los paneles (opcional)

Pasa theme para adaptar los paneles del editor a tu producto. Es un objeto con hasta 17 claves de tema reconocidas. Las demás se ignoran.

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

Resultado esperado: la herramienta activa, los indicadores de foco y los botones principales usan los colores de tu marca y los paneles su tipografía.

Las 17 claves están en Referencia del editor.

Tres aspectos importantes:

Los valores son CSS. brandColor acepta colores CSS, cardRadius longitudes CSS y fontPrimary valores font-family. Debes cargar la fuente por tu cuenta.
El tema se aplica a todo el documento mientras el editor está montado y se restaura cuando se destruye. No cambia tus estilos salvo que utilicen las mismas propiedades personalizadas.
El tema solo se lee al montar. handle.setTheme no se admite en el editor. Para cambiarlo, destruye y vuelve a montar el editor, lo que descarta las modificaciones.

En el elemento, theme es una cadena JSON:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

Paso 4: Mover la cámara desde tu página (opcional)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

Resultado esperado: el mapa vuela a París. Todo lo que haya colocado el usuario permanece en su posición.

setCamera es el único modo de actuar sobre el mapa del editor desde tu página. El handle no expone el objeto de mapa.

Paso 5: Desmontar el editor

handle.destroy();

destroy() elimina el editor, su mapa y los paneles del contenedor y restaura los valores del tema. Se descartan las modificaciones.

En aplicaciones de una sola página, llama a destroy() cuando se elimine la ruta o componente que contiene el editor. Si utilizas el elemento, quitarlo del documento hace lo mismo. Consulta Integración con frameworks.

Como solo puede haber un editor en la página, destruye el actual antes de montar otro.

Página completa

Guarda esto como index.html, introduce tu clave y sirve el archivo por HTTP desde un origen autorizado.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

Cómo funciona

Tema	Comportamiento
Dónde se ejecuta	Dentro del documento. El canvas y los paneles del editor son elementos del destino de montaje.
Sesión	El SDK intercambia la clave por una sesión breve antes de iniciar el editor y la renueva mientras está montado.
Modificaciones	Solo en memoria; no se guardan, exportan, publican ni comunican a tu página.
Mapa base	La página lo carga desde `https://tile.kaleidr.com`. Queda fijo al montar.
Tema	Se aplica a todo el documento al montar y se restaura al destruir.
Cámara	Se define al montar y se mueve con `handle.setCamera`.
Uso	La solicitud de sesión del editor no cuenta como carga de mapa y el editor integrado no tiene funciones de IA que gasten créditos. Las solicitudes del mapa base que incluyen tu clave suman cargas de mapa por lotes: se cuenta una por cada 20 solicitudes en una hora. Consulta Cargas de mapa.
Señales	Ninguna. No hay evento de preparado, cambios ni callback de error.

Qué informar a los usuarios

El editor no advierte que el trabajo es temporal. Si los usuarios dedicarán tiempo a editar, indícalo en tu interfaz, como hace la página de ejemplo, para que no esperen recuperar su mapa más adelante.

Comprobar que funciona

En la página: el mapa base ocupa el contenedor, Create abre la barra lateral y puedes colocar texto o marcadores.
En la consola: no hay líneas que contengan [kaleidr.
En Network: kaleidr.js y editor.js de https://cdn.kaleidr.com; un POST …/sdk/sessions con 200; y solicitudes a https://tile.kaleidr.com para el estilo y teselas.

Si no funciona

El SDK registra montajes fallidos en la consola como [kaleidr:editor] …. Si se rechaza una sesión, solo muestra el estado HTTP. El motivo aparece en la respuesta de sessions en Network. Un 403 incluye el código en detail; un 429, en error, con una frase en detail.

Síntoma	Causa	Solución
No aparece nada; `[kaleidr:editor] …` y `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	No se pasó una clave.	Pasa `publishableKey`.
No aparece nada, error CORS de `…/sdk/sessions` y error `[kaleidr:editor]`	Clave desconocida o revocada, u origen no permitido.	Comprueba la clave y añade el origen exacto (protocolo, host, puerto) en kaleidr.com/api-keys. Espera unos minutos.
`[kaleidr:editor] kaleidr session exchange failed (403)`	Falta `design` (`insufficient_scope`), la clave es para otros productos (`product_not_allowed`) o el plan no permite la solicitud (`tier_capability_not_allowed`).	Lee `detail` en Network y crea una clave con los permisos predeterminados.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Se pasó una clave de servidor.	Usa una clave publicable y rota la de servidor si fue pública.
El contenedor está vacío y sin altura	El destino de montaje no tiene altura.	Establece una. En Safari anterior a 16.4, añade también `display:block`.
Paneles visibles y mapa en blanco; 429 de `https://tile.kaleidr.com` con `"error":"tile_access_restricted"`	El servidor de mapas base rechazó las solicitudes.	Confirma que la clave es publicable y válida y el origen está permitido, espera unos minutos tras crearla o editarla y recarga. Si persiste, contacta con soporte.
Paneles visibles, pero mapa en blanco con error de Política de seguridad de contenido	La política bloquea el mapa, el worker o sus imágenes.	Añade las directivas del editor de Política de seguridad de contenido.
El editor no tiene estilo	La política bloquea CSS inline.	Autoriza `'unsafe-inline'` en `style-src`.
Un segundo editor falla o el primero deja de funcionar	Hay dos editores montados.	Destruye el primero antes de montar el segundo.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	El tema solo puede establecerse al montar.	Pasa `theme` durante el montaje.
`[kaleidr] theme string must be JSON…`	El atributo `theme` no contiene un objeto JSON.	Usa comillas simples fuera y dobles dentro del JSON.
Una clave de tema no surte efecto	La clave no está entre las 17 o está mal escrita. Las desconocidas se ignoran.	Compruébala en la lista.
Desaparecieron las modificaciones	Se recargó la página, se destruyó el editor o se quitó o movió el elemento.	Es esperado; consulta la advertencia inicial.

Limitaciones

Nada se guarda, exporta ni publica desde el embed.
No hay callback de cambios, señal de listo ni callback de error.
No hay acceso al objeto de mapa, de modo que no se pueden añadir capas propias ni leer lo que se dibujó.
No hay pestaña Data, catálogo de diseños, panel de IA, biblioteca de modelos 3D, compartir ni proyectos. La barra contiene Text, Image, Marker, Popup, Background, Layer, Design y Legend; consulta Alcance.
Solo un editor por página.
No se puede cambiar el mapa base ni el tema después de montar.

Próximos pasos

Referencia del editor: opciones y claves de tema.
Integración con frameworks: montar y desmontar en React, Next.js o Vue.
Política de seguridad de contenido: directivas del editor.
Insertar un mapa publicado: para mapas persistentes.

Antes de empezar​

Paso 1: Añadir un contenedor con tamaño y montar el editor​

Paso 2: Elegir el mapa base y la cámara inicial​

Paso 3: Personalizar los paneles (opcional)​

Paso 4: Mover la cámara desde tu página (opcional)​

Paso 5: Desmontar el editor​

Página completa​

Cómo funciona​

Qué informar a los usuarios​

Comprobar que funciona​

Si no funciona​

Limitaciones​

Próximos pasos​