Kaleidr Chat を Mapbox の地図に追加する

このガイドを終えると、Mapbox GL JS の地図と、その中に配置されたチャットパネルを備えたページが完成します。訪問者が質問すると回答が順に表示され、回答内の場所が地図上にピンとして示され、カメラがそれらを映す位置へ動きます。Free を含む全プランで公開可能キーを使って利用できます。質問は組織の AI クレジットを消費します。

事前準備

kaleidr.com/api-keys で発行した Kaleidr 公開可能キー（kld_pk_live_…）。新しいキーには Chat が必要とする ai スコープが付与されます。API キーを取得するを参照してください。
制限がある場合、ページのオリジンをキーの許可オリジンに登録します。ローカルでは http://localhost:8080 などです。
Mapbox アカウントから取得した Mapbox アクセストークン（pk.…）。Mapbox は地図を、Kaleidr は質問をそれぞれ課金します。
script タグで Mapbox GL JS を読み込み、window.mapboxgl が存在すること。npm でインポートする場合はインポートしたライブラリをグローバルに公開するを参照してください。
npx serve または python -m http.server 8080 などの HTTP サーバー。ディスクから直接開く方法は動作しません。
コンテンツセキュリティポリシーを設定している場合は、コンテンツセキュリティポリシーにあるホストを許可します。

ステップ 1：地図とチャットレイヤーを配置する

地図とチャットのマウント先を一つの位置指定コンテナーに置きます。チャットレイヤーは地図の上に重なり、ポインター操作は透過させます。

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:absolute; inset:0; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

**確認できること：**まだ何も表示されず、高さ 520 px の空白領域だけができます。テーマとレイアウトに各設定の説明があります。

ステップ 2：Mapbox GL JS を読み込み地図を作成する

スタイルシートをページの head に、スクリプトを自分のコードより前に読み込みます。スタイルシートがないと地図が正しく表示されません。

<link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
<script>
  mapboxgl.accessToken = 'pk.…';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

**確認できること：**ドラッグとズームができるロンドン中心部の Mapbox 地図が表示されます。

ステップ 3：`kaleidr.js` を読み込む

Mapbox のスクリプトの後、パネルをマウントするコードの前に Kaleidr ローダーを追加します。

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

**確認できること：**画面に変化はありません。コンソールで Kaleidr.version を読むとバージョン文字列が返ります。

ステップ 4：チャットパネルをマウントする

キーと実際の地図オブジェクトを渡します。

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
});

地図の load イベントを待つ必要はありません。Kaleidr.mount はすぐに返り、チャットバンドルの読み込みとキーからセッションへの交換が終わるとパネルが表示されます。

**確認できること：**地図の左上に「Ask Kaleidr」と書かれた入力バーが表示されます。

完全なページ

index.html として保存し、2 つのキーを置き換えて HTTP でフォルダーを配信します。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on Mapbox</title>
    <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      mapboxgl.accessToken = 'pk.…';

      const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v12',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      const handle = Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

動作のしくみ

訪問者	パネル	Mapbox 地図
質問を送る	チャットウィンドウが開き、回答文が順に表示されます。	まだ変化しません。
待つ	回答内の場所ごとに結果カードを表示します。	場所が特定されるたびにピンが現れます。1 件ならそこへカメラが移動し、複数ならパネルを避ける余白を取って全件を表示します。
ピンや結果をクリック	概要、写真、経路案内付きの場所カードを開きます。	結果のクリックでカメラをその場所へ動かします。
経路を要求	距離と所要時間を示します。	経路線を描画し画面内に収めます。
続けて質問	同じ会話に質問を追加します。	新しいピンが増え、以前のピンも残ります。
チャットを閉じる	入力バーに戻って会話が終了します。	ピンと経路は削除されます。

Mapbox GL JS 固有の動作：

ピンには HTML 要素を持つ Mapbox の Marker オブジェクトを使います。独自のマーカーとは別管理です。
経路はパネルがスタイルに追加するソースとレイヤーで描画され、後で削除されます。既存のソースとレイヤーには触れません。
パネルのマウント中、セッションは自動更新されるため、トークン管理は不要です。

動作を確認する

ページ上で

Ask Kaleidr 入力バーが地図左上にあります。
Show me three museums in London と入力して Enter を押します。回答が順に表示され、3 つのピンが現れ、地図が全体を表示します。

コンソールで

[kaleidr を含むエラーや警告がありません。

Network タブで

リクエスト	期待値
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200、次の例と同様の JSON 本文
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream`（質問後）	200、`content-type: text/event-stream`

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat" }

動作しない場合

SDK は短いメッセージのみを記録し、サーバーが示す理由は繰り返しません。失敗した場合は Network でリクエストを開き、JSON 応答を確認してください。403・404 のコードは detail、429 のコードは error に入り、429 では detail に説明文も入ります。

症状	原因	対処
パネルがなく `…/sdk/sessions` の CORS エラーと `[kaleidr:chat]` エラーが出る	キーが不明・失効している、またはオリジンが許可されていません。API は許可されたオリジンのみに CORS ヘッダーを送ります。	kaleidr.com/api-keys でキーを確認し、スキーム・ポートを含む正確なオリジンを追加します。
`[kaleidr:chat] kaleidr session exchange failed (403)`	キーは有効でも Chat を使う権限がありません。`detail` は `insufficient_scope`（`ai` がない）、`product_not_allowed`（別製品限定）、`tier_capability_not_allowed` のいずれかです。	`ai` があり `chat` を許可するキーを使用します。
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	サーバーキーを渡しました。リクエストは送信されません。	公開可能キー（`kld_pk_live_…`）を使い、サーバーキーを公開していた場合は失効させます。
`[kaleidr:chat] mount target not found: #chat`	セレクターが対象を見つけられません。	要素を作成してから `mount` を呼ぶか、要素そのものを渡します。 `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	CSP または広告ブロッカーがバンドルを妨げています。	`script-src` に `https://cdn.kaleidr.com` を許可します。
`Kaleidr is not defined`	`kaleidr.js` より先にコードが実行されました。`async` や `defer` が原因の例です。	通常の script タグで先に読み込むか、スクリプトの `load` イベントから実行します。 `kaleidr.js`
`[kaleidr] embed is disabled — …`	有効化ゲートがマウントを止めています。	メッセージに設定元が示されます。kaleidr.jsを参照してください。
パネルが地図ではなくブラウザーウィンドウ左上に出る	`contained` がないか `#chat` が位置指定されていません。	`contained: true` とステップ 1 の CSS を指定します。
回答は出るがピンがなく地図も動かない	`map` に渡されたオブジェクトを認識できません。	実際の `mapboxgl.Map` インスタンスを渡します。対応する地図を参照。
1 件へは移動するがピンがなく複数件が収まらない	`window.mapboxgl` がありません。1 件への移動には地図オブジェクトのみが必要ですが、ピンと複数件の調整にはグローバル変数が必要です。	npm から読み込む場合、マウント前に `window.mapboxgl` を設定します。npm インポートを参照。
毎回「Sorry — that didn't go through. Please try again.」と表示	キーの失効や許可オリジンの変更によりセッションが無効です。	キーを確認してページを再読み込みします。
「You've reached your usage limit for now.」と表示	429：AI クレジット切れまたはキーのレート制限。同じキーの訪問者全員がレート制限を共有します。	クォータとレート制限を参照してください。
地図をドラッグできない	チャットレイヤーが操作を遮っています。	`#chat` に `pointer-events:none` を設定します。

ほかの症状はトラブルシューティングを参照してください。

制限事項

ページにはパネルからコールバックやイベントが届きません。質問、回答、ピンのクリックをコードで受け取れません。
アシスタントは独自レイヤー、マーカー、表示領域を認識しません。質問とともに送信されるのはズームレベルのみです。
パネル経由で独自の指示やデータをアシスタントへ渡すことはできません。
回答の言語、パネルタイトル、プレースホルダーはマウント時の lang、title、placeholder で指定します。Chat リファレンスを参照してください。その他のラベルは英語です。
Chat マウントでは handle.setCamera() は警告のみで機能しません。Mapbox API でカメラを動かしてください。
SPA では地図ビューが破棄される際に handle.destroy() を呼び、戻るとき再マウントしてください。

全項目は機能と制限を参照してください。

次のステップ

テーマとレイアウト：サイトに合わせてパネルを調整。
Chat リファレンス：すべてのオプション、ハンドル、エラー。
本番環境チェックリスト：公開前の確認事項。
フレームワーク：React、Next.js、Vue からマウント。

事前準備​

ステップ 1：地図とチャットレイヤーを配置する​

ステップ 2：Mapbox GL JS を読み込み地図を作成する​

ステップ 3：kaleidr.js を読み込む​

ステップ 4：チャットパネルをマウントする​

完全なページ​

動作のしくみ​

動作を確認する​

動作しない場合​

制限事項​

次のステップ​