CDN 版本管理
SDK 通过一个带版本的路径提供五个文件。网页只需引用第一个文件；它会在挂载产品时加载其余文件。
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>
产品包在该产品首次挂载到页面时请求，每个页面最多请求一次。只显示 Viewer 的页面不会下载 chat.js 或 editor.js。
v1 的含义
v1 代表的是接口约定，而不是一次具体构建。
- 每个 URL 对应一个文件，新版本会直接替换该地址上的文件。
- 不提供补丁版本路径，也没有按内容哈希命名的路径。你无法固定到
/embed/v1.2.3/kaleidr.js，因为该路径不存在。 - 修复和向后兼容的新增功能会发布到
/embed/v1/，网页无需修改就会收到更新。
Kaleidr.version 是用于诊断的字符串，不是可以指定下载的构建版本号。
v1 中保持稳定的内容
| 稳定项 | 含义 |
|---|---|
| 五个 URL | 它们将持续可访问。 |
window.Kaleidr | mount、init、enable 和 version 保持文档规定的行为。 |
| 挂载选项与元素属性 | 已公开的选项会保持其名称和含义。 |
| 控制句柄 | 每个句柄都包含 setCamera、setTheme、setStyle 和 destroy。不支持的方法只输出警告而不执行操作；不会抛出异常，也不会被删除。 |
| 两种 iframe 消息 | kaleidr-embed:ready 和 kaleidr-embed:error 保持其文档规定的字段。 |
v1 内允许发生的变化：
- 新增内容。 可能出现新的选项、属性、句柄方法、消息字段、错误代码和流事件。代码必须忽略不认识的内容，例如未知消息字段、未知
code和未知事件。 - 外观。 聊天面板、编辑器和地图控件的外观可能改变。
- 未公开的行为。 文档未描述的任何内容都可能变化，包括 SDK 与 iframe 之间的其他
kaleidr-embed:消息、产品包定义的全局变量，以及控制台消息的确切文字。
HTTP API 在 /inference-api/b2b/v1/ 也遵循相同原则：只有破坏兼容性的变更才会推出 v2。变更记录在更新日志中。
如何发布破坏性变更
可能破坏现有 v1 集成的变更不会发布到 /embed/v1/，而是作为并行的新主版本提供：
https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js
现有 v1 脚本标签会继续加载 v1 文件。阅读变更并准备升级后，修改脚本标签中的路径即可切换到新主版本。加载器只会请求与自己主版本一致的产品包。
缓存
每个文件都会携带以下缓存配置提供服务
Cache-Control: public, max-age=300
并且 CDN 的副本会在每次发布时替换。
| 问题 | 回答 |
|---|---|
| 新版本多快能到达访客？ | 大约五分钟内。如果浏览器在此前五分钟内取得旧文件，在缓存过期前仍会继续使用它。 |
| 每打开一个页面都要重新下载 SDK 吗？ | 不需要。取得文件后的五分钟内会使用浏览器缓存，随后再次向 CDN 检查。 |
| 可以自行缓存更长时间吗？ | 不可以。代理、service worker 或构建流程长期保留副本，会在更新后继续提供过时代码。 |
可以添加子资源完整性校验（integrity="sha384-…"）吗？ | 不可以。每次发布都会改变文件哈希，浏览器会拒绝哈希不匹配的脚本，使嵌入组件在下一次发布后无法加载。 |
可以将 kaleidr.js 复制进自己的打包文件吗？ | 不可以，原因相同。应直接引用 URL。 |
如果网站的 service worker 会缓存跨来源脚本，请将 https://cdn.kaleidr.com 排除在缓存优先策略之外，或采用会重新验证的缓存策略。
加载器和产品包分别发布
五个文件独立发布。因此发布后短时间内，网页可能使用较新的 kaleidr.js 和浏览器缓存的旧产品包，或相反。SDK 已兼容这种情况：
-
加载器会把选项传递给产品包，并允许旧包不认识新增的选项。
-
如果调用产品支持、但缓存的产品包尚不具备的句柄方法，该调用不会产生效果，控制台会提示：
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …绕过缓存刷新页面即可获取最新产品包。缓存副本到期后，这种情况也会自动消失。
Viewer 和 Tile iframe 中的页 面由 https://map-embed.kaleidr.com 提供，也会单独发布。网页如何缓存 SDK 不会影响这些页面。
自行托管
你可以从自己的来源提供全部五个文件，例如让所有脚本都使用第一方来源。需要了解其中的代价：自行托管的副本不会自动获得修复。 API 和 iframe 内部页面仍会由 Kaleidr 更新，长期不更新的副本会逐渐与它们不兼容。
自行托管的步骤：
-
将全部五个文件镜像到
https://your-origin/embed/v1/。路径固定，仅允许改变来源。 -
在加载器运行前告诉它产品包所在的位置：
<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script><script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>或者在每次挂载时使用
base选项或base属性。 -
定期重新镜像文件，并像 Kaleidr 一样以较短的缓存时长提供副本。
哪些来源可以用于覆盖 base
加载器不会从任意来源获取产品包。只有当覆盖设置（页面全局值、base 选项 或 base 属性）的来源属于以下情况时才会生效：
- Kaleidr CDN（
https://cdn.kaleidr.com）； kaleidr.js本身的加载来源；或- 当前网页自己的来源。
只有加载器和产品包来自同一个来源，自行托管才会正常工作。 第 2 步即为这种设置：kaleidr.js 来自 https://cdn.example.com，因此 https://cdn.example.com 可作为 base。也允许从网页自身来源加载产品包。
任何其他值都会被忽略，包括其他 kaleidr.com 主机。嵌入组件仍会挂载，但产品包从 https://cdn.kaleidr.com 加载，控制台会显示：
[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.
因此以下两种配置不受支持：
kaleidr.js从https://cdn.kaleidr.com加载，base 却指向第三方来源。此时应同时从该第三方来源加载加载器。- 加载器位于你的一个来源，产品包位于另一个来源，且二者都不是当前网页的来源。请从同一个来源提供全部五个文件。
如果这个警告出现在仅允许自家脚本来源的内容安全策略页面中，那么到 https://cdn.kaleidr.com 的产品包请求将被阻止，页面无法显示内容。应修正 base，而非安全策略。
自行托管会改变及不会改变的内容：
- 只自行托管
kaleidr.js并不够。不覆盖 base 时，加载器仍会从https://cdn.kaleidr.com获取产品包。 - 只使用
base的来源部分，设置中的路径会被丢弃，并从该来源的/embed/v1/请求产品包。 window.__KALEIDR_EMBED_BASE__必须是字符串，其他值会被忽略。- 自行托管仅改变脚本的来源。会话交换仍发送到
https://api.kaleidr.com，Viewer 和 Tile iframe 仍从https://map-embed.kaleidr.com加载，Editor 底图仍来自https://tile.kaleidr.com。你的内容安全策略仍须允许这些地址。