Versionado de la CDN

El SDK se distribuye en cinco archivos bajo una misma ruta versionada. Tu página referencia el primero, que carga los demás cuando se monta un producto.

https://cdn.kaleidr.com/embed/v1/kaleidr.js   the loader: window.Kaleidr and <kaleidr-map>
https://cdn.kaleidr.com/embed/v1/chat.js      the chat panel
https://cdn.kaleidr.com/embed/v1/viewer.js    the viewer's iframe loader
https://cdn.kaleidr.com/embed/v1/tile.js      the tile iframe loader
https://cdn.kaleidr.com/embed/v1/editor.js    the editor

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

El paquete de un producto se solicita la primera vez que se monta en una página, como máximo una vez por página. Una página que solo muestra Viewer nunca descarga chat.js ni editor.js.

Qué significa `v1`

v1 identifica un contrato, no una compilación.

Cada URL contiene un solo archivo, y cada versión publicada lo sustituye en la misma ubicación.
No hay versiones de parche ni rutas basadas en hashes. No puedes fijar /embed/v1.2.3/kaleidr.js porque esa ruta no existe.
Las correcciones y las funciones compatibles con versiones anteriores se publican en /embed/v1/, y tu página las recibe sin que tengas que modificar nada.

Kaleidr.version es una cadena útil para el diagnóstico, no un identificador de compilación descargable.

Qué permanece estable en `v1`

Estable	Significado
Las cinco URL	Seguirán funcionando.
`window.Kaleidr`	`mount`, `init`, `enable` y `version` mantienen su comportamiento documentado.
Opciones de montaje y atributos de elementos	Cada opción documentada conserva su nombre y significado.
El controlador	Todos incluyen `setCamera`, `setTheme`, `setStyle` y `destroy`. Si un producto no admite un método, este avisa y no hace nada; no lanza una excepción ni se elimina.
Los dos mensajes de iframe	`kaleidr-embed:ready` y `kaleidr-embed:error` conservan sus campos documentados.

Qué puede cambiar dentro de v1:

Incorporaciones. Pueden aparecer nuevas opciones, atributos, métodos del controlador, campos de mensajes, códigos de error y eventos de transmisión. Haz que tu código ignore los valores desconocidos: campos, códigos code y eventos no reconocidos.
Apariencia. Puede cambiar el aspecto del panel de chat, el editor o los controles del mapa.
Comportamientos no documentados. Todo lo que no se describa aquí, incluidos otros mensajes kaleidr-embed: entre el SDK y sus iframes, las variables globales de los paquetes de producto y el texto exacto de los mensajes de consola.

La API HTTP sigue la misma regla en /inference-api/b2b/v1/: v2 aparecerá solo para un cambio incompatible. Las novedades se registran en el registro de cambios.

Cómo se publica un cambio incompatible

Un cambio que rompería una integración v1 en funcionamiento no se publica en /embed/v1/. Se distribuye como una nueva versión principal, junto a la anterior:

https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js

La etiqueta v1 sigue cargando archivos v1. Cuando estés listo y hayas leído los cambios, podrás cambiar la ruta de la etiqueta de script para pasar a la nueva versión principal. El cargador solicita los paquetes de producto de su misma versión principal.

Almacenamiento en caché

Cada archivo se entrega con

Cache-Control: public, max-age=300

y la copia de la CDN se reemplaza en cada publicación.

Pregunta	Respuesta
¿Cuánto tarda una versión en llegar a un visitante?	Unos cinco minutos como máximo. Si el navegador obtuvo el archivo anterior en los últimos cinco minutos, seguirá usándolo hasta que expire su copia.
¿El visitante vuelve a descargar el SDK en cada página?	No. Durante cinco minutos se usa la copia en caché; después el navegador consulta de nuevo a la CDN.
¿Puedo almacenar los archivos en mi caché durante más tiempo?	No. Un proxy, service worker o compilación que conserve la copia servirá código obsoleto tras una actualización.
¿Puedo añadir integridad de subrecursos (`integrity="sha384-…"`)?	No. El hash cambia con cada publicación y el navegador rechaza los scripts con un hash que no coincida. Los elementos incrustados dejarían de cargar en la siguiente versión.
¿Puedo incluir `kaleidr.js` en mi propio paquete?	No, por el mismo motivo. Referencia la URL.

Si tu sitio utiliza un service worker que almacena scripts de otros orígenes, excluye https://cdn.kaleidr.com de las reglas de prioridad de caché o utiliza una estrategia con revalidación.

El cargador y los paquetes se publican por separado

Los cinco archivos se publican de forma independiente. Durante un breve período puede coexistir un kaleidr.js nuevo con un paquete antiguo de la caché del navegador, o al revés. El SDK está preparado para ello:

El cargador transmite las opciones al paquete y admite que un paquete antiguo desconozca una opción nueva.
Si llamas a un método admitido por el producto pero ausente en el paquete almacenado, no ocurre nada y la consola lo indica:
```
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …
```
Al recargar la página sin utilizar caché se obtiene el paquete actual. El problema desaparece automáticamente al caducar la copia almacenada.

Las páginas de los iframes de Viewer y Tile se sirven desde https://map-embed.kaleidr.com y también se publican por separado. La caché del SDK de tu página no las afecta.

Alojamiento propio

Puedes servir los cinco archivos desde tu propio origen para que los scripts provengan de tu dominio. Ten en cuenta la contrapartida: una copia alojada por ti deja de recibir correcciones. La API y las páginas internas de los iframes siguen actualizándose en Kaleidr, por lo que una copia que no renueves quedará desfasada.

Para alojarlos tú mismo:

Replica los cinco archivos en https://your-origin/embed/v1/. La ruta es fija; solo puede cambiar el origen.

Indica al cargador dónde están sus paquetes antes de que se ejecute:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script>
<script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>

o, por montaje, mediante la opción base o el atributo base.

Actualiza la copia periódicamente y sírvela con una duración de caché breve, como Kaleidr.

Orígenes permitidos en la sustitución de base

El cargador no descarga paquetes de cualquier origen. Una sustitución de base (variable global de página, opción base o atributo base) solo se acepta si su origen es:

la CDN de Kaleidr (https://cdn.kaleidr.com);
el origen desde el que se cargó el propio kaleidr.js; o
el origen de la propia página.

El alojamiento propio funciona cuando el cargador y los paquetes se sirven desde el mismo origen. Así ocurre en el paso 2: kaleidr.js se carga desde https://cdn.example.com, por lo que se acepta https://cdn.example.com como base. También se aceptan los paquetes alojados en el origen de la página.

Se ignora cualquier otro valor, incluso otro servidor de kaleidr.com. El elemento sigue montándose y descarga los paquetes desde https://cdn.kaleidr.com; la consola muestra:

[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.

Quedan excluidas estas dos configuraciones:

kaleidr.js cargado desde https://cdn.kaleidr.com con una base que apunta a un tercer origen. Carga también el cargador desde ese tercer origen.
El cargador en uno de tus orígenes y los paquetes en otro, sin que ninguno sea el origen de la página. Sirve los cinco archivos desde un único origen.

Si aparece esa advertencia en una página cuya política de seguridad de contenido solo permite el origen propio para scripts, la solicitud del paquete a https://cdn.kaleidr.com queda bloqueada y no se muestra nada. Corrige la base, no la política.

Lo que cambia y lo que no cambia con el alojamiento propio:

No basta con alojar kaleidr.js. Sin la sustitución de base, el cargador sigue solicitando los paquetes desde https://cdn.kaleidr.com.
Solo se utiliza el origen de base: se descarta cualquier ruta y los paquetes se solicitan en /embed/v1/ de dicho origen.
window.__KALEIDR_EMBED_BASE__ debe ser una cadena; los demás valores se ignoran.
El alojamiento propio solo cambia los scripts. El intercambio de sesión sigue usando https://api.kaleidr.com, los iframes de Viewer y Tile cargan desde https://map-embed.kaleidr.com y el mapa base de Editor desde https://tile.kaleidr.com. Tu política de seguridad de contenido debe seguir permitiendo esos orígenes.

Qué significa v1​

Qué permanece estable en v1​

Cómo se publica un cambio incompatible​

Almacenamiento en caché​

El cargador y los paquetes se publican por separado​

Alojamiento propio​

Orígenes permitidos en la sustitución de base​

Relacionado​