Tile リファレンス

product="tile" はスタイル ID で選択した Kaleidr のベースマップを表示します。SDK は公開用キーを Tile セッションに交換し、マウント先の内容を https://map-embed.kaleidr.com/?style=<style> を読み込む iframe に置き換えます。地図はこの iframe 内で描画されます。

Kaleidr はセッションを使用してキー、そのスコープ、ページのオリジンを確認し、地図読み込みを計上して、組織の既定ベースマップを提供します。セッションは iframe に渡されません。iframe の URL に含まれるのはスタイル ID と指定したカメラ（camera、pitch、bearing）だけで、公開用キーやセッショントークンは含まれず、iframe 内の地図もそれらでリクエストを送りません。

キー	公開用キー（kld_pk_live_…）。必須。
スコープ	maps。新しいキーには既定で含まれます。
プラン	Free を含むすべてのプラン。
表示場所	https://map-embed.kaleidr.com から読み込む iframe。
計測	Tile セッションごとに地図読み込みを 1 回計上。
CSP	script-src https://cdn.kaleidr.com、connect-src https://api.kaleidr.com、frame-src https://map-embed.kaleidr.com。

手順については、Kaleidr ベースマップの使用を参照してください。

マウント

要素を使用する場合：

<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="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

JavaScript から：

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

オプション

マウントオプション	属性	型	既定値	必須	説明
product	product	'tile'	なし	はい	Tile を選択します。
publishableKey	publishable-key	文字列	なし	はい	kld_pk_… キー。スコープ maps が必要です。サーバーキー（kld_sk_…）は、リクエストを送る前にブラウザーで拒否されます。
styleId	style-id	文字列	設定されていれば組織の既定ベースマップ	推奨	下表のスタイル ID またはスタイルドキュメントの完全な https:// URL。^[A-Za-z0-9._:/~-]{1,200}$ に一致する必要があります。
center	center	[longitude, latitude]。属性では "longitude,latitude"	スタイルの既定ビュー	いいえ	初期中心点。
zoom	zoom	数値	スタイルの既定ビュー	いいえ	初期ズーム。マウント時に center がない場合は無視されます。
pitch	pitch	数値、度	スタイルの既定ビュー	いいえ	初期傾斜。
bearing	bearing	数値、度	スタイルの既定ビュー	いいえ	初期回転。
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	いいえ	セッション交換の送信先。/inference-api パスが必要です。通常、本番環境での指定は不要です。
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	いいえ	iframe の読み込み元。使用されるのはオリジンのみです。地図データではなく地図ページのホストです。
base	base	URL	https://cdn.kaleidr.com	いいえ	SDK が tile.js を読み込むオリジン。ベース URL の上書きで認められたオリジンのみ使用できます。
enabled	flag	真偽値	なし	いいえ	マウント単位の有効化ゲート。

shareId、theme、map、mapTarget、contained、tileBase は Tile のマウントには影響しません。

スタイル ID

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

規則：

• ID は完全一致で大文字と小文字を区別します。短縮エイリアスはありません。
• styleId を省略すると、セッションで返された組織の既定ベースマップを使用します。未設定なら iframe に「Couldn't find a map id in the URL.」と表示されます。アカウント設定に依存しないよう styleId を指定してください。
• 明示した styleId は組織の既定値より常に優先されます。
• 存在しない ID は空の iframe と、kaleidr-embed:error メッセージを生じさせ、コードは maplibre_error ですを生じさせます。
• 許可されない文字が含まれるとマウントされず、コンソールに [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$. が表示されます。このためスタイル URL にクエリ文字列は付けられません。

カメラ

初期カメラはスタイルの既定ビューに基づき、指定した各フィールドで対応する値を上書きします。既定ビューがないスタイルでは世界全体が表示されます。中心 [0, 20]、ズーム 2、傾斜と回転はありません。

• center は経度が先です。[-0.1276, 51.5072] はロンドンを示します。
• マウント時の zoom は center を同時に指定した場合のみ使用されます。
• pitch と bearing は center と独立しています。

サイズ

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

ハンドル

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

メンバー	Tile での動作
handle.product	'tile'
handle.setCamera(camera)	地図を移動します。
handle.setStyle(style)	再マウントせずにベースマップを切り替えます。
handle.setTheme(theme)	非対応。警告を記録し、何もしません。
handle.destroy()	iframe を削除し、セッション更新を停止します。

setStyle(style)

handle.setStyle('kaleidr-night');

スタイル ID または完全なスタイル URL を受け取り、マウント時の styleId と同じ方法で解決します。iframe は再読み込みされず、カメラ位置も変わらず、地図読み込み回数は加算されません。setStyle に対応するのは Tile だけです。

setCamera(camera)

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

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

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

呼び出すタイミング

setCamera と setStyle は Kaleidr.mount が戻った後ならいつでも、次の行でも呼び出せます。iframe 内の地図が準備できる前の呼び出しは保持され、準備が通知されると順番に適用されます。最新 256 件が保持されます。一定時間（通常は iframe 読み込みから 10 秒）待っても準備の通知がなければ、保持した呼び出しは送信され、コンソール警告が一度表示されます。事前に kaleidr-embed:ready を待つ必要はありません。初期ビューやスタイルはマウントオプションで指定すれば、途中で変更することなくその状態で開けます。

マウント後の要素属性

マウント済みの <kaleidr-map product="tile"> で center、zoom、pitch、bearing を変更すると、アニメーションなしで地図が移動します。style-id、publishable-key など他の属性を変更しても何も起きません。

iframe からのメッセージ

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id は渡したスタイル ID または URL です。no_id の場合は null となり、iframe に「Couldn't find a map id in the URL.」が表示され、ready は送信されません。

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

• ready は地図の描画時に一度だけ送信され、setStyle の後には再送信されません。
• maplibre_error は ready の前後に複数回届くことがあります。
• iframe は loading="lazy" で作成されるため、表示領域に近づくまでメッセージは届きません。
• セッションが拒否された場合、iframe が作成されないためメッセージもありません。コンソールを確認してください。
• iframe は type が kaleidr-embed: で始まる追加メッセージも送ります。SDK が Chat と地図の接続に使いますが、公開契約には含まれません。

セッションと使用量計測

Tile のマウントごとに SDK は次を送信し、

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

次を受け取ります。

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id は組織の既定ベースマップを示します。未設定なら null です。

"product":"tile" による交換が成功するたびに、組織に対して地図読み込み 1 回が計上されます。交換のタイミングは次のとおりです。

タイミング	回数
マウント時	1
マウントが続く間、セッション失効の 90 秒前	毎回 1
タブが再び表示され、失効まで 90 秒以内、またはすでに失効している場合	1
destroy() 後の再マウント、または削除した要素を再挿入した場合	1

注意：

• 更新失敗時は 30 秒ごとに再試行されます。表示中の地図は削除されません。
• 最初の交換が失敗するとマウントも失敗し、自動再試行されません。再マウントしてください。
• destroy() は更新を停止します。
• カメラ操作、スタイル変更、訪問者の操作は計上されません。

Tile のセッション交換は、次のうち最初に該当した理由で拒否されます。

状態	detail	理由
403	publishable_key_required	キーが公開用キーではありません。
403	origin_required	リクエストにオリジンがありません。
403	origin_not_allowed	ページのオリジンがキーの許可リストにありません。
403	product_not_allowed	キーは別の製品に制限されています。
403	tier_capability_not_allowed	プランが製品を許可していません。
403	insufficient_scope	キーに maps スコープがありません。
429	map_load_quota_exceeded	組織の地図読み込み枠を使い切りました。

これらの判定の前に、プラットフォーム側でセッション交換が無効の場合は 404 sessions_disabled、障害が発生した場合は 503 sessions_not_configured が返されることがあります。いずれもキーの問題ではありません。全コードはエラー一覧を参照してください。

Chat との連携

Chat のマウントから Tile 要素を操作できます。Tile 要素に id を指定し、Chat の map-target 属性（マウントオプション mapTarget）をその要素に向けます。

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

Tile 地図では、アシスタントがポップアップ付きのピンを置き、場所に合わせてカメラを調整し、経路、都市などの領域の輪郭、リアルタイムの車両位置を描きます。手順はKaleidr ベースマップの使用、レイアウトはテーマと配置、オプションはChat リファレンスにあります。

コンソールメッセージ

メッセージ	意味
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	有効な product がなく、要素はマウントされません。
[kaleidr:tile] kaleidr session exchange failed (<status>)	セッション交換が拒否されました。ネットワークタブの応答を確認してください。403 の場合は detail を確認し、map_load_quota_exceeded もここにあります。429 の場合は error を確認し、例として rate_limited を確認します。
…/sdk/sessions の CORS エラーの後に [kaleidr:tile] の取得エラー	未知または失効したキー、もしくは許可されないオリジンが原因です。許可されないオリジンへの応答には CORS ヘッダーがなく、ブラウザーは SDK に応答を見せません。
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	サーバーキーが渡されました。リクエストは送信されません。
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId に許可されない文字があります。
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount がセレクターに一致する要素を見つけられませんでした。
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	Tile バンドルを読み込めませんでした。
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	Tile 非対応のハンドルメソッドが呼び出されました。
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	キャッシュされた古い tile.js が使用されています。キャッシュを無効にして再読み込みしてください。

利用できない機能

• 独自のマーカー、レイヤー、ポップアップの追加。
• クリック、カメラ移動、選択のイベント。
• カメラの状態の読み取り。
• iframe を使わずに地図を表示すること。

関連ページ

• Kaleidr ベースマップの使用
• <kaleidr-map> 要素
• ローダー kaleidr.js
• クォータとレート制限