CDNのバージョン管理

SDKは、バージョン付きの1つのパスにある5つのファイルとして配布されます。ページでは最初のファイルを参照します。製品がマウントされると、そのファイルが残りを読み込みます。

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>

製品のバンドルは、その製品をページで初めてマウントしたときに要求され、ページごとに最大1回です。Viewerだけを表示するページでは chat.js も editor.js もダウンロードされません。

`v1` の意味

v1 は特定のビルドではなく、互換性の契約を表します。

各URLには1つのファイルがあり、新しいリリースが同じ場所のファイルを置き換えます。
パッチバージョンやコンテンツハッシュ付きのパスはありません。/embed/v1.2.3/kaleidr.js というパスは存在せず、固定できません。
修正と後方互換の機能追加は /embed/v1/ に公開され、ページの変更なしで反映されます。

Kaleidr.version は診断用の文字列です。指定して取得できるビルドを識別するものではありません。

`v1` で安定している内容

安定する項目	意味
5つのURL	引き続きアクセスできます。
`window.Kaleidr`	`mount`、`init`、`enable`、`version` は文書化された動作を維持します。
マウントオプションと要素属性	文書化されたオプションの名前と意味は変わりません。
ハンドル	すべてのハンドルには `setCamera`、`setTheme`、`setStyle`、`destroy` があります。非対応の製品でメソッドを呼ぶと警告が記録され、何も実行しません。例外は投げられず、メソッドも削除されません。
iframeの2つのメッセージ	`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上のコピーはリリースごとに置き換えられます。

質問	回答
新しいリリースが訪問者に届くまでの時間は？	約5分以内です。直前の5分間に旧ファイルを取得したブラウザーは、そのキャッシュが期限切れになるまで旧ファイルを使います。
ページを開くたびにSDKを再ダウンロードしますか？	いいえ。取得後5分間はキャッシュを利用し、その後CDNに再確認します。
自分の側でさらに長くキャッシュできますか？	しないでください。プロキシ、サービスワーカー、ビルド工程が古いコピーを保持すると、更新後も旧コードが配信されます。
サブリソース完全性（`integrity="sha384-…"`）を付けられますか？	いいえ。リリースごとにハッシュが変わり、一致しないスクリプトはブラウザーに拒否されます。次回の更新後に埋め込みが動かなくなります。
`kaleidr.js` を自分のバンドルにコピーできますか？	同じ理由で不可です。URLを参照してください。

サイトのサービスワーカーが別オリジンのスクリプトをキャッシュする場合、https://cdn.kaleidr.com をキャッシュ優先ルールから除外するか、再検証する方式を使ってください。

ローダーとバンドルは別々にリリースされます

5つのファイルは独立して公開されます。そのためリリース直後、一時的に新しい 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キャッシュはこれらに影響しません。

セルフホスティング

5つのファイルを自分のオリジンから配信し、スクリプトの提供元をすべてファーストパーティーにできます。ただし、セルフホストしたコピーには自動で修正が届きません。 APIとiframe内部のページはKaleidr側で進化するため、更新しないコピーは次第に互換性を失います。

セルフホスティングの手順：

5つすべてのファイルを 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.

次の2構成は対象外です：

kaleidr.js は https://cdn.kaleidr.com から読み込み、baseだけを第三のオリジンに向ける構成。この場合はローダーも第三のオリジンから読み込んでください。
ローダーとバンドルを別々の自社オリジンに置き、いずれもページのオリジンではない構成。5ファイルを同じオリジンから配信してください。

この警告が表示され、Content Security Policyで自社のスクリプト元だけを許可している場合、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 を使います。Content Security Policyでこれらを許可してください。

v1 の意味​

v1 で安定している内容​

互換性を破る変更の公開方法​

キャッシュ​

ローダーとバンドルは別々にリリースされます​

セルフホスティング​

base上書きに指定できるオリジン​

関連ページ​