Kaleidr のベースマップを使用する

このガイドを終えると、選んだスタイルとカメラ設定のインタラクティブな Kaleidr ベースマップをページに表示し、コードからカメラの移動やスタイルの切り替えができるようになります。Free を含むすべてのプランで利用できます。新規キーに標準で付与される maps スコープを持つ公開可能キーが必要です。

事前準備

• kaleidr.com/api-keys で発行した公開可能キー（kld_pk_live_…）。API キーを取得するを参照してください。
• テストページのオリジン（例：http://localhost:3000）がキーの許可オリジンに含まれていること。許可オリジンが未設定のキーは任意のサイトで利用できます。
• npx serve . など、HTTP でページを配信する方法。ローカルファイルを直接開くと有効なオリジンがなく、制限付きキーでは拒否されます。
• サイトにコンテンツセキュリティポリシーがある場合、script-src に https://cdn.kaleidr.com、connect-src に https://api.kaleidr.com、frame-src に https://map-embed.kaleidr.com を許可してください。コンテンツセキュリティポリシーを参照してください。

ステップ 1：地図を追加する

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

**確認できること：**最初に「Loading map…」が表示され、続いて明るいベースマップが現れます。Network タブでは https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions への POST が 200 を返し、続いて https://map-embed.kaleidr.com/ へのドキュメント要求が行われます。iframe の URL にはスタイル ID のみが入り、認証情報は入りません。キーはセッション要求だけで送信され、セッショントークンが iframe URL に記載されることはありません。

要素には高さが必要です。指定しない場合、地図は固定の 500 ピクセルになります。<kaleidr-map> は既定で display:block のため高さが有効ですが、CSS に明示しておくことを推奨します。Safari 16.4 より前では要素がインラインのままになり、height が無視されるためです。 (display:block)

ステップ 2：スタイルを選ぶ

style-id に次の汎用スタイルのいずれかを設定します。

style-id	外観
kaleidr-morning	明るい白地、シアンの水域、白い道路。
kaleidr-afternoon	中間色の地面、緑の植生、グレーの道路。
kaleidr-evening	夕暮れの暖かい砂色とオリーブ色。
kaleidr-night	濃紺とチャコール、琥珀色の幹線道路。
kaleidr-plain	境界線と地名を示す白いキャンバス。ズーム 15 から 3D 建物を表示。
kaleidr-editorial	ラベルを除いた午後の配色。小さな地図や装飾用。

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

**確認できること：**同じ地域が暗い配色で表示されます。

必ず style-id を指定してください。省略すると組織の既定ベースマップが使われます。既定の設定がない場合、フレームに「Couldn't find a map id in the URL.」と表示されます。

スタイル ID は完全一致が必要です。短縮名はなく、night は kaleidr-night の代わりになりません。

ステップ 3：カメラを設定する

カメラを指定しない場合は、スタイルに用意された既定のビューで地図が開きます。多くは全世界表示です。目的の地域を表示するには center（経度、緯度の順）と zoom を渡します。pitch は傾斜、bearing は回転を設定します。

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

**確認できること：**ロンドン中心部が傾きと回転を加えて表示されます。

center を指定しないと zoom は無視されます。 pitch と bearing は単独でも機能します。

ステップ 4：コードからカメラを移動しスタイルを変更する

要素の指定は宣言型の方法です。JavaScript から制御する場合は Kaleidr.mount でマウントし、返されるハンドルを保持してください。

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

**確認できること：**各ボタンで地図がその場で変わります。iframe は再読み込みされず、Network に新しいセッション要求も現れません。

重要な注意点：

• setCamera と setStyle は要素ではなくハンドルのメソッドです。
• setStyle は Tile 専用です。ほかの製品で呼ぶと警告が出るだけで何も起こりません。
• Kaleidr.mount が返った後はいつでもハンドルを操作できます。iframe 内の地図が準備できる前の呼び出しは保持され、準備が整った時点で順に適用されます。ステップ 6 の kaleidr-embed:ready を待つ必要はありません。初期カメラとスタイルはマウントオプションで指定してください。
• マウント済み要素の center、zoom、pitch、bearing を変更すると地図が移動します。style-id の変更は反映されません。

ステップ 5：チャットパネルを地図に接続する（任意）

Kaleidr Chat パネルは Tile 地図を操作できます。回答にある場所へピンを立て、カメラを調整して表示します。Tile 要素を位置指定したコンテナーに入れ、その上にチャット要素を重ね、map-target で Tile 要素を指定してください。

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

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

**確認できること：**チャットパネルが地図の左上に配置されます。「coffee near Covent Garden」と質問すると Tile 地図上にピンが現れます。

チャット要素の属性とスタイルの役割：

項目	役割
map-target="#basemap"	チャットが操作する Tile 要素への CSS セレクター。
contained	パネルをチャット要素内に固定します。省略するとウィンドウ左上に固定されます。
position:absolute; inset:0	チャット要素を地図全体に重ね、パネルを地図の隅に配置します。
z-index:1	チャットレイヤーを地図より手前にします。
pointer-events:none	パネルの外で地図をドラッグ・ズームできます。パネル自体は操作可能です。

補足：

• 標準キーには maps と ai の両スコープがあるため、2 つの要素に同じキーを利用できます。チャット要素は別のセッションを作成し、質問ごとに組織の AI クレジットを消費します。
• 要素の順序は問いません。チャットは必要になったときに地図を参照します。

パネルのレイアウトとテーマはテーマとレイアウト、アシスタントができること・できないことは機能と制限を参照してください。

ステップ 6：地図の読み込み完了を検出する（任意）

SDK に ready Promise はなく、要素もイベントを発火しません。iframe が地図を描画したとき、また描画に問題があったとき、ページへメッセージを送ります。

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

セッション要求が失敗した場合は iframe 自体が生成されないためメッセージは送られません。代わりにコンソールでエラーを確認してください。動作しない場合を参照してください。

完全なページ例

index.html として保存し、キーを入力して、キーが許可するオリジンから HTTP でフォルダーを配信してください。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

動作のしくみ

項目	動作
セッション	SDK は iframe を生成する前にキーを短期 Tile セッションと交換し、マウント中は更新します。この交換でキーを検証し、地図の読み込みを 1 回計上します。セッションは iframe に渡されず、URL にあるのはスタイルとカメラだけです。
開始時のビュー	指定したカメラ。未指定ならスタイルの既定ビュー。
スクロール	ポインターが地図上にあるときは、スクロールで地図をズームします。ポインターが地図の外にあるときは、スクロールでページを移動します。タッチ画面ではドラッグで地図を移動し、ピンチでズームします。
高さ	マウント時のコンテナーの高さに従います。なければ固定 500 ピクセル。
読み込み	iframe は画面内に近づくまで遅延読み込みされます。
削除	handle.destroy() は iframe を取り除き、セッション更新を停止します。<kaleidr-map> の削除も同様です。
再挿入	削除した要素を再挿入するか別の親へ移動すると、再マウントされ新しいセッションが作成されます。

地図の読み込み回数の計算

SDK が Tile セッションを取得するたびに 1 回の地図読み込みとして計上します。

操作	地図読み込み回数
地図をマウント	1
マウント中にセッションを更新	更新ごとに 1
マウントを破棄して再マウント、または要素を再挿入	1
setCamera、setStyle、パン、ズーム	0

セッションの有効期間は標準で 15 分です。SDK は期限の 90 秒前に、ページが前面でも背面でも更新します。数分の訪問なら通常 1 回、1 時間開いたページではおよそ 5 回の読み込みが計上されます。

使用量を抑えるには：

• ダイアログを閉じる、画面遷移する、タブを破棄するなど、地図が完全に非表示になったらマウントを破棄します。
• 描画のたびに要素を作り直さないでください。React や Vue などはフレームワーク統合を参照してください。
• スタイル変更には再マウントではなく setStyle を使ってください。

期間内の地図読み込み枠を使い切ると、新しいセッションは HTTP 429 と {"detail":"map_load_quota_exceeded"} で拒否されます。表示済みの地図はそのまま残りますが、新しいマウントは何も表示しません。クォータとレート制限を参照してください。

動作を確認する

• **ページ：**地図を操作でき、下部に地図の帰属表示があります。
• コンソール：[kaleidr を含むエラーや警告がありません。
• Network：https://cdn.kaleidr.com から kaleidr.js と tile.js を取得し、POST …/sdk/sessions が 200 を返して JSON に session_token と expires_in が含まれます。また https://map-embed.kaleidr.com/?style=… へのドキュメント要求があります。
• リスナー：source が "tile" の kaleidr-embed:ready メッセージを受信します。

動作しない場合

SDK はマウント失敗を [kaleidr:tile] … としてコンソールに出力します。セッション拒否の場合、コンソールには HTTP ステータスのみ表示されます。理由は Network の sessions 要求のレスポンスで確認してください。403 と map_load_quota_exceeded のコードは detail に、429 の rate_limited のコードは error に入ります。

症状	原因	対処
何も表示されず …/sdk/sessions の CORS エラーと [kaleidr:tile] エラーが出る	キーが不明・失効しているか、ページのオリジンが許可されていません。拒否時のレスポンスには CORS ヘッダーがありません。	kaleidr.com/api-keys でキーを確認し、正確なオリジン（スキーム、ホスト、ポート）を登録します。数分待って再読み込みします。Network のステータスは 401 または 403 です。
[kaleidr:tile] kaleidr session exchange failed (403)	maps スコープがない（insufficient_scope）、キーが別製品用（product_not_allowed）、またはプランが許可しない（tier_capability_not_allowed）。	Network の detail を確認し、標準スコープのキーを作成します。
[kaleidr:tile] kaleidr session exchange failed (429)	地図読み込み枠が尽きた（map_load_quota_exceeded）、またはリクエストが多すぎる（rate_limited）。	前者は detail、後者は error を確認してください。クォータとレート制限を参照。
sessions が 404	api-base の上書きで /inference-api が欠けています。	上書きを削除するか https://api.kaleidr.com/inference-api を使用します。
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…	サーバーキーを渡したため、要求前に SDK が拒否しました。	公開可能キーを使用し、サーバーキーを公開していた場合は交換してください。
[kaleidr:tile] Kaleidr tile: invalid style "…"…	style-id に空白や ? など不正な文字があります。	ステップ 2 の ID を指定します。
iframe に「Couldn't find a map id in the URL.」が表示され code: 'no_id' と id: null を受信	style-id がなく、組織にも既定ベースマップがありません。	style-id を渡してください。
iframe が空で kaleidr-embed:error の maplibre_error を受信	スタイルが存在しません。多くは ID の誤記です。	ステップ 2 の ID を使います。
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product がないか誤記です。	product="tile" にします。
地図の高さが常に 500 ピクセル	マウント時に高さがない、display:inline が指定された、または Safari 16.4 未満で display:block がありません。	display:block と高さを指定します。 height
空の枠と CSP 違反が表示される	ローダー、セッション要求、iframe のいずれかが CSP でブロックされています。	事前準備の 3 ホストを許可します。
setStyle または setCamera が効かない	要素上で呼んだ、または地図がまだ読み込み中です。	Kaleidr.mount が返したハンドルで呼び、kaleidr-embed:error とコンソールを確認します。準備前の呼び出しは後で適用されます。 地図が所定の待機時間内（通常は iframe 読み込み後 10 秒）に準備完了を報告しない場合も、呼び出しは送信され、コンソールに [kaleidr] the map frame has not reported ready と表示されます。エラー表示中のフレームには移動・変更する地図がありません。
要素の style-id を変えても効果がない	仕様どおりです。style-id はマウント時に一度だけ読み取られます。	handle.setStyle を使うか要素を挿入し直します。

制限事項

• ページから Tile 地図にマーカー、レイヤー、ポップアップを追加できず、クリックやカメラのイベントも取得できません。ただし接続されたチャットは場所をマークできます。
• 現在のカメラを読み出すメソッドはありません。
• Kaleidr ベースマップの表示には Tile 製品を使用します。
• ページのオリジンがキーに許可されていない場合、Tile 地図は表示されません。

次のステップ

• Tile リファレンス：すべてのオプション、属性、メッセージ。
• フレームワーク統合：React、Next.js、Vue で余分な読み込みを増やさずマウント・破棄する方法。
• Chat：地図にアシスタントを追加する方法。
• クォータとレート制限：地図読み込み枠。