Versionnement du CDN

Le SDK est fourni sous forme de cinq fichiers regroupés dans un chemin versionné. Votre page référence le premier ; il charge les autres lorsqu’un produit est monté.

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>

Le bundle d’un produit est demandé lors de son premier montage sur une page, au plus une fois par page. Une page qui affiche uniquement Viewer ne télécharge jamais chat.js ni editor.js.

Ce que signifie `v1`

v1 désigne un contrat, pas une compilation.

Chaque URL contient un fichier, remplacé au même endroit à chaque publication.
Il n’existe ni versions correctives ni chemins fondés sur le hash du contenu. Il est impossible de figer /embed/v1.2.3/kaleidr.js puisque ce chemin n’existe pas.
Les correctifs et ajouts rétrocompatibles sont publiés sous /embed/v1/ ; votre page les reçoit sans modification.

Kaleidr.version est une chaîne utile aux diagnostics. Elle ne correspond pas à une compilation que vous pouvez demander.

Ce qui reste stable dans `v1`

Élément stable	Signification
Les cinq URL	Elles restent accessibles.
`window.Kaleidr`	`mount`, `init`, `enable` et `version` conservent leur comportement documenté.
Options de montage et attributs d’élément	Une option documentée garde son nom et sa signification.
Le handle	Chaque handle possède `setCamera`, `setTheme`, `setStyle` et `destroy`. Une méthode non prise en charge affiche un avertissement et ne fait rien ; elle ne lève pas d’exception et n’est pas supprimée.
Les deux messages iframe	`kaleidr-embed:ready` et `kaleidr-embed:error` conservent leurs champs documentés.

Ce qui peut changer au sein de v1 :

Ajouts. De nouvelles options, des attributs, des méthodes de handle, des champs de message, des codes d’erreur et des événements de flux peuvent apparaître. Votre code doit ignorer les données inconnues : champ de message, valeur code ou événement non reconnu.
Apparence. L’aspect du panneau de chat, de l’éditeur et des commandes de la carte peut changer.
Comportements non documentés. Tout ce que cette documentation ne décrit pas, y compris les autres messages kaleidr-embed: échangés entre le SDK et ses iframes, les variables globales définies par les bundles et le texte exact des messages de console.

L’API HTTP suit la même règle à /inference-api/b2b/v1/ : une v2 n’apparaît que pour une modification incompatible. Les changements figurent dans le journal des modifications.

Publication d’une modification incompatible

Une modification qui casserait une intégration v1 fonctionnelle n’est pas publiée sous /embed/v1/. Elle est diffusée comme une nouvelle version majeure, parallèlement à la précédente :

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

Votre balise v1 continue de charger les fichiers v1. Lorsque vous êtes prêt, après avoir lu les changements, modifiez le chemin de votre balise script pour passer à la nouvelle version majeure. Le chargeur demande les bundles correspondant à sa propre version majeure.

Mise en cache

Chaque fichier est servi avec

Cache-Control: public, max-age=300

et la copie sur le CDN est remplacée à chaque publication.

Question	Réponse
En combien de temps une version atteint-elle un visiteur ?	En cinq minutes environ. Un navigateur qui a récupéré l’ancien fichier moins de cinq minutes auparavant le conserve jusqu’à l’expiration de sa copie.
Le visiteur retélécharge-t-il le SDK sur chaque page ?	Non. Pendant cinq minutes après une récupération, le navigateur utilise son cache, puis vérifie à nouveau auprès du CDN.
Puis-je mettre les fichiers en cache plus longtemps ?	Non. Un proxy, service worker ou processus de compilation qui garde la copie trop longtemps diffusera du code obsolète après la mise à jour.
Puis-je ajouter une intégrité de sous-ressource (`integrity="sha384-…"`) ?	Non. Le hash change à chaque publication ; un navigateur refuse un script dont le hash ne correspond pas. Les intégrations cesseraient de charger dès la version suivante.
Puis-je copier `kaleidr.js` dans mon propre bundle ?	Non, pour la même raison. Référencez son URL.

Si votre site possède un service worker qui met en cache les scripts d’autres origines, excluez https://cdn.kaleidr.com de toute règle privilégiant le cache, ou adoptez une stratégie avec revalidation.

Le chargeur et les bundles sont publiés séparément

Les cinq fichiers sont publiés indépendamment. Peu après une publication, une page peut donc utiliser un kaleidr.js plus récent avec un ancien bundle en cache, ou l’inverse. Le SDK prend en charge cette situation :

Le chargeur transmet les options au bundle et accepte qu’un ancien bundle ne connaisse pas une option récente.
Si vous appelez une méthode de handle prise en charge par le produit mais absente du bundle mis en cache, elle ne fait rien et la console l’indique :
```
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …
```
Un rechargement ignorant le cache récupère le bundle actuel. La situation se résout d’elle-même lorsque la copie en cache expire.

Les pages à l’intérieur des iframes Viewer et Tile sont servies depuis https://map-embed.kaleidr.com et publiées séparément elles aussi. La mise en cache du SDK par votre page ne les affecte pas.

Auto-hébergement

Vous pouvez servir les cinq fichiers depuis votre propre origine, par exemple pour n’avoir que des scripts provenant de votre domaine. Comprenez toutefois le compromis : une copie auto-hébergée ne reçoit plus les correctifs automatiquement. L’API et les pages des iframes continuent d’évoluer chez Kaleidr ; une copie non actualisée finit par être désynchronisée.

Pour auto-héberger :

Copiez les cinq fichiers dans https://your-origin/embed/v1/. Le chemin est fixe ; seule l’origine peut changer.

Indiquez au chargeur l’emplacement de ses bundles avant son exécution :

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

ou, pour chaque montage, avec l’option base ou l’attribut base.

Recopiez les fichiers régulièrement et servez-les avec une courte durée de cache, comme Kaleidr.

Origines acceptées pour remplacer la base

Le chargeur n’accepte pas les bundles de n’importe quelle origine. Une base personnalisée (variable globale de page, option base ou attribut base) est respectée uniquement si son origine est :

le CDN Kaleidr (https://cdn.kaleidr.com) ;
l’origine depuis laquelle kaleidr.js a été chargé ; ou
l’origine de la page elle-même.

L’auto-hébergement fonctionne lorsque le chargeur et les bundles sont servis depuis la même origine. C’est la configuration de l’étape 2 : kaleidr.js vient de https://cdn.example.com, donc https://cdn.example.com est accepté comme base. Les bundles hébergés sur l’origine de la page sont également acceptés.

Toute autre valeur est ignorée, même un autre hôte kaleidr.com. L’intégration se monte tout de même, charge les bundles depuis https://cdn.kaleidr.com et affiche en console :

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

Cela exclut deux configurations :

kaleidr.js chargé depuis https://cdn.kaleidr.com avec une base pointant vers une troisième origine : chargez aussi le chargeur depuis celle-ci.
Le chargeur sur une de vos origines et les bundles sur une autre, dont aucune n’est celle de la page : servez les cinq fichiers depuis une seule origine.

Si cet avertissement apparaît sur une page dont la politique de sécurité du contenu n’autorise que votre origine pour les scripts, la requête des bundles vers https://cdn.kaleidr.com est bloquée et rien ne s’affiche. Corrigez la base, pas la politique.

Ce que l’auto-hébergement change ou non :

Héberger uniquement kaleidr.js ne suffit pas. Sans remplacement de base, le chargeur récupère toujours les bundles depuis https://cdn.kaleidr.com.
Seule l’origine de base est utilisée. Le chemin indiqué est ignoré ; les bundles sont demandés sous /embed/v1/ sur cette origine.
window.__KALEIDR_EMBED_BASE__ doit être une chaîne. Toute autre valeur est ignorée.
L’auto-hébergement déplace uniquement les scripts. L’échange de session passe toujours par https://api.kaleidr.com, les iframes Viewer et Tile par https://map-embed.kaleidr.com, et le fond de carte de l’éditeur par https://tile.kaleidr.com. Votre politique de sécurité du contenu doit continuer de les autoriser.

Ce que signifie v1​

Ce qui reste stable dans v1​

Publication d’une modification incompatible​

Mise en cache​

Le chargeur et les bundles sont publiés séparément​

Auto-hébergement​

Origines acceptées pour remplacer la base​

Pages connexes​