Google マップに Kaleidr Chat を追加する

このガイドを終えると、Google マップの中にチャットパネルを配置したページが完成します。訪問者が質問すると回答がパネルにストリーミング表示され、回答に登場する場所が Google マップ上のピンになり、カメラもその場所を表示するように動きます。公開用キーがあれば Free を含むすべてのプランで利用できます。質問には組織のAIクレジットが消費されます。

Google Maps のキーと Kaleidr のキーは別のものです。地図の料金は Google、質問の料金は Kaleidr が請求します。Kaleidr が Google キーを受け取ることはありません。

事前準備

kaleidr.com/api-keys から取得した Kaleidr 公開用キー (kld_pk_live_…)。新しいキーには Chat が必要とする ai スコープが含まれます。APIキーの取得を参照してください。
許可オリジンを指定している場合は ページのオリジンをキーの許可一覧に追加してください。ローカル開発では http://localhost:8080 のように実際に配信するオリジンを追加します。
Google Cloud プロジェクトの Google Maps JavaScript API キー。Maps JavaScript API が有効で、リファラー制限でページのオリジンが許可されている必要があります。
npx serve や python -m http.server 8080 など、HTTP でページを配信する方法。ディスク上のファイルを直接開いても動作しません。
コンテンツセキュリティポリシーを使うサイトでは、Google Maps が必要とするホストに加え、コンテンツセキュリティポリシーに記載のホストを許可してください。

Google Maps JavaScript API は常に google.maps グローバルを定義するため、チャットバンドルにライブラリを公開する追加手順は不要です。

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

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

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

地図要素は height:100% でラッパー全体を占めます。position:relative と z-index:0 を組み合わせると、Google のレイヤーが地図要素内のチャットレイヤーより下に配置されます。

表示されるもの: この段階では高さ 520 px の空白領域だけです。

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

地図のコールバックが実行されるまでに Kaleidr が存在するよう、通常の script タグで Kaleidr ローダーを読み込んでください。

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

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

ステップ3：地図を作成してパネルを取り付けるコールバックを定義する

Google Maps スクリプトは読み込み完了時に指定された関数を呼び出します。その時点より前には google.maps が存在しないため、地図の作成とパネルの取り付けはその関数内で行ってください。

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

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

表示されるもの: まだ変化はありません。関数は定義されましたが呼び出されていません。

ステップ4：コールバックの後に Google Maps スクリプトを読み込む

Google の script タグは initMap を定義するスクリプトの後ろに配置してください。

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

読み込み順序は重要です。Google のスクリプトには async が設定されているため、ダウンロード後すぐに実行されて initMap を呼び出します。Google のタグを先に置くと、ブラウザが initMap の定義を読む前に処理が進み、「initMap は関数ではない」と報告される可能性があります。コールバックを先に定義すると、この競合を避けられます。

表示されるもの: ロンドン中心部の Google マップと、左上に 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 Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; 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>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

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

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

動作のしくみ

訪問者	パネル	Google マップ
質問を送信	チャットウィンドウが開き、回答テキストがストリーミング表示される	まだ変化なし
待機	回答中の場所ごとに結果カードを表示	場所が特定されるとピンを表示。1か所ならそこへパンしてズームを変更し、複数なら上下左右 56 px の余白を付けて全件が入るよう調整します。
ピンや結果をクリック	概要・写真・道順ツールを備えた場所カードを開く	結果を選ぶとその場所へ移動
道順をリクエスト	ルートの距離と時間を表示	経路線を描画して画面に収める
別の質問をする	同じ会話に追加	新しいピンが加わり、以前のピンは残る
チャットを閉じる	入力バーに戻り会話が終了	ピンと経路が削除される

Google Maps 固有の動作:

ピンはカスタムオーバーレイに描画される HTML 要素です。 Map ID は不要です。ただしページで Google の marker ライブラリを読み込むと高度なマーカーが使用され、その場合は mapId が必要です。
1か所への移動はパン後にズームを変更する方式であり、1回の飛行アニメーションではありません。
複数地点を収める際は四辺すべてに 56 px の余白を使用します。 チャットパネルの領域は考慮しないため、結果がパネルの下に隠れる場合があります。訪問者は地図の移動やパネルの最小化ができます。
経路は2本のポリラインで、白い縁取りの上に色付きの線を描きます。
地図は平面の北向きとして扱われ、アシスタントは方位や傾きを設定しません。
パネルの取り付け中はセッションがバックグラウンドで更新されます。トークンを自分で管理する必要はありません。

動作を確認する

ページ上で

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

コンソールで

[kaleidr を含むエラーや警告、および Google Maps API のエラーがないことを確認します。

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 に説明文も入ります。

症状	原因	対処
地図が出ず、Google が `initMap is not a function` と表示	`initMap` の定義前に Google スクリプトが動いた	ステップ4のように Google のタグをコールバックの後へ移動します。
地図がない、または Google のエラーダイアログ付きの灰色地図	Google キーで Maps JavaScript API が無効、課金設定がない、またはオリジンが未許可	Kaleidr とは独立した問題です。Google Cloud プロジェクトで修正してください。
`initMap` 内で `Kaleidr is not defined`	`kaleidr.js` に `async` / `defer` がある、または Google スクリプトより後に読み込んだ	通常の script タグで `kaleidr.js` を先に読み込んでください。
地図は出るがパネルがなく、`…/sdk/sessions` の CORS エラーの後に `[kaleidr:chat]` のエラー	Kaleidr キーが不明または失効、あるいはページのオリジンが許可一覧にない。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] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	コンテンツセキュリティポリシーまたは広告ブロッカーでバンドルがブロックされました。	`script-src` で `https://cdn.kaleidr.com` を許可します。
パネルが地図ではなくブラウザ左上に出る	`contained` がない、または `#chat` の位置指定がない	`contained: true` とステップ1のスタイルを追加します。
パネルが地図の背後に隠れる	地図要素に独立したスタッキングコンテキストがない	`#map` の `z-index:0` と `#chat` の `z-index:1` を維持します。
パネルは回答するがピンが出ず、地図も動かない	`map` に渡したのが `google.maps.Map` インスタンスではなくDOM要素やラッパーなど	`new google.maps.Map(…)` が返したオブジェクトを渡します。対応地図を参照。
回答と地図移動はできるがピンが出ない	`marker` を読み込んでいるが `mapId` がない	地図オプションに `mapId` を追加するか `marker` を読み込まないでください。
毎回「送信できませんでした。もう一度お試しください。」と表示	キーが失効したか許可オリジンが変更され、セッションが無効	キーを確認してページを再読み込みします。
「現在の使用上限に達しました。」と表示	429: 組織のAIクレジット不足またはキーのレート制限。ページの全訪問者が制限を共有します。	クォータとレート制限を参照してください。

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

制限事項

ページ側にはパネルからのコールバックやイベントは届きません。質問・回答・ピンのクリックにコードで反応できません。
アシスタントは独自のオーバーレイ、マーカー、現在表示中の領域を認識しません。質問に送られる地図情報はズームレベルだけです。
パネルを通してアシスタントに独自指示やデータを与えることはできません。
回答言語、パネルのタイトル、入力欄のプレースホルダーは lang、title、placeholder のマウントオプションです。Chat リファレンスを参照してください。それ以外の表示ラベルは英語です。
Google Maps の範囲調整ではチャットパネルを避けません。
Chat マウントでは handle.setCamera() は何もせず警告を出します。Google 自身のAPIで地図を移動してください。
SPA では地図ビューを削除するときに handle.destroy() を呼び、戻ってきたら再マウントしてください。

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

次のステップ

テーマとレイアウト: サイトに合うようパネルを調整。
対応地図: Google Maps 上で可能な操作。
Chat リファレンス: オプション、ハンドル、エラー。
本番運用チェックリスト: 公開前の確認項目。

事前準備​

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

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

ステップ3：地図を作成してパネルを取り付けるコールバックを定義する​

ステップ4：コールバックの後に Google Maps スクリプトを読み込む​

完全なページ​

動作のしくみ​

動作を確認する​

動作しない場合​

制限事項​

次のステップ​