CDN versioning

The SDK is delivered as five files under one versioned path. You reference the first one. It loads the others when a product mounts.

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>

A product bundle is requested the first time that product mounts on a page, and at most once per page. A page that only shows a viewer never downloads chat.js or editor.js.

What `v1` is

v1 names a contract, not a build.

There is one file at each URL, and a release replaces it in place.
There are no patch versions and no content-hashed paths. You cannot pin /embed/v1.2.3/kaleidr.js, because no such path exists.
Fixes and backward-compatible additions are published to /embed/v1/, and your page receives them without any change on your side.

Kaleidr.version is a string for diagnostics. It does not identify a build you can request.

What stays stable under `v1`

Stable	Meaning
The five URLs	They keep resolving.
`window.Kaleidr`	`mount`, `init`, `enable` and `version` keep their documented behavior.
Mount options and element attributes	A documented option keeps its name and meaning.
The handle	Every handle has `setCamera`, `setTheme`, `setStyle` and `destroy`. A method a product does not support logs a warning and does nothing. It does not throw, and it is not removed.
The two iframe messages	`kaleidr-embed:ready` and `kaleidr-embed:error` keep their documented fields.

What can change within v1:

Additions. New options, attributes, handle methods, message fields, error codes and stream events can appear. Write code that ignores what it does not recognize: an unknown field on a message, an unknown code, an unknown event.
Appearance. The look of the chat panel, the editor and the map chrome can change.
Undocumented behavior. Anything not described in these docs, including the other kaleidr-embed: messages that pass between the SDK and its iframes, the globals the product bundles define, and the exact wording of console messages.

The HTTP API follows the same rule at /inference-api/b2b/v1/: a v2 appears only for a breaking change. Changes are recorded in the changelog.

How a breaking change ships

A change that would break a working v1 integration is not published to /embed/v1/. It ships as a new major beside it:

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

Your v1 tag keeps loading v1 files. You move to the new major by changing the path in your script tag, when you are ready, after reading what changed. A loader requests product bundles from its own major.

Caching

Every file is served with

Cache-Control: public, max-age=300

and the CDN's copy is replaced at each release.

Question	Answer
How fast does a release reach a visitor?	Within about five minutes. A browser that fetched the old file up to five minutes earlier keeps using it until its copy expires.
Does a visitor re-download the SDK on every page?	No. For five minutes after a fetch, the browser uses its cached copy. After that it checks with the CDN again.
Can I cache the files longer on my side?	Do not. A proxy, a service worker or a build step that keeps a copy for longer will serve stale code after a release.
Can I add Subresource Integrity (`integrity="sha384-…"`)?	No. The hash of the file changes with every release, and a browser refuses a script whose hash does not match. Your embeds would stop loading at the next release.
Can I copy `kaleidr.js` into my own bundle?	No, for the same reason. Reference the URL.

If your site has a service worker that caches cross-origin scripts, exclude https://cdn.kaleidr.com from any cache-first rule, or use a strategy that revalidates.

The loader and the bundles are released separately

The five files are released independently, so for a short time after a release a page can hold a newer kaleidr.js with an older product bundle from the browser's cache, or the other way round. The SDK is built for this:

The loader passes options through to the bundle and tolerates a bundle that does not know a newer option.
If you call a handle method that the product supports but the cached bundle does not have yet, the call does nothing and the console says so:
```
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …
```
A reload that bypasses the cache picks up the current bundle. The condition clears by itself when the cached copy expires.

The pages inside the Viewer and Tile iframes are served from https://map-embed.kaleidr.com and are released separately as well. How your page caches the SDK has no effect on them.

Self-hosting

You can serve the five files from your own origin, for example to keep all script origins first-party. Understand the trade before you do: a self-hosted copy stops receiving fixes. The API and the pages inside the iframes keep moving on Kaleidr's side, so a copy you do not refresh drifts out of step with them.

To self-host:

Mirror all five files to https://your-origin/embed/v1/. The path is fixed. Only the origin can change.

Tell the loader where its bundles are, before the loader runs:

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

or per mount, with the base option or the base attribute.

Re-mirror on a schedule, and serve the copies with a short cache lifetime, as Kaleidr does.

Which origins a base override may name

The loader does not load bundles from an arbitrary origin. A base override (the page global, the base option or the base attribute) is honored only when its origin is:

the Kaleidr CDN (https://cdn.kaleidr.com);
the origin kaleidr.js itself was loaded from; or
the page's own origin.

Self-hosting works when the loader and the bundles are served from the same origin. That is the layout in step 2: kaleidr.js comes from https://cdn.example.com, so a base of https://cdn.example.com is accepted. Serving the bundles from the page's own origin is accepted too.

Any other value is ignored, another kaleidr.com host included. The embed still mounts, with bundles from https://cdn.kaleidr.com, and the console shows:

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

Two layouts this rules out:

kaleidr.js loaded from https://cdn.kaleidr.com with a base that points at a third origin. Load the loader from that origin as well.
The loader on one of your origins and the bundles on another, where neither is the page's origin. Serve all five files from one origin.

If the warning appears on a page whose Content Security Policy lists only your own script origin, the bundle request to https://cdn.kaleidr.com is then blocked by the policy and nothing renders. Fix the base, not the policy.

What self-hosting does and does not change:

Hosting only kaleidr.js yourself is not enough. Without the base override, the loader still fetches the product bundles from https://cdn.kaleidr.com.
Only the origin of base is used. A path in the value is dropped, and the bundles are requested from /embed/v1/ on that origin.
window.__KALEIDR_EMBED_BASE__ must be a string. Any other value is skipped.
Self-hosting moves the scripts only. The session exchange still goes to https://api.kaleidr.com, the Viewer and Tile iframes still load from https://map-embed.kaleidr.com, and the Editor's basemap still comes from https://tile.kaleidr.com. Your Content Security Policy must keep allowing those.

What v1 is​

What stays stable under v1​

How a breaking change ships​

Caching​

The loader and the bundles are released separately​

Self-hosting​

Which origins a base override may name​

Related​