Viewer リファレンス

product="viewer" は Kaleidr Studio で公開された地図を表示します。SDK はマウント先の内容を https://map-embed.kaleidr.com/embed/<id> を読み込む iframe に置き換えます。地図はその iframe 内で描画されます。

キー	不要です。指定しないでください。
プラン	Free を含むすべてのプラン。
表示場所	https://map-embed.kaleidr.com から読み込む iframe。
計測	表示ごとに地図読み込み 1 回。地図所有者の組織に計上されます。
CSP	script-src https://cdn.kaleidr.com と frame-src https://map-embed.kaleidr.com。

手順については公開済み地図の埋め込みを参照してください。

マウント

要素で指定する場合：

<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>

JavaScript から：

const handle = Kaleidr.mount('#map', {
  product: 'viewer',
  shareId: 'YOUR_MAP_ID',
});

SDK を使わない場合：

<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>

チャットバー

layout="bar" は Viewer をチャットバーに変えます。ページに置くのは質問欄 1 つだけで、訪問者が質問するまで地図は表示されません。質問すると公開地図が開き、地図の Kaleidr AI がそこで回答します。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
             chat-title="Ask about the neighborhood"
             prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>

回答は次のどちらかで開きます。

設定	質問したときの動作
results-url なし（既定）	地図がページの上にウィンドウ全体を覆って開き、質問を送ります。訪問者は閉じるボタンで閉じます。以降の質問も同じ地図に送られるため、会話が続きます。
results-url="/map"	ブラウザーが ?q=<question> 付きでそのページへ移動します。そのページで prompt-param="q" を指定した Viewer が、地図を開いたときに質問を送ります。ただし、訪問者が同じオリジンのページから来た場合に限ります。

結果ページ：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
             style="display:block; height:600px"></kaleidr-map>

• 回答するのは地図です。 質問は地図自身の Ask Kaleidr パネルに送られるため、地図で Control Tower がオンになっている必要があり（Studio の Kaleidr AI）、公開済み地図の Kaleidr AI のルールが適用されます。費用は所有者が負担し、どこで回答するかは地図の許可ドメインで決まります。Control Tower のない地図では、地図は開きますが質問は送られません。
• チャットバーは地図を読み込みません。 訪問者が質問した時点で地図が読み込まれ、地図読み込み 1 回として計上されます。
• チャットバーは専用のシャドウルートに描画されるため、 ページの CSS でスタイルが変わることはなく、そのスタイルに style-src の許可も不要です。幅は要素と同じで、高さは内容に合わせて決まります。
• チャットバー自身のラベルは lang に従い、 lang がなければ訪問者のブラウザー言語に従います。対応言語は英語、スペイン語、フランス語、ドイツ語、ポルトガル語、日本語、韓国語、中国語（簡体字・繁体字）、アラビア語です。指定した chat-title、placeholder、prompts は書いたとおりに表示されます。
• prompt は入力欄にあらかじめ入力し、handle.send() はコードから質問します。 handle.send('Parks nearby') はその質問を送り、handle.send() は入力欄の内容を質問します。

template.kaleidr.com のビルダーで、選んだ地図の両方のスニペットを生成できます。

スポットのレイアウト

layout="locator" と layout="listings" は、地図が描画するスポットライブラリのコレクションの一覧を、そのコレクションのフィルターとカードとともに、公開済み地図の横に表示します。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
             filters="search|category|open_now"
             style="display:block; height:600px"></kaleidr-map>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
             filters="price|beds|baths"
             style="display:block; height:720px"></kaleidr-map>

レイアウト	一覧	ピン
locator	距離順に並んだスポット。検索欄、現在地周辺 ボタン、フィルター、件数があります。一覧のどのスポットにも一致しない検索は、検索した場所へ地図を移動します。	Studio で設定したスタイルのコレクションのレイヤー。
listings	写真付きのカード。幅の広いフレームでは 2 列で、距離、価格の安い順、価格の高い順 で並べ替えられます。	価格ラベル。

• 幅 768 ピクセル以上のフレームでは一覧が地図の横に、 それより狭い場合は地図の上のシートに表示され、訪問者が上へドラッグします。
• 一覧と地図は連動します。 一覧でスポットを選ぶと地図がそこへ移動してカードを開き、ピンを選ぶと一覧がそこまでスクロールします。一覧、ピン、件数は常に同じスポットを表示します。
• 一覧には一度に 50 件を表示し、 さらに表示 で続きを表示します。
• 現在地周辺は訪問者に位置情報を求めます。 SDK が作成する iframe は許可していますが、直接の iframe には allow="geolocation" が必要です。
• コレクションを描画しない地図では、どちらのレイアウトも地図だけを表示します。

filters は、コレクション自体の 訪問者向けフィルター のうちどれを表示するかを | で区切って選びます。書いた順序に関係なくコレクションの順序で表示され、コレクションが提供しないフィルターは無視されます。filters がない場合は、コレクションのすべてのフィルターを表示します。

フィルター	表示	一致するもの
search	テキスト欄	名前、住所、カテゴリにそのテキストを含むスポット。
category	カテゴリのボタン（多い順に最大 30 件）	選択したいずれかのカテゴリのスポット。
price	最小値と最大値	価格がその範囲内のスポット。範囲を絞ると、価格のないスポットは非表示になります。
beds、baths	指定なし、1+、2+、3+、4+	少なくともその数があるスポット。
open_now	スイッチ	そのスポット自身のタイムゾーンで、今営業しているスポット。オンの間、営業時間のないスポットは非表示になります。

訪問者が設定したフィルターはすべて同時に適用されます。

card はスポットのカードに表示する量を設定します。既定値の auto は Studio で設計したカードです。compact は小さなフレーム向けに、タイトル、サブタイトル、アクションだけを表示します。

スポットのアクションはコレクションの定義どおりに動作します。経路 は地図内にルートを描画し、Apple マップと Google マップを提示します。リンク は新しいタブで開き、電話 は電話リンクを開きます。Schedule a Tour などのリクエストアクションは、事業者のリクエストフォームを地図の上に開きます。

ガイドのレイアウト

layout="guide" は施設の地図を開き、その横に Ask Kaleidr パネルを表示します。ホテルの周辺ガイドや、施設の周辺地図に使います。施設 コレクション（collection、なければ地図が描画する最初の施設コレクション）を一覧にし、Control Tower がオンである必要があります。施設コレクションを描画しない地図では、地図だけを表示します。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
             style="display:block; height:640px"></kaleidr-map>

• チャットが主役です。 幅 769 ピクセル以上のフレームでは、パネルは幅 400 ピクセルで地図の左に表示されます。それより狭い場合は地図の上に高さ 45% のシートとして表示され、訪問者は 85% まで引き上げられます。回答が AI によって生成されることを示す注記は入力欄の下に残ります。
• 入力欄の上の カテゴリチップ は、コレクションで最も多い 8 つのカテゴリです。チップはそのカテゴリのピンを表示し、訪問者の言語で「アンカー の近くの カテゴリ を見せて」と質問します。Plan My Day は「アンカー を起点に一日の計画を立てて」と質問します。
• アンカー は地図の 起点ピン で、Studio の地図設定で指定します。地図が描画するコレクションのスポット、またはホテルなど地図上に置いた地点です。名前付きの専用ピンとして描画され、ガイドでの「近く」はその近くを意味します。アンカーのない地図では地図の中心を使います。
• 一日のプラン。 一日の計画を頼まれると、ガイドはアンカーから出発し、まず自社のコレクションのスポット、次に Kaleidr 独自のスポットデータを巡るルートを描画し、名前付きの立ち寄り先と時刻を並べたカードとして訪問者の言語で表示します。
• 施設のカード には Studio でデザインしたカードが表示され、マークしたスポットには Staff Pick が付き、その下に連携のカードが表示されます。コネクションの内容はカードにのみ表示され、ガイドの回答には使われません。
• リクエスト。 施設の Reserve アクションは事業者のリクエストフォームを開きます。

チャットストリームでのガイド

viewer は表示中のレイアウトを地図の Kaleidr AI に伝えます。POST /chat/control/stream のクライアントには、ガイドに関する 2 つのフィールドが見えます。

フィールド	場所	形
layout	リクエスト本文	ガイドのレイアウトを表示している間は "guide"。それ以外は省略され、通常の地図のターンになります。最大 16 文字で、超えるとリクエストは 422 invalid_layout で拒否されます。
itinerary	ストリームのイベント。end イベントにも同じものが入ります	{ title, stops: [{ name, time?, note? }] }：一日のプランのタイトルと、名前付きの立ち寄り先 1〜12 件。訪問者の言語で書かれています。note は自社のスポットにのみ付きます。

一日のプランを表示しないクライアントは、このイベントを無視してかまいません。

ライブのレイアウト

layout="live" は、車両が今どこにいて、今日どこに停車するかを表示します。キッチンカーのルート、シャトル、移動サービスなどに使います。2 つのコレクションを読み込みます。位置がライブトラッキングから届く 車両 コレクションと、スケジュールを持つ 停留所 コレクションです。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
             collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
             style="display:block; height:640px"></kaleidr-map>

オプション	既定値	読み込むもの
collection	地図が描画する最初の車両コレクション	ライブで表示する車両。
stops	地図が描画する最初の停留所コレクション	停留所とその運行時間帯。

どちらも描画しない地図では、地図だけを表示します。パネルは幅 769 ピクセル以上のフレームでは地図の横に、それより狭い場合は地図の上のシートとして表示されます。

• パネルの先頭に ライブ の表示が出ます。シフト中の車両がないときは 現在運行していません と表示されます。
• 表示中の車両ごとに 1 行：車両名、移動中、停車中、停車地 と停留所名、または最後の報告がフリートの 古いと表示するまで を過ぎたときは 5 分前に確認。さらに 次の停留所 と 約 12 分、推定 のタグ。
• 本日のルート：今日の停留所を時間帯の順に並べ、それぞれの時間帯、担当車両、バッジを表示します。
• 自分の場所までどのくらい？ は訪問者の位置情報を求め、拒否された場合は市区町村のおおよその位置を使い、表示中の車両が到着するまでの時間を示します。位置情報はこの推定にのみ使われ、保存されることはありません。
• 車両を選ぶ と、訪問者が地図を動かすまでその車両を追いかけます。停留所を選ぶ と、今日の時間帯または次の運行日を載せたカードが開きます。

バッジ	表示される条件
現在ここにいます	車両がその停留所でチェックインしました。
本日休業	ドライバーが車両を今日は休業にしました。
営業中	停留所の時間帯に今の時刻が含まれます。
次回：11:00–14:00	停留所に今日これより後の時間帯があります。
本日はありません	停留所に今日の時間帯がありません。カードには 14 日以内の次の運行日が表示されます。

訪問者に見える動きはなめらかで、推測はしません。 車両は報告された位置から次の位置へとすべるように移動し、最後の報告より先に進むことはありません。位置は 10 秒ごとに更新されます（地図の作成者が 5〜60 秒の別の間隔を選んだ場合はその間隔）。ページが非表示の間は更新を止めます。今日の状況と推定時間は 1 分ごとに更新されます。更新に失敗した場合は直前の表示を保ちます。

表示されるのはシフト中の車両だけで、 精度はフリートの公開精度の範囲内です。シフトが終わった車両は次の更新で消えます。

表示される時間はすべて推定です。 道路距離と標準的な速度から算出し、交通状況は含みません。分単位に切り上げて 約 12 分 や 約 1 時間 20 分 のように表示し、到着時刻としては表示しません。2 地点の間に道路ルートがない場合、行には 推定なし と表示されます。道路ルートは OpenStreetMap のデータから作成されており、© OpenStreetMap contributors、ODbL に基づきます。

Request Pickup は停留所コレクションのリクエストアクションです。作成者が 訪問者に乗車地と目的地を選ばせる をオンにしている場合、訪問者はまず乗車地（変更しなければ停留所そのもの）と目的地を、住所検索または地図のタップで指定し、それからリクエストフォームに記入します。両方の地点がリクエストと一緒に送られます。

パネルのラベルは viewer の言語に従い、チャットバーと同じ 10 言語に対応します。

オプション

マウントオプション	属性	型	既定値	必須	説明
product	product	'viewer'	なし	はい	Viewer を選択します。
shareId	share-id	文字列	なし	はい	Studio の埋め込みコードに記載された公開済み地図 ID。^[A-Za-z0-9._~-]{1,100}$ と一致する必要があります。
mapId	map-id	文字列	なし	いいえ	shareId の別名。shareId がない場合に使われます。
center	center	[longitude, latitude]。属性値は "longitude,latitude"	保存されたビュー	いいえ	初期中心点。
zoom	zoom	数値	保存されたビュー	いいえ	初期ズーム。マウント時に center がなければ無視されます。
pitch	pitch	数値、度	保存されたビュー	いいえ	初期傾斜。
bearing	bearing	数値、度	保存されたビュー	いいえ	初期回転。
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	いいえ	iframe を読み込むオリジン。オリジンのみを使用します。本番環境では不要です。
base	base	URL	https://cdn.kaleidr.com	いいえ	SDK が viewer.js を読み込むオリジン。オリジンのみ使用し、ベース URL の上書きで認めるものに限られます。
enabled	flag	真偽値	なし	いいえ	マウント単位の有効化ゲート。
prompt	prompt	文字列	なし	いいえ	地図を開いたときに地図の Kaleidr AI に投げかける質問。チャットバーでは入力欄にあらかじめ入るテキスト。最大 500 文字。
promptParam	prompt-param	文字列	なし	いいえ	ページ自身の URL のこのクエリパラメーターから prompt を読み取ります。チャットバーの結果ページでは q。訪問者が同じオリジンのページから来た場合にのみ読み取るため、他の場所からのリンクで地図に何かを質問させることはできません。
layout	layout	'map'、'bar'、'locator'、'listings'、'guide' または 'live'	'map'	いいえ	bar でチャットバーをマウントします。locator と listings はコレクションの一覧の横に地図を表示します。スポットのレイアウトを参照してください。guide は施設の地図の横にチャットを開きます。ガイドのレイアウトを参照してください。live は車両と今日の停留所を表示します。ライブのレイアウトを参照してください。
collection	collection	string	地図が描画する、レイアウトの種類の最初のコレクション	いいえ	店舗検索、物件一覧、ガイド：一覧に表示するコレクションの ID。ライブ：車両コレクションの ID。
stops	stops	string	地図が描画する最初の停留所コレクション	いいえ	ライブ：停留所コレクションの ID。
filters	filters	文字列の配列。属性では | で区切る	コレクションのすべてのフィルター	いいえ	店舗検索と物件一覧：コレクションが提供するもののうち、search、category、price、beds、baths、open_now のどれを表示するか。
card	card	'auto' または 'compact'	'auto'	いいえ	compact のカードはタイトル、サブタイトル、アクションだけを表示します。
prompts	prompts	文字列の配列。属性では | で区切る	なし	いいえ	チャットバー：質問例。押すとその質問を送るボタンとして表示されます。
title	chat-title	文字列	なし	いいえ	チャットバー：入力欄の上のラベル。
placeholder	placeholder	文字列	チャットバーの言語での "Ask about this map"	いいえ	チャットバー：入力欄のプレースホルダー。
accent	accent	CSS カラー	#2da84a	いいえ	チャットバー：送信ボタン、アイコン、フォーカスリングの色。
theme	theme	'light'、'dark'、'auto'	'light'	いいえ	チャットバー：配色。auto は訪問者のシステム設定に従います。
lang	lang	言語タグ	訪問者のブラウザー言語	いいえ	チャットバー：自身のラベルの言語。
resultsUrl	results-url	URL	なし	いいえ	チャットバー：地図をページの上に開く代わりに、訪問者を ?q=<question> 付きでこのページへ送ります。

publishableKey、styleId、map、mapTarget、contained は Viewer のマウントに影響しません。キーを渡すことはむしろ逆効果です。SDK が Viewer では使われないセッションと交換してしまい、交換に失敗すると地図も表示されません。

ID

shareId は Studio が生成する次の 2 種類の地図 ID を受け付けます。

• 公開済み地図の ID。 公開と埋め込みページのコード、および共有ダイアログの埋め込みタブに表示されます。どちらも同じ ID です。
• 共有リンクの ID。 共有ダイアログのリンクを共有タブにある URL の末尾の 16 文字です。

公開済み地図 ID では現在保存されている地図が表示されます。共有リンク ID ではリンク作成時のスナップショットが表示されます。Kaleidr AI はどちらの ID も受け付けます。共有リンクでは、地図が公開されている間、地図の現在の許可ドメインで、スナップショットの Kaleidr AI スイッチに従います。公開済み地図の Chatを参照してください。

空または不正な ID でも例外は発生しません。SDK は以下を記録し、

[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.

何も描画しません。Kaleidr.mount はハンドルを返しますが、どのメソッドも何もしません。

直接 iframe URL

https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>

クエリパラメーター	値	効果
camera	longitude,latitude または longitude,latitude,zoom	初期中心点と任意のズーム。
pitch	数値、度	初期傾斜。
bearing	数値、度	初期回転。
q	テキスト、最大 500 文字	地図を開いたときに地図の Kaleidr AI に投げかける質問。Viewer がページに埋め込まれている場合にのみ質問し、Control Tower のない地図では無視されます。
layout	locator、listings、guide または live	スポットのレイアウト、ガイド、またはライブのレイアウト。それ以外の値では地図を表示します。
collection	コレクション ID	レイアウトが一覧にするコレクション。live では車両コレクション。
stops	コレクション ID	live での停留所コレクション。
filters	| で区切ったフィルター名	レイアウトが表示するフィルター。
card	auto または compact	スポットのカードに表示する量。

SDK はカメラオプション、prompt、layout、collection、stops、filters、card から同じ URL を構築します。

カメラ

初期カメラは次の情報源から組み立てられます。後の情報源は指定したフィールドのみを置き換えます。

1. ベースマップの既定ビュー。
2. 作者が Studio に保存したビュー。作者はデスクトップ、タブレット、スマートフォンの幅ごとに別のビューを保存でき、地図は iframe の幅に合うものを使用します。あるいは地図の内容を枠内に収める設定もできます。
3. ページから指定するカメラ（オプションまたは属性の center、zoom、pitch、bearing、または直接 iframe URL の camera、pitch、bearing）。

ページが渡すカメラは、画面幅別のビューや内容の自動フレーミングを含め、作者のビューより優先されます。指定しないフィールドは作者の値を保持します。

画面幅別ビューや内容のフレーミングを使う地図は、訪問者が地図を動かすまでは iframe のサイズ変更に合わせて再調整します。ページからカメラを指定した場合もこの自動調整が終了します。読み込み時のカメラ指定または setCamera の呼び出し後は、サイズを変更しても再フレーミングされません。setCamera は渡したフィールドだけを変更し、それ以外は保持します。

center は経度が先です。[-0.1276, 51.5072] はロンドンを表します。

サイズ

• iframe はマウント先の幅の 100% で、枠線がなく角が丸められています。
• マウント時に先の要素に高さがある場合、その高さの 100% になります。ない場合は固定 500 ピクセルです。
• マウント時に先の子要素を置き換え、インラインの位置指定がなければ position:relative、さらに overflow:hidden を設定します。
• <kaleidr-map> は既定で display:block なので height が適用されます。高さを指定してください。Safari 16.4 より前の環境では要素がインラインのままのため、例には display:block も含めています。

ハンドル

Kaleidr.mount は同期的にハンドルを返します。全製品の動作はハンドル一覧を参照してください。

メンバー	Viewer での動作
handle.product	'viewer'
handle.setCamera(camera)	地図を動かします。
handle.setTheme(theme)	非対応。警告だけを出します。
handle.setStyle(style)	非対応。警告だけを出します。
handle.send(text)	訪問者が text を入力したかのように、地図の Kaleidr AI へ質問します。チャットバーでは、テキストなしの send() で入力欄の内容を質問します。回答中に送った質問はその回答を待ち、より新しい質問はまだ待機中の質問を置き換えます。
handle.setFilters(filters)	スポットのレイアウトの訪問者向けフィルターを設定します。map レイアウトでは何もしません。
handle.showVehiclesLayer(layer)	自分の車両レイヤーを描画または移動します。
handle.clearVehiclesLayer()	自分の車両レイヤーを消します。
handle.destroy()	iframe を削除し、メッセージの監視を終了します。

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 800,             // milliseconds
});

フィールド	型	説明
center	[number, number]	経度、緯度。
zoom	数値	ズームレベル。マウント時と異なり、ここでは zoom は center なしでも機能します。
pitch	数値	傾斜角（度）。
bearing	数値	回転角（度）。
duration	数値	アニメーション時間（ミリ秒）。省略または 0 で即座に移動します。

すべてのフィールドは任意です。省略したフィールドは現在の値を保ちます。

setCamera は Kaleidr.mount が戻った後ならいつでも、次の行でも呼び出せます。iframe 内の地図がまだ準備できていない場合、呼び出しは保持され、準備完了の通知後に順番に適用されます。最新 256 件が保持されます。一定時間（通常 iframe の読み込み後 10 秒）待っても準備の通知がなければ、保持した呼び出しは送信され、コンソール警告が表示されます。kaleidr-embed:ready を事前に待つ必要はありません。初期ビューにはマウントオプションを使う方が直接的で、後から移動させずにそのビューで開けます。

カメラの現在値を読み取るメソッドはありません。

setFilters(filters)

handle.setFilters({
  q: 'downtown',
  category: ['Outlet', 'Flagship'],
  price: [250000, null],     // [min, max]; null leaves that end open
  beds: 2,
  baths: 1,
  open_now: true,
});

フィールド	型	設定するもの
q	文字列	検索欄。
category	文字列の配列	選択するカテゴリ。
price	[number | null, number | null]	最低価格と最高価格。
beds	数値	寝室の最小数。
baths	数値	浴室の最小数。
open_now	真偽値	営業中スイッチ。

すべてのフィールドは省略可能です。訪問者には、自分で設定したかのようにフィルターが変わって見え、もう一度変更することもできます。レイアウトが表示しないフィルターのフィールドや、それ以外のフィールドは無視されます。setCamera と同様に、地図の準備ができる前の呼び出しは保持され、準備ができた時点で適用されます。スポットのレイアウトより古い viewer バンドルには setFilters がありません。その場合、呼び出しは何もせず、マウントがそれを公開していないというコンソール警告を記録します。

showVehiclesLayer(layer)

自社の配車システムの位置など、ページがすでに把握している車両を埋め込み地図に描画します。データはページから iframe に渡るだけで、ほかには送られません。Kaleidr のサーバーを経由することはなく、viewer がこのレイヤーのために何かを取得することもありません。

handle.showVehiclesLayer({
  layer_id: 'shuttles',
  vehicles: [
    { id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
    { id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
  ],
});

// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });

handle.clearVehiclesLayer();

フィールド	型	説明
layer_id	string	レイヤーの名前。同じ ID で再度呼ぶとその場で更新されます。
vehicles	array、最大 2,000	描画する車両。
vehicles[].id	string	必須。呼び出しをまたいで車両を識別します。
vehicles[].lat, vehicles[].lng	number	必須。車両の位置。
vehicles[].name	string	車両の横に描画するラベル。
vehicles[].color	CSS の 16 進カラー	車両の色。指定がなければグレーで描画します。
vehicles[].bearing	number、度	車両が向いている方向。
attribution	string	データのクレジット。車両をタップすると、そのカードに表示されます。

• 同じ layer_id ならその場で更新されます。 各車両は描画中の位置から新しい地点まで、前回の呼び出しからの経過時間（最大 30 秒）をかけてすべるように移動します。新しい呼び出しに含まれない車両は消えます。
• 新しい layer_id、または指定なしの場合はレイヤーを置き換えます。 地図に表示される車両レイヤーは一度に 1 つです。
• id がない車両、または lat と lng が有限の数値でない車両は破棄されます。 2,000 台目を超える車両も同様です。
• 車両を動かすには、もう一度呼び出してください。 viewer がこのレイヤーのデータを自分で取りに行くことはありません。
• setCamera と同様に、地図の準備ができる前の呼び出しは保持され、 準備ができた時点で適用されます。

SDK の LiveLayerData 型と LiveVehicle 型がレイヤーの形を宣言しています。showVehiclesLayer と clearVehiclesLayer は viewer のメソッドで、chat、editor、tile では警告を記録して何もしません。このレイヤーより古い viewer バンドルにはどちらもありません。その場合、呼び出しは何もせず、マウントがそれを公開していないというコンソール警告を記録します。

マウント後の要素属性

マウント済みの <kaleidr-map product="viewer"> で center、zoom、pitch、bearing を変更すると、アニメーションなしで地図が動きます。share-id など他の属性を変更しても効果はありません。別の地図を表示するには要素を削除して新しいものを挿入します。

iframe からのメッセージ

iframe は埋め込み元ページにメッセージを送信します。そのうち 2 種類が公開された「読み込み完了」と「失敗」の通知です。

// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }

// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== iframe.contentWindow) return; // which embed sent it
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

SDK を使う場合、iframe はマウント先の最初の <iframe>、つまり target.querySelector('iframe') です。

エラーコード

code	終了を伴う	意味
no_id	はい	iframe の URL に地図 ID がありません。id は null です。
not_found	はい	該当する公開済み地図も共有リンクもありません。地図が一度も公開されていないか公開を取り消された、共有リンクの地図が削除されたか Kaleidr がリンクを削除した、または ID の入力ミスです。
domain_not_allowed	はい	地図がドメインを制限しており、埋め込みページが許可されていないか、リファラーを送信していません。
map_loads_exhausted	はい	所有組織が当期の地図読み込み枠を使い切りました。
fetch_failed	はい	地図を取得できませんでした。
maplibre_error	いいえ	地図は起動しましたが一部の描画に失敗しました。ready の前後に複数回届くことがあります。

終了を伴うコードの後、iframe は地図の代わりに短いメッセージを表示し、ready を送信しません。

規則

• ready は地図が描画され、表示が計上された後、読み込みごとに 1 回だけ送信されます。
• SDK は iframe を loading="lazy" で作成するため、画面の近くまで来るまでメッセージは届きません。
• iframe は type が kaleidr-embed: で始まる別のメッセージも送信します。SDK が Chat と地図を接続するために使いますが、公開契約ではなく変更され得るため依存しないでください。
• iframe は setCamera によるカメラ移動などの制御メッセージを、直接 iframe を埋め込んだページからの場合だけ受け付けます。別のウィンドウやフレームから送信されたメッセージは無視されるため、iframe を保持するページから setCamera を呼び出してください。
• SDK と要素は DOM イベントを発火せず、ready Promise も提供しません。

訪問者に表示されるメッセージ

次のメッセージが地図の代わりに iframe 内に表示されます。

テキスト	コード
"Loading map…"	なし：地図の読み込み中
"Couldn't find a map id in the URL."	no_id
"This map isn't available — it may have been unpublished, paused, or the link is incorrect."	not_found
"This map isn't allowed to render on this site. Please contact the map owner."	domain_not_allowed
"This map has reached its map load limit. It will be available again when the owner's allowance resets."	map_loads_exhausted
"Could not load the map. Please try again in a moment."	fetch_failed
"Unexpected error loading the map."	なし：起動時の予期しないエラー

アップロードされたデータ

公開済み地図は、作者が Studio のデータパネルに追加したデータセットと画像オーバーレイを描画します。iframe 自体がそれらを読み込むので、オプション、属性、キーは関与せず、データが埋め込み元ページを経由することもありません。

動作	詳細
表示内容	公開済み地図に含まれる全データセットと画像オーバーレイ。作者が設定したスタイルのレイヤーとして表示されます。
誰が閲覧できるか	地図を開ける人なら誰でも閲覧できます。許可ドメインを設定してもデータは機密になりません。
ブラウザーに届くもの	各データセットの全行・全列。大きなデータセットほど読み込みに時間がかかります。
データセットの読み込みに失敗した場合	そのレイヤー以外は通常どおり描画されます。
Studio のデータパネルでデータセットを削除した場合	公開済み地図と、表示していたすべての共有リンクへの提供が停止します。すでに読み込んだブラウザーはデータを保持し、発行済みダウンロードリンクは最大 1 時間利用できる場合があります。
地図の公開を取り消した場合	公開 ID から地図とデータセットが提供されなくなり、iframe は not_found を表示します。再公開すると同じ ID が復元されます。
共有リンク	リンク作成時の地図デザインのスナップショットであり、公開を取り消しても地図を表示し続けますが、再公開するまで Kaleidr AI は使えません。Studio に削除や一時停止の操作はありません。地図を削除するか、所有者の依頼により Kaleidr がリンクを取り消すまで機能します。共有リンクを参照してください。

公開済み地図のアップロードデータに詳細があります。

許可ドメイン

地図所有者は Studio の 共有、埋め込み、特定のドメイン から表示できるサイトを制限できます。

• 一覧にあるドメインはそのサブドメインも含みます。
• 検査では、iframe の要求でブラウザーが送信したリファラーのホスト名と一覧を比較します。リファラーがなければ失敗します。
• 失敗すると「許可されていない」というメッセージを表示し、domain_not_allowed を送信します。
• この検査で拒否された表示は地図読み込みとして計上されません。

使用量の計測

• 表示 1 回は地図所有組織の地図読み込み 1 回として計上されます。
• 同じ訪問者が 24 時間以内に同じ地図を再表示しても再計上されません。
• Kaleidr 自社サイト上の表示は計上されません。
• 上限に達すると、リセットまで iframe に制限メッセージが表示されます。クォータとレート制限を参照してください。

コンソールメッセージ

メッセージ	意味
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	有効な product がなくマウントされません。
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$.	ID が空または不正な形式です。
[kaleidr:viewer] mount target not found: <selector>	Kaleidr.mount がセレクターに一致する要素を見つけられませんでした。
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js	ネットワーク障害、ブロッカー、script-src ポリシーなどで Viewer バンドルを読み込めませんでした。
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. …	Viewer で使えないハンドルメソッドが呼ばれました。

利用できない機能

• クリック、カメラ移動、選択のイベント（スポットのカードとアクションを含む）。
• カメラ状態、地図のレイヤー、データの読み取り。
• 埋め込み地図への独自マーカーやレイヤーの追加（車両レイヤーを除く）。
• 埋め込みからのベースマップやテーマの変更。

関連ページ

• 公開済み地図の埋め込み
• <kaleidr-map> 要素
• ローダー kaleidr.js
• 公開済み地図の Chat