メインコンテンツまでスキップ

Tile

Tileを使うと、Kaleidrのベースマップをページに追加できます。kaleidr-morningやkaleidr-nightなどのスタイルを選ぶと、SDKがKaleidrのホストするiframe内に表示します。ページ側で地図ライブラリを読み込む必要はありません。

独自の描画は不要で、見栄えのよいインタラクティブなベースマップが必要な場合にTileを使います。所在地の背景、「所在地はこちら」のパネル、Kaleidrのチャットが回答を地図上に表示する用途などに適しています。

独自のMapbox、MapLibre、Google Maps、Leafletの地図をすでに使用している場合、Tileは不要です。その地図にChatを接続してください。

概要​

質問回答
必要なものは？公開可能キー（kld_pk_live_…）で、mapsスコープを持つもの。新しいキーにはデフォルトで含まれます。
対応プランは？Freeを含むすべてのプラン。
表示方法は？https://map-embed.kaleidr.comが配信するiframe内。
外観の選択方法は？style-idで指定します。下に汎用スタイル6種類を示します。
料金は？Tileセッションごとにマップ読み込み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>

必要なのは次の3点です。

  1. キー。 kaleidr.com/api-keysで公開可能キーを作成します。APIキーを取得するを参照してください。
  2. 許可されたオリジン。 キーに許可オリジンが設定されている場合、ページのオリジンを含めてください。ディスクから直接開かず、HTTPまたはHTTPSでページを配信してください。
  3. 高さ。 要素はデフォルトでdisplay:blockなのでheightが適用されます。サンプルには、要素がインラインになるSafari 16.4より前の環境向けにdisplay:blockも明示されています。

スタイル​

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

必ずstyle-idを指定してください。省略すると、設定されていれば組織のデフォルトベースマップが使われ、なければエラーが表示されます。

動作の仕組み​

  1. SDKは公開可能キーをKaleidrへ送信し、短期間有効なTileセッションを受け取ります。この段階でキー、スコープ、ページのオリジンを確認し、マップ読み込み1回を計上します。設定されている場合、応答には組織のデフォルトベースマップも含まれます。Tileセッションの用途はここまでで、地図はそれを使って追加のリクエストを送りません。
  2. SDKは要素の内容を指定スタイルのiframeに置き換えます。フレームのURLにはスタイルIDと指定したカメラ情報のみが含まれ、公開可能キーやセッショントークンは含まれません。
  3. 地図はiframe内で描画されます。ページのコンテンツセキュリティポリシーはローダー、セッションリクエスト、フレームを許可すれば十分です。
  4. 描画が完了するとiframeはページへkaleidr-embed:readyメッセージを送信します。

訪問者ができること​

地図のパン、回転、傾斜、地図上のボタンやピンチ、スクロールホイールによるズームができます。ポインターが地図上にあるときはスクロールで地図がズームし、ポインターが地図の外にあるときはスクロールでページが動きます。

ページからできること​

  • 初期カメラを設定：center、zoom、pitch、bearingを使用します。
  • 後からカメラを移動：handle.setCamera(...)を使用します。
  • スタイルを切り替え：handle.setStyle('kaleidr-night')で再読み込みせずに変更できます。
  • チャットパネルを組み合わせる。 チャットのマウント先にTile要素を指定し、回答をその地図上に表示できます。
  • 読み込み完了を確認：kaleidr-embed:readyメッセージを受信します。

マップ読み込みの計測方法​

Tileの使用量は、公開済み地図の閲覧と同じ単位であるマップ読み込み回数で計測します。SDKがTileセッションを取得するたびに1回計上されます。

  • 地図をマウントしたとき。
  • マウントが続いている間、セッション期限の少し前にSDKが更新するたび。セッションはデフォルトで15分間有効です。
  • マウントを破棄して再マウントしたとき、または要素を削除して挿入し直したとき。

数分間ページを見る訪問者はマップ読み込みを1回使用します。1時間開いたままのページでは約5回になります。「ページ閲覧ごとに1回」ではないため、表示しなくなったTileのマウントは破棄してください。

組織が期間中のマップ読み込み枠を使い切ると、新しいTileセッションはHTTP 429で拒否されます。新しいマウントは何も表示しません。すでに表示されている地図はそのまま残ります。枠の詳細はクォータとレート制限を参照してください。

制限事項​

  • Tileはベースマップです。ページから独自のマーカー、レイヤー、ポップアップを追加したり、クリックやカメラのイベントを受け取ったりできません。組み合わせたチャットパネルは場所を表示できます。
  • Kaleidrのベースマップを表示するためのサポート対象はTile製品です。
  • マウント済み要素のstyle-idを変更しても何も起きません。handle.setStyleを使うか新しい要素を挿入してください。
  • Tile専用のキーはありません。他のKaleidr製品に使う公開可能キーをTileでも使います。

次のステップ​