Viewer
Viewerを使うとKaleidr Studioで公開した地図を自分のページに配置できます。地図はKaleidrがホストするiframeで描画されるため、地図ライブラリやAPIキーはページ側に必要ありません。公開済み地図のIDだけで埋め込めます。
Studioですでに作成した地図を訪問者に見せたい場合にViewerを使います。店舗検索、キャンパスマップ、イベントのルート、記事内のデータマップなどに適しています。
概要
| 質問 | 回答 |
|---|---|
| 必要なものは？ | 公開済み地図のID。APIキーもセッションも不要です。 |
| 対応プランは？ | Freeを含むすべてのプラン。公開にはKaleidrアカウントが必要です。 |
| 表示方法は？ | https://map-embed.kaleidr.comが配信するiframe内に表示します。 |
| 表示内容は？ | 作者が公開した地図のマーカー、ルート、スタイル付きレイヤー、Studioのデータパネルからアップロードされたデータセットや画像オーバーレイです。 |
| 埋め込み方法は？ | 通常の<iframe>、またはSDKの<kaleidr-map product="viewer">要素を使います。 |
| 料金は？ | 閲覧1回につき地図所有者の組織にマップ読み込み1回が計上されます。 |
| ページから地図を操作できる？ | カメラの設定・移動と読み込み・エラーメッセージの受信のみが可能です。 |
最小限の埋め込み
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer"
share-id="YOUR_MAP_ID"
style="display:block; height:480px"></kaleidr-map>
YOUR_MAP_IDを、公開後にStudioの埋め込みコードに表示されるIDに置き換えてください。要素はデフォルトでdisplay:blockなのでheightが有効です。サンプルではSafari 16.4より前の環境向けにもdisplay:blockを明示しています。古いSafariではインライン要素のままでheightが無視されます。
ページにスクリプトを追加できない場合（Webサイトビルダー、CMS、HTML対応のニュースレター作成ツールなど）は、代わりにStudioが生成するiframeを使ってください。
<iframe
src="https://map-embed.kaleidr.com/embed/YOUR_MAP_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>
どちらの方法でも同じ地図が表示されます。公開済み地図を埋め込むで使い分けを説明しています。
動作の仕組み
- Studioで地図を公開すると、IDと埋め込みコードが発行されます。
- ページがコードを読み込みます。SDK要素または通常のiframeは
https://map-embed.kaleidr.com/embed/YOUR_MAP_IDを参照します。 - iframe内のページが公開済み地図を取得し、作者がアップロードしたデータセットや画像オーバーレイとともに描画します。許可ドメインのリストがある場合は、先にページのドメインを確認します。
- 地図の描画が完了するとiframeは
kaleidr-embed:readyをページに送信します。描画できなければkaleidr-embed:errorを送信し、地図の代わりに短い説明を表示します。
ページが地図データを受け取ることはなく、iframeの中にもアクセスできません。地図ライブラリ、スタイル、ネットワークリクエストはすべてiframe内にあるため、コンテンツセキュリティポリシーではフレームだけを許可すれば済みます。
訪問者ができること
- 地図を移動・回転・傾斜し、地図上のズームボタン、ピンチ操作、スクロールホイールで拡大できます。ポインターが地図上にあるときは、Studioと同じくスクロールで地図がズームします。ポインターが地図の外にあるときは、スクロールでページが動きます。
- ブラウザーの許可を得たうえで、位置情報ボタンで現在地を表示できます。
- 作者がStudioで有効にした場合は、地図をクリックして場所のポップアップを開けます。
- 地図下部の凡例やクレジット表記を読めます。
- 地図について Kaleidr AI に質問できます。作者が Studio の Kaleidr AI タイルで Control Tower をオンにしていれば Ask Kaleidr パネルで、Popup Window がオンならポップアップで質問できます。公開地図で Kaleidr AI を使うを参照してください。
埋め込み地図は 読み取り専用です。訪問者は地図を編集できず、訪問者の操作は保存されません。
ページからできること
- 初期カメラを設定：
center、zoom、pitch、bearingを使用します。デフォルトは作者が保存したビューです。ページから指定したフィールドが個別に優先されます。 - 後からカメラを移動：
handle.setCamera(...)を呼ぶか要素のカメラ属性を変更します。 - 読み込みや失敗を把握：iframeから届く2種類のメッセージを監視します。
- 地図を削除：
handle.destroy()を呼ぶか要素を削除します。
地図所有者向けの設定
これらは埋め込みコードではなくStudioで設定します。
- 公開と公開解除。 公開済み地図にはStudioで現在保存されている内容が表示されます。保存した編集は再公開せずとも次に埋め込みが読み込まれると公開されます。再公開は同じリンクを保ったまま新しい公開バージョンを記録します。非公開で編集する場合は、先に公開を解除し、完了後に再公開してください。公開解除は地図のすべての埋め込みを停止し、再公開すると同じURLが復活します。地図の公開を解除するを参照してください。
- アップロードデータ。 公開済み地図に描画されるデータセットと画像オーバーレイは訪問者に表示されます。提供を止めるにはデータパネルでデータセットを削除するか、地図の公開を解除します。共有リンクは公開解除後も機能しますが、データセットを削除すると共有リンクからも消えます。公開地図は公開情報なので、誰でも閲覧できるデータだけを公開してください。公開済み地図のアップロードデータを参照してください。
- 許可ドメイン。 地図を表示できるサイトを制限します。判定にはページが送るリファラーを使うため、リファラーを送らないページにはドメイン制限付き地図を表示できません。
- Kaleidr AI。 地図の Kaleidr AI タイルで、Ask Kaleidr パネル（Control Tower）とポップアップ内の AI チャット（Popup Window）をオンにします。
制限事項
- キーを使わないため、許可オリジンなどのキーに基づく制限は適用されません。地図の許可ドメインを使ってください。
- ページから地図のレイヤーを読み取ったり、マーカーを追加したり、クリックイベントを受け取ったりできません。
- 埋 め込みは自動で高さを調整しません。要素またはiframeに高さを指定してください。
- 所有者の組織が期間中のマップ読み込み枠を使い切ると、枠がリセットされるまで地図の代わりに上限メッセージを表示します。
- 訪問者は地図に表示するすべてのデータセットを丸ごとダウンロードするため、大きな表を使う地図は表示に時間がかかります。
次のステップ
- 公開済み地図を埋め込む：公開、埋め込み、ドメイン制限、動作確認。
- Viewerリファレンス：全オプション、ハンドル、メッセージ、エラーコード。
- 公開済み地図でのチャット：訪問者が地図について質問できるようにします。
- コンテンツセキュリティポリシー：Viewer埋め込みに必要な2つのディレクティブ。