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。你的內容安全策略仍須允許這些地址。