跳至主要内容

CDN 版本管理

每個 embed 資源都透過一個 major-alias 路徑提供：

https://cdn.kaleidr.com/embed/v1/kaleidr.js   ← the loader (façade)
https://cdn.kaleidr.com/embed/v1/chat.js      ← chat bundle
https://cdn.kaleidr.com/embed/v1/viewer.js    ← viewer loader
https://cdn.kaleidr.com/embed/v1/editor.js    ← editor bundle
https://cdn.kaleidr.com/embed/v1/tile.js      ← tile loader

您固定 kaleidr.js；接著它會依序要求每個產品 bundle 的 v1。

v1 實際代表什麼​

  • v1 是主版本契約別名，而不是固定的 build。 /embed/v1/* 下不存在 patch 或 content-hash 路徑。該 URL 所提供的檔案 是目前的 v1 build，並直接發布在原位置；不存在可供您固定的 /embed/v1.2.3/…。
  • 向後相容的修正會發布至 /embed/v1/ 下 — 您會 自動取得這些更新。這也包括行為擴充（新的穩定 SSE event、 新的 handle method）— 相容性規則要求用戶端必須 忽略未知 wire 擴充，而不支援的 handle method 應 以帶警告的 no-op 方式運行。
  • 破壞相容性的 wire/postMessage 變更會作為新的主版本與 v1 並行發布： /embed/v2/kaleidr.js (+ /embed/v2/<product>.js)。您固定的 v1 URL 會繼續原樣運作；您可以依自己的時程，透過修改 路徑進行遷移。

SSE wire contract 也以相同方式在 /inference-api/b2b/v1/* 下進行版本管理 — 只有發生破壞相容性的 stream 變更時才會出現 v2。

快取​

bundle 以 Cache-Control: public, max-age=300 提供，每次 publish 都會使 CloudFront distribution 失效 — 因此實際 傳播時間為 edge 約 1–5 分鐘，已經快取舊檔案的 瀏覽器最多還可能再延遲 300 秒。對修正而言，這個速度很快； 也正因如此，如果沒有替換計畫，不應對這些 檔案進行 fingerprint 或長期本機快取。

自行託管​

僅將 kaleidr.js 指向您自己的 origin 並不能讓您脫離 Kaleidr CDN — loader 在 mount 時仍會從 cdn.kaleidr.com 取得 lazy bundle （chat.js, editor.js, viewer.js, tile.js）。若要完全 self-host，請覆蓋 loader base，並在 {origin}/embed/v1/ 鏡像全部五個檔案：

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

如果您的 embed 還會與 platform API 或 private tile CDN 通訊， 請分別覆蓋它們 — 請參閱 api-base、 viewer-base 與 tile-base。