メインコンテンツまでスキップ

kaleidr.js ローダー

kaleidr.js はすべての Kaleidr 埋め込みの起点となるスクリプトです。グローバルの window.Kaleidr とカスタム要素 <kaleidr-map> を定義します。地図ライブラリや製品コードを含まない小さなスクリプトで、製品をマウントすると同じ CDN から製品バンドルを読み込み、オプションを渡します。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

npm パッケージはありません。SDK は script タグからのみ読み込めます。React、Next.js、Vue、TypeScript についてはフレームワーク連携をご覧ください。

スクリプトの読み込み​

質問回答
タグの配置場所は?どこでも構いません。<kaleidr-map> 要素はタグより前でも後でもマウントされます。
Kaleidr.mount はいつ呼べる?スクリプトの実行後です。通常の <script src> タグなら、それより後のスクリプトから呼べます。
async または defer を使える?要素には使えます。Kaleidr.mount の場合、タグの load イベントを待ってください。それ以前は window.Kaleidr が定義されていません。
何回読み込む?1 ページにつき 1 回です。
integrity を付けられる?いいえ。ファイルは同じ URL で更新され、固定ハッシュは次のリリースで一致しなくなります。CDN のバージョン管理を参照。
サーバーで実行できる?できません。window と document が必要です。SSR アプリではブラウザーでのみ読み込んでください。

async で読み込み、完了後にマウントする方法:

<div id="map" style="height:480px"></div>
<script>
const s = document.createElement('script');
s.src = 'https://cdn.kaleidr.com/embed/v1/kaleidr.js';
s.async = true;
s.onload = () => {
Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });
};
document.head.appendChild(s);
</script>

window.Kaleidr​

メンバー説明
Kaleidr.mount(target, options)要素に製品をマウントし、ハンドルを返します。
Kaleidr.init()文書に既に存在する <kaleidr-map> 要素を初期化します。通常は不要です。
Kaleidr.enable(on)以降のマウントの有効・無効を切り替えます。
Kaleidr.versionローダーの診断用バージョン文字列です。

Kaleidr.mount(target, options)​

const handle = Kaleidr.mount('#chat', {
product: 'chat',
publishableKey: 'kld_pk_live_…',
map: myMap,
contained: true,
});
パラメーター型説明
targetCSS セレクターまたは HTMLElementマウント先。セレクターは document.querySelector で一度だけ解決します。
optionsオブジェクト必須。オプションを参照。

ハンドルを返します。

動作:

  • すぐに戻ります。 セッション交換と製品バンドルの読み込みはバックグラウンドで行われます。準備前のハンドル呼び出しは順に保持され、製品が準備できてから適用されます。Viewer と Tile では iframe 内の地図が準備完了を通知した時点なので、setCamera の呼び出しが mount の直後でも動作します。
  • マウント失敗時に例外を投げません。 対象がない、バンドルが読み込めない、セッション拒否、ID 不正の場合は [kaleidr:<product>] を含むエラーをコンソールに記録します。ハンドルは返りますが、メソッドは何もしません。例外はオプションオブジェクトなしの Kaleidr.mount('#map') だけで、TypeError を投げます。
  • コードに結果を通知しません。 待機する Promise やコールバックはありません。マウントの成否確認を参照。
  • 対象ごとに 1 マウントです。 既存の対象に再マウントする前に handle.destroy() を呼んでください。最初の読み込み中でも、破棄して同じ要素へ再マウントするのは安全です。破棄済みのマウントは新しいものに干渉しません。

オプション​

オプション型既定値製品説明
product'chat' | 'viewer' | 'editor' | 'tile'なし、必須すべてマウントする製品。
publishableKey文字列なしchat、editor、tile公開可能キー kld_pk_…。SDK が短期セッションに交換し、製品にはセッションだけ渡します。Viewer には渡さないでください。サーバーキー (kld_sk_…) はリクエスト前に拒否されます。
shareId文字列なしviewer、chatViewer:公開地図の ID。キーなしの Chat:所有者がチャットを提供する公開地図。
mapId文字列なしviewershareId がない場合に使う shareId の別名。
styleId文字列組織の既定ベースマップtile、editorkaleidr-morning のようなスタイル ID、または完全なスタイル URL。
map実行中の地図インスタンスなしchatアシスタントが操作する Mapbox GL JS、MapLibre GL JS、Google Maps、Leaflet の地図オブジェクト。対応地図を参照。地図なしチャットでは省略。
mapTargetCSS セレクターなしchatViewer または Tile の <kaleidr-map> 要素。map の代わりに操作します。
contained真偽値falsechatパネルをマウント先内に固定します。対象には位置指定とサイズが必要です。通常は画面左上に固定表示されます。
lang文字列ページの有効な <html lang>、なければ英語chat回答言語の BCP 47 タグ。例:en、ko、pt-BR。Chat の言語を参照。
title文字列パネル固有のタイトルchatヘッダーに表示するタイトル。要素の属性名は chat-title です。
placeholder文字列パネル固有のプレースホルダーchat入力欄の案内文。
center[longitude, latitude]製品の既定値viewer、tile、editor初期中心。
zoom数値製品の既定値viewer、tile、editor初期ズーム。Viewer と Tile は center と一緒に渡したときのみ適用。
pitch数値製品の既定値viewer、tile、editor初期傾斜角(度)。
bearing数値製品の既定値viewer、tile、editor初期回転角(度)。
themeオブジェクトまたはその JSON 文字列なしchat、editorChat:CSS カスタムプロパティ。例:{ '--highlight-color': '#0b5fff' }。Editor:17 個のテーマキー。JSON でない文字列は警告して無視します。
enabled真偽値なしすべてマウント単位の有効化ゲート。マウント時にのみ読みます。
baseURLhttps://cdn.kaleidr.comすべてバンドルの読み込み元。オリジンのみを使い、その /embed/v1/ から取得します。ベースの上書きで許されたオリジンのみ有効。その他は警告して無視。
viewerBaseURLhttps://map-embed.kaleidr.comviewer、tileiframe の読み込み元。オリジンのみ使用。
apiBaseURLhttps://api.kaleidr.com/inference-apichat、editor、tileセッション交換と製品リクエストの送信先。/inference-api を含める必要があり、オリジンだけでは 404。
tileBaseURLhttps://tile.kaleidr.comeditorスタイル ID の解決に用いるホスト。

注意:

  • apiKey は廃止予定の publishableKey の別名です。
  • 4 つの …Base オプションは別のデプロイ環境のテスト用で、本番では不要です。base が変更するのはバンドルだけで、地図ページ、API、ベースマップホストはそれぞれ上書きしない限り Kaleidr のままです。
  • lang、title、placeholder はマウント時に読みます。変更するには破棄して再マウントしてください。
  • 製品が使わないオプションは通知なく無視されます。

ベースの上書き​

base(オプションと属性)とページグローバル window.__KALEIDR_EMBED_BASE__ は製品バンドルの読み込み元オリジンを指定します。次のいずれかの場合だけ上書きが認められます:

許可されるオリジン例
Kaleidr CDNhttps://cdn.kaleidr.com
kaleidr.js 自体を読み込んだオリジンkaleidr.js を https://static.example.com から配信し、base に https://static.example.com を指定。
ページ自身のオリジンページが https://www.example.com/… にあり、base が https://www.example.com。

その他の値は無視されます。マウントは続行され、既定の CDN からバンドルが読み込まれ、コンソールに警告が出ます:

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

ページグローバルは文字列でなければなりません。その他は通知なく無視されます。ローダーとバンドルを同じオリジンから配信する場合、セルフホスティングでもこの規則を守ります。

製品ごとの初期カメラ:

製品既定のカメラ
viewer地図作成者が保存した視点。
tileスタイルの既定視点、なければ世界全体。
editor中心 [0, 0]、ズーム 2、傾斜 0、回転 0。
chat該当なし。Chat は地図を作成しません。

詳細は製品別リファレンス:Chat、Viewer、Tile、Editor。

ハンドル​

Kaleidr.mount はどの製品でも同じ形のハンドルを返します。

interface KaleidrHandle {
readonly product: 'chat' | 'viewer' | 'editor' | 'tile';
setCamera(camera: {
center?: [number, number]; // [longitude, latitude]
zoom?: number;
pitch?: number;
bearing?: number;
duration?: number; // milliseconds
}): void;
setTheme(theme: string | Record<string, string>): void;
setStyle(style: string): void;
destroy(): void;
}

すべてのメソッドが各ハンドルに存在します。実際に動くかは製品によります:

メソッドchatviewereditortile
setCamera(camera)警告はいはいはい
setTheme(theme)はい警告警告警告
setStyle(style)警告警告警告はい
destroy()はいはいはいはい

「警告」は何も起こらず、コンソールに通知されることを意味します。

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

これは /embed/v1 の契約の一部です。非対応メソッドは例外を投げません。

メソッドの補足:

  • setCamera:省略したフィールドは値が保たれます。duration で移動をアニメーション化し、省略または 0 なら即座に移動します。Chat では setCamera は非対応です(地図の所有者ではないため)。ただし回答時にはアシスタントが連携先の地図を動かします。自分で動かす場合は地図ライブラリの API を使ってください。
  • setTheme:Chat のみ。CSS カスタムプロパティのオブジェクトか JSON 文字列を受け取ります。
  • setStyle:Tile のみ。スタイル ID または URL を受け取ります。
  • destroy:表示内容を削除し、セッション更新を止め、保留中の呼び出しを破棄します。二度呼んでも問題ありません。破棄したハンドルは再利用できず、再マウントが必要です。

mount の直後からハンドルを呼べます。 Viewer と Tile では、iframe 内の地図が準備できる前の setCamera(Tile の setStyle も)を順番に保持し、kaleidr-embed:ready または最初のカメラ位置を受けると適用します。最新 256 件を保持します。iframe 読み込み後、通常 10 秒ほどの制限時間内に準備完了しなくても、保留呼び出しを送信し、警告を 1 回表示します:

[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. The frame may be showing an error (an unpublished map, a blocked request).

待機時間は iframe の読み込みが始まってから計測します。画面外で遅延読み込みされる iframe の呼び出しはそのまま保持されます。ハンドル操作前に kaleidr-embed:ready を待つ必要はありません。このメッセージと kaleidr-embed:error は成功・失敗の通知にも使います。Viewer のメッセージを参照。

ハンドルには ready Promise、on() メソッド、map や iframe メンバーはありません。

Kaleidr.init()​

呼び出した時点で文書内にあるすべての <kaleidr-map> を初期化します。ローダーが自動的に呼び、後から追加した要素も自動マウントされるため、通常は不要です。複数回呼んでも安全です。

有効化ゲート​

埋め込みは既定で有効です。ゲートがオフの場合、Kaleidr.mount は読み込みも送信もせず、操作できないハンドルを返します。訪問者の同意を待つ場合や、HTML を削除せず埋め込みを停止する場合に使用します。

3 つの制御方法​

制御適用範囲設定方法
ページフラグページのすべてのマウント対象を保留する前に window.__KALEIDR_EMBED_ENABLED__ = false を設定
Kaleidr.enable()呼び出し以降のすべてのマウントKaleidr.enable(false)
マウント単位1 回のマウントenabled: false オプション、または flag="false" 属性

マウント時の判定​

マウントのたびに SDK は 3 つの制御を確認します:

  1. いずれかが明示的に false ならマウントを保留します。
  2. そうでなく、どれかが明示的に true なら実行します。
  3. それ以外は既定の有効状態です。

重要な結果は 3 つあります:

  • false の解除はそれを設定した制御でしかできません。 Kaleidr.enable(true) ではマウントの enabled: false やページフラグの false を解除できません。相互に上書きしません。
  • ゲートはマウント時だけ判定されます。 保留解除しても以前のマウントは自動開始せず、ゲートをオフにしても実行中のものは消えません。解除後に Kaleidr.mount を再度呼ぶか、要素を除去して再挿入します。
  • ページフラグは毎回のマウント時に読みます。 スクリプト読込時だけではないため、後から代入した値は次のマウントに効きます。
保留を設定したもの解除方法
window.__KALEIDR_EMBED_ENABLED__ = falsetrue を代入するか削除する。
Kaleidr.enable(false)Kaleidr.enable(true)、または既定に戻す Kaleidr.enable(null) を呼ぶ。
enabled: false または flag="false"それを外して再マウントする。既存要素の flag 属性を変更しても無効。

保留中は、原因となる制御を示す警告がコンソールに 1 回出ます:

[kaleidr] embed is disabled — window.__KALEIDR_EMBED_ENABLED__ is false. Reassigning it releases that lever — Kaleidr.enable() cannot.

許可される値​

予期しない文字列で誤って埋め込みが有効にならないよう、真偽値の解釈は厳密です。

制御true とみなす値false とみなす値警告して無視する値
window.__KALEIDR_EMBED_ENABLED__truefalse真の真偽値以外。文字列 "true"、"false" も不可
Kaleidr.enable(x)引数なし、true、"true"、"1"、"yes"、"on"false、0、""、"false"、"0"、"no"、"off"その他の文字列、undefined、オブジェクト、関数
enabled オプションtrue、"true"、"1"、"yes"、"on"false、0、""、"false"、"0"、"no"、"off"その他の文字列、オブジェクト、関数
flag 属性値なしの flag、"true"、"1"、"yes"、"on""false"、"0"、"no"、"off"その他すべて

大文字小文字や前後の空白は無視されます。保存された値について 2 点注意してください:

  • Kaleidr.enable(null) は制御を既定にリセットします。「意見なし」の意味ではありません。localStorage.getItem(key) は未保存なら null を返し、同意前もこの状態です。保存値をそのまま渡さず、まず比較してください:Kaleidr.enable(stored === 'true')。
  • 無視された値は制御の以前の状態を維持し、有効にも無効にもしません。

例:同意まで埋め込みを保留する​

このページはページフラグで全要素を保留します。要素はローダー実行時にマウントされるため、この方法が有効です。同意後、同じフラグを解除し、要素を再挿入してマウントします。

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Consent-gated map</title>
<script>
// A real boolean, set before the loader. A stored string is compared, never passed through.
window.__KALEIDR_EMBED_ENABLED__ =
localStorage.getItem('embeds-consent') === 'true';
</script>
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
</head>
<body>
<div id="banner">
This page shows an interactive map from Kaleidr.
<button id="accept">Show the map</button>
</div>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
style="display:block; height:480px"></kaleidr-map>

<script>
const banner = document.getElementById('banner');
if (window.__KALEIDR_EMBED_ENABLED__) banner.hidden = true;

document.getElementById('accept').addEventListener('click', () => {
localStorage.setItem('embeds-consent', 'true');
banner.hidden = true;

// 1. Release the lever that held the embeds.
window.__KALEIDR_EMBED_ENABLED__ = true;

// 2. A held element does not mount by itself. Re-insert each one.
document.querySelectorAll('kaleidr-map').forEach((el) => {
const parent = el.parentNode;
const next = el.nextSibling;
el.remove();
parent.insertBefore(el, next);
});
});
</script>
</body>
</html>

同意前のネットワークタブには kaleidr.js だけが表示され、Kaleidr の製品バンドル、セッション要求、iframe はありません。

JavaScript からマウントするならゲートなしでも、同意するまで Kaleidr.mount を呼ばなければ十分です。ゲートは HTML の要素や、タグマネージャー・他チームのコードが mount を呼び、ページ全体のスイッチが必要な場合に役立ちます:

Kaleidr.enable(false); // hold every later mount
// …
Kaleidr.enable(true); // release it
const handle = Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });

ページグローバル​

グローバル型読み取り時点用途
window.__KALEIDR_EMBED_ENABLED__真偽値マウントごと有効化ゲートのページフラグ。
window.__KALEIDR_EMBED_BASE__URL 文字列マウントごとセルフホストするバンドルのオリジン。オリジンのみを使い、ベースの上書きで許可される必要があります。CDN のバージョン管理を参照。

マウントの成否確認​

SDK はコードに準備完了や失敗のシグナルを渡しません。確認できるものは:

製品読み込み成功失敗
vieweriframe が kaleidr-embed:ready を送信。iframe が kaleidr-embed:error を送信するか、コンソールに [kaleidr:viewer] エラー。
tileiframe が kaleidr-embed:ready を送信。セッション拒否はコンソールのみ。描画問題は kaleidr-embed:error。
chatシグナルなし。パネルがページに表示される。コンソールのみ。
editorシグナルなし。エディターがページに表示される。コンソールのみ。

2 つのメッセージは Viewer のメッセージに記載しています。

マウントに失敗した場合​

原因表示内容要求送信?
セレクターが対象に一致しない[kaleidr:<product>] mount target not found: <selector>いいえ
要素に有効な product がない[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"いいえ
サーバーキーを渡した[kaleidr:<product>] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.いいえ
キーが不明・取り消し済み、またはオリジンが不許可sessions へのブラウザー CORS エラー、その後 [kaleidr:<product>] の取得エラー。何も表示されません。はい
スコープ不足、製品制限、プラン不許可[kaleidr:<product>] kaleidr session exchange failed (403)。何も表示されません。はい
地図読み込み枠が尽きた(tile)、またはセッション要求過多[kaleidr:<product>] kaleidr session exchange failed (429)。何も表示されません。はい
製品バンドルを読み込めない[kaleidr:<product>] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/<product>.js該当なし
Viewer の ID がない・不正[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.いいえ
Editor のキーがない[kaleidr:editor] [editor-embed] attach() requires an { apiKey }いいえ
Chat にキーも shareId もないパネルは表示されますが、質問はすべて失敗します。マウント時は送信なし
有効化ゲートがオフ[kaleidr] embed is disabled — …いいえ

SDK はサーバーが返した理由を表示しません。 セッション拒否時は HTTP ステータスだけを記録します。理由は応答本文にあります。403/404 は detail にコード(例:{"detail":"insufficient_scope"})、429 は error にコードと detail に説明が入ります。例外として map_load_quota_exceeded は detail に入ります。ネットワークタブで sessions の応答を確認してください。CORS で本文が隠れる場合はターミナルから同じ要求を再現します:

curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "x-api-key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "content-type: application/json" \
-d '{"product":"chat"}'
HTTP/2 403
content-type: application/json

{"detail":"origin_not_allowed"}

失敗するページのオリジンを使います。テストには "chat"、"editor"、"viewer" を指定してください。"tile" で交換が成功すると地図読み込み 1 回に加算されます。全コードはエラーを参照。

最初の交換に失敗したマウントは再試行されません。原因を直して再マウントしてください。

セッション交換の概要​

Chat、Editor、Tile では、SDK は公開可能キーをランタイム API に直接使わず、先にセッションへ交換します。

  1. マウント時に POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions を送信し、ヘッダー x-api-key: <your publishable key>、本文 {"product":"<product>"} を付けます。ブラウザーはページの Origin を追加します。
  2. Kaleidr は順に、公開可能キーか、オリジンがあるか、許可オリジン一覧があれば一致するか、キーとプランで製品が許可されるか、必要スコープがあるかを検証します。Chat は ai、Editor は design、Tile は maps、Viewer は不要です。
  3. 応答は {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …} です。basemap_style_id は組織の既定ベースマップ、設定がなければ null です。
  4. 製品は発行元オリジンと製品に紐づけられたセッショントークンを使ってリクエストします。
  5. SDK は期限の 90 秒前、またはバックグラウンドのタブが戻り期限間近の場合に更新します。更新失敗時はマウント中 30 秒ごとに再試行します。
  6. handle.destroy() は更新を停止します。

Viewer にセッションは不要です。キーなしで shareId を指定した公開地図の Chat は、キーでなく地図からセッションを取得します。公開地図の Chatを参照。

要求と応答はエンドポイントに説明があります。キー種別、セッション、許可オリジン設定で保護できること・できないことはセキュリティモデルを参照。

その他のコンソールメッセージ​

メッセージ意味
[kaleidr] <method>() is not supported on product "<product>" — the call is a no-op. …製品非対応のハンドルメソッドを呼びました。
[kaleidr] <method>() IS supported on product "<product>", but this mount did not expose it, so the call did nothing. …キャッシュ済みバンドルがローダーより古い状態です。キャッシュを無視して再読み込みします。
[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. …Viewer/Tile の地図がハンドルの待機時間内に準備完了しませんでした。保留した setCamera、setStyle を送信済みで、kaleidr-embed:error の可能性があります。
[kaleidr] theme must be an object of CSS tokens, not an array; ignored.theme が配列です。
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.theme の文字列が { で始まっていません。
[kaleidr] theme JSON parse failed (…); ignored.theme の JSON が不正です。
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. …flag または contained の値が無効です。メッセージには flag="…" または contained="…" が示されます。
[kaleidr] base "<value>" is IGNORED — bundles load from <origin>. …base または window.__KALEIDR_EMBED_BASE__ がベースの上書きで認められないオリジンを指定しています。既定 CDN を使います。
[kaleidr] window.__KALEIDR_EMBED_ENABLED__ must be a boolean; got <type> (…). …ページフラグが真偽値でないため無視しました。
[kaleidr] Kaleidr.enable(): "<value>" is not a recognized boolean — the value is IGNORED. …Kaleidr.enable に無効な値が渡されました。
[kaleidr] enabled: "<value>" is not a recognized boolean — the value is IGNORED. …enabled オプションに無効な値が渡されました。
[kaleidr] Kaleidr.enable(undefined) is IGNORED and leaves the gate exactly as it was. …Kaleidr.enable に undefined が渡され、状態は維持されます。
[kaleidr] Kaleidr.enable(null) RESET the gate to the build default, releasing the <value> set earlier. …Kaleidr.enable(null) が以前の設定を解除し既定に戻しました。

提供されない機能​

  • npm パッケージ、ES モジュールビルド、付属型定義。フレームワーク連携で宣言をコピーできます。
  • iOS、Android、React Native、Flutter 向けネイティブ SDK。
  • ハンドルの ready Promise、イベント、コールバック。
  • 製品マウント不要の JavaScript API クライアント。バックエンドのサーバー APIを使ってください。

関連ページ​