kaleidr.js — el cargador

Una sola etiqueta script instala window.Kaleidr y define el elemento <kaleidr-map>:

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

La fachada es un cargador ligero. Solo gestiona: versión, configuración, carga de scripts, el registro de productos, transferencia de claves, selección del método de integración, ciclo de vida del montaje, normalización de errores y el indicador de dormancy. El comportamiento real de cada producto vive en su propio paquete, que se carga de forma diferida por URL en el primer uso.

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

Devuelve un handle de forma síncrona mientras el paquete del producto se carga en segundo plano; las llamadas anteriores a la carga se ponen en cola y se ejecutan al estar listo.

Opciones

Opción	Tipo	Notas
product	'chat' | 'viewer' | 'editor' | 'tile'	Obligatorio. Selecciona el paquete + el método de integración predeterminado.
publishableKey	string	Clave de navegador publishable (kld_pk_live_…). Obligatoria para chat/editor/tile; viewer no debe recibir una clave y la rechaza con product_not_allowed. El SDK intercambia la clave por una sesión de corta duración vinculada al origen en tiempo de ejecución.
apiKey	string	Alias obsoleto de publishableKey. También acepta una clave heredada kld_live_….
shareId / mapId	string	Solo Viewer. Obligatorio — omitirlo provoca un error al cargar el paquete.
styleId	string	Tile/editor. Tile: un ID de estilo de mapa base de Kaleidr (por defecto, el canvas predeterminado de viewer). Editor: un ID de estilo o una URL completa de estilo — si se omite, se aplica el valor predeterminado guardado de la organización y después kaleidr-morning.
map	map instance	Chat: tu mapa Mapbox / MapLibre / Google activo dentro de la página al que se adjuntará.
mapTarget	string	Chat: selector CSS de un elemento de mapa host (ruta declarativa).
contained	boolean	Solo Chat. Predeterminado false. Acopla el panel dentro del elemento de montaje en lugar de dejarlo flotando en document.body — sin esto, el panel sale del diseño y parece roto.
center zoom		Cámara inicial (viewer, editor, tile).
pitch bearing		Cámara inicial en viewer, editor y tile.
theme	object or JSON object string	Conjunto de tokens CSS (p. ej. { '--kd-accent': '#2da84a' }). Chat también permite actualización en vivo mediante el handle. Los temas con nombre en formato string no se admiten; pasar un string simple registra una advertencia y se ignora.
doorway	'iframe' | 'attach'	Vía de escape — sustituye el valor predeterminado del producto.
base	string	Sustituye el origen CDN desde el que se cargan los paquetes (dev / self-host).
viewerBase	string	Viewer/tile: el origen que carga el iframe. Distinto de base — el iframe nunca apunta al CDN.
tileBase	string	Editor: el CDN de tiles utilizado para resolver los valores styleId del catálogo. Predeterminado https://tile.kaleidr.com.
apiBase	string	Debe incluir la ruta del servicio. Predeterminado https://api.kaleidr.com/inference-api; un origen simple como https://api.kaleidr.com devuelve 404 durante el intercambio de sesión. Se aplica a chat, editor y tile — cualquier producto que realice un intercambio de sesión.
enabled	boolean	Sustitución de dormancy por montaje.

KaleidrHandle

La forma del handle es un superset — cada producto implementa únicamente los métodos que puede admitir. Consulta Handle matrix para ver qué hace cada método en cada producto.

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

Actualmente, llamar a un método no admitido registra una advertencia [kaleidr] y vuelve — el cargador no lanza errores. Ese comportamiento forma parte del contrato del alias principal v1.

Kaleidr.init()

Actualiza cualquier <kaleidr-map> que ya esté en el DOM. Se ejecuta automáticamente al cargar; llámalo después de insertar elementos dinámicamente.

Kaleidr.enable(on = true)

El SDK está activo de forma predeterminada — no necesitas habilitar nada, y el quickstart funciona tal como está escrito.

enable() existe como interruptor de apagado: pasar false impide que mount() cargue cualquier paquete, por lo que puedes colocar las integraciones detrás de un banner de consentimiento o desactivarlas en una página sin eliminar el marcado. El mismo interruptor está disponible como window.__KALEIDR_EMBED_ENABLED__ = false (antes de ejecutar el script) o mediante el atributo flag / la opción enabled en cada montaje.

Kaleidr.version

La cadena de versión del cargador.

Sustituir la base del CDN

Para desarrollo local o alojamiento propio, apunta el cargador a otro origen:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>