クイックスタート

このページでは、多くのチームが必要とする順番に、最短で動作する3つの連携方法を紹介します。

1. 既存の地図でChatを使う。 場所に関する質問に答え、地図上にピン、カメラ移動、経路を表示するチャットパネルです。
2. 公開した地図を埋め込む。 Kaleidr Studioで設計した地図を自分のページに表示します。
3. ベースマップを表示する。 Kaleidrのデザイン済みベースマップをそのまま利用します。

どの方法も1つのHTMLファイルで実行できます。3つとも Free プランに対応しています。

方法	製品	必要なキー	表示場所
既存の地図でChat	chat	公開可能キー	既存の地図上、ページ内
公開済み地図	viewer	不要	Kaleidrのiframe内
ベースマップ	tile	公開可能キー	Kaleidrのiframe内

最初に全体の仕組みを理解したい場合はKaleidrの仕組みを、どの製品が必要か迷う場合は方法の選択を参照してください。

開始前の準備

• Kaleidrアカウント。 kaleidr.com で登録します。このページの内容にはFreeプランで十分です。

• Chatとベースマップ用の公開可能キー。 kaleidr.com/api-keys で作成します。接頭辞は kld_pk_live_ です。手順はAPIキーを取得を参照。公開済み地図にはキーは不要です。

• ページを配信するWebサーバー。 ローカルでもHTTPで配信してください。ファイルのあるフォルダーから次のいずれかを実行できます。

  python -m http.server 8000
  # or
  npx serve -l 8000

  次に http://localhost:8000/your-file.html を開きます。ディスクから直接開かないでください。file:// のページにはキーの許可オリジンに登録できるオリジンがありません。

• キーに許可オリジンがある場合はページのオリジンを登録。 許可リストのないキーはどのサイトでも使えます。リストがある場合は登録したサイトだけなので、テスト時には http://localhost:8000 を追加します。

• サイトがコンテンツセキュリティポリシーを設定している場合はKaleidrの通信を許可。 Content-Security-Policy ヘッダーがなければ追加の設定は不要です。ある場合はコンテンツセキュリティポリシーを参照してください。

どの方法も同じスクリプトタグから始めます。自分で読み込むファイルはこれだけで、製品をマウントすると対応するコードが自動的に読み込まれます。

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

既存の地図でChatを使う

MapLibre GL JSの地図と、その中にドッキングしたチャットパネルを作ります。「Where can I get ramen near Bryant Park?」と尋ねると、回答がストリーミングされ、場所ごとのピンが表示されてカメラが移動します。

この例はMapLibre GL JSを使いますが、ChatはMapbox GL JS、Google Maps JavaScript API、Leafletにも接続できます。対応地図を参照してください。

1. ページを作成する

ファイルを chat.html として保存し、kld_pk_live_… をお使いの公開可能キーに置き換えます。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

このファイルでは次の3点が重要です。

• 地図ライブラリをページのグローバルとして公開する。 Chatは window.maplibregl からMapLibreを参照します。スクリプトタグで読み込むと自動的に設定されます。npmからインポートする場合は、マウント前に window.maplibregl = maplibregl を自分で設定してください。
• map は地図オブジェクトです。 CSSセレクターではなく、作成したインスタンスを渡します。
• contained: true には配置設定と高さのある領域が必要です。 パネルはマウント先の中に表示されます。contained がなければ、ページ上の地図の位置に関係なくブラウザー画面左上の固定ウィンドウになります。

デモのスタイルは情報量の少ない世界地図です。ピンの座標は正しいですが、道路を確認するには自分の地図スタイルを使ってください。

2. 配信して質問する

ファイルのフォルダーでローカルサーバーを起動し、http://localhost:8000/chat.html を開きます。

確認する内容：

• 地図が画面を埋め、地図の左上に入力欄のあるチャットパネルが表示されます。
• ブラウザーのNetworkタブで https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions へのリクエストが 200 を返します。これはSDKがキーを短期セッションに交換したことを示します。
• 場所について Where can I get ramen near Bryant Park? などと入力すると、回答がテキストでストリーミングされ、場所ごとのピンが表示され、すべてが収まるようにカメラが動きます。Networkタブには回答配信中に開いたままの …/b2b/v1/chat/control/stream リクエストが見えます。
• コンソールに [kaleidr を含むエラーが表示されません。

3. 動作しない場合

症状	原因	対処
パネルがなく、…/sdk/sessions のCORSエラーと [kaleidr:chat] エラーが表示される	キーが間違っている、失効している、またはページのオリジンが許可リストにない。APIにCORSヘッダーが付かず、ブラウザーがCORSエラーとして報告する	キーを確認します。kaleidr.com/api-keys でポートを含む正確なオリジンを追加するか、テスト中はリストを空にします。
パネルが地図内ではなくブラウザー画面の左上に出る	contained: true がない、またはマウント先が適切に配置されていない	contained: true を渡し、対象に position: relative と高さを指定します。
回答は届くがピンがない	地図ライブラリがページのグローバルにないため、Chatがピンを作れない	スクリプトタグで読み込むか、Kaleidr.mount の前に window.maplibregl を設定します。

トラブルシューティングでは、各症状をコンソールメッセージとともに説明しています。

次はMapLibreにChatを接続の詳細手順と、パネルの機能をまとめた機能と制限をご覧ください。

公開済み地図

Kaleidr Studioで設計した地図を自分のページに表示します。この方法ではAPIキーは不要で、公開地図のIDだけで埋め込めます。

1. 地図を公開しIDをコピーする

1. Kaleidr Studio で地図を開いて Publish を選びます。
2. Publish & embed ページで Go Live を押します。
3. Embed code のスニペットをコピーします。IDはそのURLの最後の部分です。https://map-embed.kaleidr.com/embed/abc123 なら abc123 がIDです。

確認する内容： プロジェクトの状態が live になり、埋め込みコードの下に訪問者に表示される地図のライブプレビューが現れます。

2. ページを作成する

map.html として保存し、YOUR_SHARE_ID をコピーしたIDに置き換えます。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

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

要素には高さが必要です。指定しないと地図の高さは500ピクセルになります。<kaleidr-map> はデフォルトで display:block なので高さを指定できます。例にも display:block を明記してあります。これは通常のブラウザーでは無害で、16.4以前のSafariで要素がインラインになり高さを適用できない問題も防ぎます。

サイトビルダーやCMSの入力欄など、ページにスクリプトを追加できない場合は、Studioの iFrame タブが生成する通常のiframeを使います。ローダーは必要ありません。

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. 配信する

http://localhost:8000/map.html を開きます。

確認する内容：

• 高さ480ピクセルでページ幅いっぱいの地図が表示され、Studioで保存した視点から始まります。
• ポインターを地図上に置いてスクロールすると地図がズームします。ポインターを地図の横に置いてスクロールするとページが動きます。
• Elementsパネルで <kaleidr-map> 要素内に <iframe> があり、そのURLが https://map-embed.kaleidr.com/embed/ から始まります。

フレームに "This map isn't available — it may have been unpublished, paused, or the link is incorrect." と表示されたら、IDが誤っているか地図が公開されていません。"This map isn't allowed to render on this site. Please contact the map owner." と表示されたら、別のドメインだけで表示できるよう制限されています。

この方法の続きは、表示可能なドメインを制限する地図の埋め込みと、訪問者がキーなしで質問できる公開地図でのChatをご覧ください。

ベースマップ

Kaleidrが設計したベースマップをページに表示します。地図ライブラリのインストールもスタイルの作成も不要で、完成したインタラクティブな地図が使えます。

1. ページを作成する

basemap.html として保存し、kld_pk_live_… を自分の公開可能キーに置き換えます。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

• style-id はベースマップを指定します。必ず設定してください。kaleidr-morning は汎用スタイルの1つです。他の種類はTileをご覧ください。
• center は longitude,latitude の順です。zoom を指定するときは必ず center も指定してください。center がない zoom は無視されます。

2. 配信する

http://localhost:8000/basemap.html を開きます。

確認する内容：

• マンハッタンのミッドタウンを中心とした高さ480ピクセルのベースマップ。
• Networkタブで https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions が 200 を返し、その後 https://map-embed.kaleidr.com からiframeが読み込まれます。
• ポインターを地図上に置いてスクロールするとズームします。

何も表示されず …/sdk/sessions のCORSエラーが出る場合、Chatの例と同じくキーが間違っているかオリジンが許可リストにありません。

Tileのセッション1件ごとに、組織の月間地図ロード枠から1回分が計上されます。割当量とレート制限を参照してください。

続きは、実行中にスタイルを切り替えたりカメラを操作したりできるTileの利用をご覧ください。

読み込んだもの

3つの方法はいずれも次の2つの要素を使いました。

• Kaleidr.mount(target, options) はJavaScriptから製品をマウントし、すぐにハンドルを返します。製品のコードはバックグラウンドで読み込まれ、準備前に呼び出したハンドルの操作は保持され、準備後に適用されます。
• <kaleidr-map> はHTMLから同じことを行います。属性名はオプション名をハイフン付きで表したもの（share-id、style-id、publishable-key）です。ただし enabled オプションは flag 属性、Chatの title オプションは chat-title 属性になります。

自分の地図でChatを使うときはライブ地図オブジェクトが必要なため Kaleidr.mount を使います。それ以外の製品ではどちらの方法も使用できます。

どの製品のハンドルにも destroy() があります。その他のメソッドは製品によって異なります。たとえば setCamera は viewer、tile、editor で動作しますが chat では動作しません。Chatではアシスタントが地図を動かし、自分でカメラを操作するときは地図ライブラリのAPIを使います。対応表は<kaleidr-map> 要素を参照してください。

現時点での制限

• Chatは独自のピン、経路、カメラ移動を追加します。 既存のレイヤーやマーカーを変更したりKaleidrに送ったりせず、ホストページにイベントも通知しません。機能と制限を参照。
• ViewerとTileはiframe内で動作します。 独自のレイヤーやマーカーを追加できません。独自のレイヤーが必要なら既存の地図を維持し、Chatを接続してください。
• Kaleidrのベースマップを表示する方法はTileです。 自分の地図ライブラリにKaleidrのスタイルやタイルを直接読み込む方法はサポートされていません。
• SDKはWebページ向けです。 npmパッケージとネイティブモバイルSDKはありません。バックエンドからはサーバーAPIを呼び出します。
• キーを使用するマウントでは利用枠を消費します。 Chatの回答は組織のAIクレジットを消費し、Tileのセッションは地図ロード数を消費します。Kaleidrの仕組みを参照してください。

次に選ぶ方法

やりたいこと	参照ページ
Mapbox GL JSにChatを接続	MapboxにChatを接続
MapLibre GL JSにChatを接続	MapLibreにChatを接続
Google MapsにChatを接続	Google MapsにChatを接続
LeafletにChatを接続	LeafletにChatを接続
パネルの位置やブランドカラーを調整	テーマとレイアウト
公開地図上で訪問者にChatを使わせる	公開地図でのChat
公開地図を埋め込み、表示ドメインを制限	地図の埋め込み
ベースマップを表示し、スタイルを切り替える	Tileの利用
ページに地図エディターを追加	Editorの接続
React、Next.js、VueからSDKを使用	フレームワーク
バックエンドからKaleidrを呼び出す	サーバークイックスタート
自社業務データを回答に使用	自社データ
本番環境に公開	本番運用チェックリスト