公開済みの地図を埋め込む

このガイドを終えると、Kaleidr Studio で作成した地図を自分のページに公開し、表示可能なサイトを制限し、読み込みの成功・失敗を検知できます。Free を含むすべてのプランで利用できます。公開には Kaleidr アカウントが必要ですが、API キーは不要です。

始める前に

公開できる状態の Kaleidr Studio の地図。
編集可能な Web ページ。SDK 要素には <script> タグが必要です。通常の iframe なら HTML だけで構いません。
Content Security Policy を使用している場合、https://map-embed.kaleidr.com のフレーム表示と、SDK 要素用の https://cdn.kaleidr.com のスクリプト読み込みを許可してください。Content Security Policy を参照。
テスト用に HTTP でページを配信する方法（例：フォルダー内で npx serve .）。

ステップ 1：地図を公開する

Studio で地図を開き、Publish を選択します。Publish & embed ページが開きます。
Project status に Draft と表示されます。Go Live を選択します。

確認できること： ステータスが Live に、ボタンが Re-publish に変わり、隣に Unpublish が表示されます。Embed code セクションとライブプレビューも表示されます。

公開地図に表示されるのは、Go Live をクリックした瞬間のコピーではなく、Studio に現在保存されている内容です。Studio は作業中の変更を保存するため、公開後の編集や追加したデータセットも、次に埋め込み地図が読み込まれると公開されます。再度 Re-publish を押す必要はありません。Re-publish は新しい公開バージョンを記録する操作で、ID、リンク、埋め込みコードは変わりません。前後で訪問者に表示される地図は同じです。

編集中の状態を見せずに公開地図を変更するには、先に Unpublish を選んで作業後に再公開するか、別のコピーで編集してください。公開解除すると、再公開するまですべての埋め込みが停止します。

公開対象にはアップロード済みデータも含まれます。Data パネルのデータセットや画像オーバーレイは、設定したレイヤーのスタイルで訪問者にも表示されます。公開すべきでない情報が含まれる場合は、公開地図のアップロードデータを先に読んでください。

ステップ 2：埋め込みコードをコピーする

Embed code には 2 つの形式があります。

Studio の形式	取得できるもの	適した用途
iFrame	公開地図を参照する通常の `<iframe>`。	ページがスクリプトを実行できないサイトビルダー、CMS、Wiki、または単に地図を表示したい場合。
Developer	SDK ローダーと `<kaleidr-map product="viewer">` 要素。	ページを制御でき、コードからカメラを設定・移動したり、チャットを重ねたり、SPA でライフサイクルを管理したい場合。

形式を選び、Copy をクリックしてください。

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>

Developer 形式：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js" async></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
  style="display:block;width:100%;height:480px;"></kaleidr-map>

YOUR_MAP_ID は Studio がコードに挿入する地図 ID です。使用できるのは英数字と ., _, ~, - で、最大 100 文字です。どちらの形式にも同じ ID を使えます。

どちらの形式にも地図の Kaleidr AI が含まれます。Control Tower がオンなら Ask Kaleidr パネル、Popup Window がオンならポップアップ内の AI チャットです。公開地図で Kaleidr AI を使うを参照してください。

ステップ 3：ページに追加してサイズを設定する

地図を表示したい位置にコードを貼り付けます。

確認できること：「Loading map…」と表示された後、Studio に保存した表示範囲の地図が現れます。

サイズ設定のルール：

通常の iframe： 一般的な iframe と同様に width と height を指定します。
SDK 要素： 高さを指定します。<kaleidr-map> の既定は display:block なので高さが適用されます。サンプルの style="display:block; height:480px" はそのまま使えます。Safari 16.4 より前では要素がインライン扱いになり height が無視されるため、明示的な指定が役立ちます。スタイルシートでも設定できます。
```
kaleidr-map { display: block; height: 480px; }
```
地図は要素の横幅いっぱいに広がります。マウント時に高さがないと、500 ピクセルの固定高さになり、後からサイズを与えても変わりません。非表示タブや折りたたみパネルでは高さが得られないため、表示時にマウントするか明示的な高さを設定してください。
レスポンシブにするには height:60vh、aspect-ratio:16/9、flex/grid セルなど、高さが確定する CSS を使えます。

ステップ 4：初期カメラを設定する（任意）

地図は作成者が保存した表示範囲で開きます。作成者は PC・タブレット・スマートフォン別の表示設定や、コンテンツに合わせた自動フィットを保存できます。後者はフレーム幅に応じて表示範囲が決まり、サイズ変更時にも再調整されます。別の位置で開くにはカメラを指定します。center は経度、緯度の順です。

要素で指定する場合：

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

通常の iframe では URL に camera=longitude,latitude,zoom を追加します：

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID?camera=-0.1276,51.5072,12&pitch=45&bearing=-20"
  width="100%" height="480" style="border:0;" loading="lazy"
  referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"></iframe>

ページから渡したカメラは、作成者が保存した画面幅別の設定や自動フィットより優先されます。指定したフィールドだけ置き換わり、省略したものは作成者の値が維持されます。ページがカメラを指定すると、フレームのサイズ変更時の自動再フィットは停止します。重要：center を指定しないと zoom は無視されます。 pitch と bearing は単独でも使えます。

確認できること： 指定したカメラで地図が開き、マーカー、レイヤー、アップロードデータはそのまま残ります。

読み込み後にカメラを移動するには、JavaScript でマウントしてハンドルを保持します：

<div id="map" style="height:480px"></div>
<button id="paris">Paris</button>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#map', {
    product: 'viewer',
    shareId: 'YOUR_MAP_ID',
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
  });
</script>

setCamera についての注意点は 2 つあります：

setCamera は要素ではなく、Kaleidr.mount の戻り値であるハンドルのメソッドです。document.querySelector('kaleidr-map').setCamera は undefined です。要素としてマウントした地図を動かす場合は center、zoom、pitch、bearing 属性を変更します。移動にはアニメーションがありません。
Kaleidr.mount が返った後ならいつでも呼び出せます。iframe の準備前の呼び出しは保持され、準備完了時に適用されるため、ステップ 6 の kaleidr-embed:ready を待つ必要はありません。初期表示を選ぶ場合はマウントオプションを使います。
マウント後のカメラ設定も作成者の保存表示より優先され、自動再フィットを停止します。省略したフィールドは現在の値を維持します。

ステップ 5：地図を表示できるサイトを制限する（任意）

既定では、公開地図の ID を知っているサイトならどこでも表示できます。制限するには：

Studio で地図を開き、Share を選択します。未公開なら地図が公開され、開くたびに新しい共有リンクが作成されます。
Embed タブを開きます。
アクセス設定を Any domain から Specific domains に変更します。
ドメインを 1 行に 1 つ入力します。例：
```
example.com
blog.example.org
```
入力欄の外側をクリックすると、Studio がリストを保存し、Saved と表示します。

確認できること： リストにあるサイトでは表示されます。それ以外では「This map isn't allowed to render on this site. Please contact the map owner.」と表示されます。

ドメインの照合規則：

ホスト名だけを入力してください。先頭の https:// は無視されます。パスやポートは含めません。
親ドメインはサブドメインを含みます。example.com は example.com、www.example.com、shop.eu.example.com を許可します。
制限中にローカルテストする場合は localhost を追加します。

判定はリファラーに依存します

地図は iframe 読み込み時にブラウザーが送信するリファラーから許可ドメインを判定します。リファラーがなければドメイン制限付き地図は表示されません。次のケースに注意してください：

ページがレスポンスヘッダーまたは <meta name="referrer"> で Referrer-Policy: no-referrer や same-origin を指定している。
iframe が referrerpolicy="no-referrer" を指定している。
ページを file:// URL でローカルディスクから開いている。
iframe の URL をブラウザーのタブで直接開いている。

ブラウザーの既定ポリシー strict-origin-when-cross-origin はオリジンを送信するため正常に動作します。サイトがより厳しい場合、通常の iframe では referrerpolicy="no-referrer-when-downgrade" を維持するか、埋め込みページのポリシーを緩和してください。

地図を別の iframe 内に表示する場合、リファラーは外側のフレームのアドレスになります。そのドメインをリストに含めてください。

許可ドメインは表示場所を制限するだけで、公開地図やそのデータセットを秘密にする仕組みではありません。公開地図のアップロードデータを参照し、非公開にすべき情報を公開しないでください。

ステップ 6：読み込み成功・失敗を検知する（任意）

SDK に ready Promise はなく、要素もイベントを発火しません。iframe は次の 2 つの場合にページへメッセージを送信します：

メッセージ	タイミング	フィールド
`kaleidr-embed:ready`	地図が初めて描画されたとき。	`type`、`id`（地図 ID）、`source`（`"publish"` または `"share"`）
`kaleidr-embed:error`	地図の読み込みや一部の描画に失敗したとき。	`type`、`id`、`code`、`message`

window で受信し、メッセージの送信元オリジンと送信したフレームの両方を確認します：

const el = document.getElementById('locations'); // the <kaleidr-map> element

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = el.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    console.log('map loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    console.warn('map problem', msg.code, msg.message);
  }
});

通常の iframe では event.source とその iframe の contentWindow を比較します。

エラーメッセージの code は次のいずれかです：

`code`	意味	フレームでの表示
`no_id`	iframe の URL に地図 ID がありません。	“Couldn't find a map id in the URL.”
`not_found`	未公開、公開解除済み、または ID の誤りです。	“This map isn't available — it may have been unpublished, paused, or the link is incorrect.”
`domain_not_allowed`	許可ドメイン外かリファラーがありません。	“This map isn't allowed to render on this site. Please contact the map owner.”
`map_loads_exhausted`	地図所有者の組織の読み込み枠が尽きています。	“This map has reached its map load limit. It will be available again when the owner's allowance resets.”
`fetch_failed`	ネットワーク障害などで地図を取得できません。	“Could not load the map. Please try again in a moment.”
`maplibre_error`	地図は開始したものの一部の描画に失敗しました。詳細は `message` に含まれます。	一部が欠けた地図。

タイミングについて：

maplibre_error 以外のコードでは地図は表示されず、ready も届きません。
maplibre_error は ready の前後に複数回届くことがあり、地図全体が使えないとは限りません。警告として扱ってください。
SDK は iframe を遅延読み込みします。ページ下部の地図はスクロールで近づくまで読み込まれず、メッセージも届きません。数秒の無応答だけで失敗と判断しないでください。
iframe は SDK 内部向けの別の kaleidr-embed: メッセージも送信します。公開仕様として扱うのは上記 2 種だけです。

完全なページの例

index.html として保存し、YOUR_MAP_ID を置き換え、フォルダーを HTTP で配信してください。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our locations</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #map { height: 480px; }
  </style>
</head>
<body>
  <h1>Our locations</h1>
  <p id="status">Loading the map…</p>

  <div id="map"></div>
  <p>
    <button id="london">London</button>
    <button id="paris">Paris</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('map');
    const status = document.getElementById('status');

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

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (!msg || typeof msg.type !== 'string') return;

      if (msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      } else if (msg.type === 'kaleidr-embed:error' && msg.code !== 'maplibre_error') {
        status.textContent = 'The map could not load (' + msg.code + ').';
      }
    });

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 12, duration: 800 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
    });
  </script>
</body>
</html>

動作のしくみ

項目	動作
初期表示	作成者が保存した範囲。ページでカメラを指定した場合は、その各フィールドを優先。
スクロール	ポインターが地図上にあるとき、スクロールで地図をズーム（Studio と同じ）。ポインターが地図の外にあるときは、スクロールでページを移動。タッチ画面ではドラッグで地図を移動し、ピンチでズーム。
更新	Studio に現在保存されている地図を表示。保存した編集は次の読み込みで反映され、再公開は不要。
アップロードデータ	レイヤー化したデータセットと画像オーバーレイが表示されます。公開地図のアップロードデータを参照。
公開解除	利用不可メッセージが出ます。再公開すれば同じ URL が再び使えます。地図の公開解除を参照。
ポップアップ	作成者が有効にした場合に限り、クリックで場所のポップアップを表示。
高さ	マウント時の高さを使用。なければ固定 500 ピクセル。
読み込み	SDK の iframe は画面に近づいてから遅延読み込み。
キー	不要。viewer に公開キーを渡すと不要なセッション要求が発生し、拒否されると地図が表示されません。

公開地図上のアップロードデータ

Studio の Data パネルに追加したデータセットは公開地図の一部です。各データセットや画像オーバーレイは指定したレイヤーとして訪問者に表示されます。通常の iframe、SDK 要素、共有リンクのいずれでも同じです。追加の設定や、埋め込み側の API キーは不要です。

公開地図は現在保存された状態を表示するため、公開後に追加したデータセットも保存した時点で公開されます。再公開は必要ありません。

何が誰に配信されるか：

公開地図のデータのみ。 データセットは公開地図または共有リンクに含まれる場合に限って配信され、未公開地図だけにあるものは配信されません。
データセット単体では取得できません。 地図のデータセット一覧機能はなく、ID だけでは公開地図なしに開けません。
地図を開ける人はデータを読めます。 公開地図は公開情報です。許可ドメインは表示先の制限であって、秘密保持ではありません。
表示に使わない列もすべて送られます。 ブラウザーはすべての行と列を受信します。非公開列は公開前に元ファイルから削除し、再アップロードしてください。

データセットの配信を停止するには：

Studio での操作	公開地図への影響	共有リンクへの影響
Data パネルでデータセットを削除	データ配信が止まり、残りの地図はそのまま。	対象データのレイヤーがない地図を表示。
地図を公開解除	データセットを含む地図全体が配信されなくなる。	影響なし。共有リンクは保有していたデータを表示し続ける。

データセットを削除するには、データパネルで対象行のゴミ箱を選択し、確認します。データセットの削除または置換には、手順と、その後に「元に戻す」を実行した場合の挙動が記載されています。データセットを描画するレイヤーだけを削除しても、データセットの削除にはなりません。データセット自体は保存されたまま地図にも残るため、引き続き配信されます。

共有リンクは地図デザインのスナップショットです。 リンク作成時点の地図を表示します。その後に地図を編集したり公開を解除したりしても、リンクの表示内容は変わりません。スナップショットには作成時点の地図名、許可ドメイン一覧、Kaleidr AI のスイッチも含まれるため、後からそれらを変更しても、作成済みのリンクが表示される場所や提供される Kaleidr AI の機能は変わりません。ただし、共有リンクの Kaleidr AI には地図も必要です。地図が公開されている間だけ、かつ地図の現在の許可ドメインに含まれるページでのみ動作するため、地図の公開を解除するかドメインを削除すると止まります。費用は地図の所有者が負担します。公開地図で Kaleidr AI を使うを参照してください。

共有リンクは地図デザインのスナップショットです。 作成時の見た目を保持するため、その後に地図を編集・公開解除しても変わりません。ただしデータセットは例外です。共有リンクも同じ保存データを参照するので、データセットを削除すると、それを表示していたすべてのリンクから消えます。

Studio で Share ダイアログを開くたびに地図は公開され、新しい共有リンクが作られます。何度も共有すると、作成時点の見た目を持つ複数のリンクができます。

Studio には共有リンクを削除または一時停止する操作はありません。表示データを削除するか、Kaleidr にリンク削除を依頼するまで有効です。新しい状態を配る場合は再び Share を開いて新しいリンクを使ってください。古いリンクは以前の見た目のままです。

地図の公開を解除する

Publish & embed で公開地図には Re-publish の隣に Unpublish があります。Studio は埋め込みが停止し、配布済み共有リンクは動作し続けることを確認します。続行する場合は Unpublish、維持する場合は Cancel を選択してください。

埋め込みはすべて停止し、「利用できない」というメッセージと not_found が出ます。
地図 ID は維持されます。Go Live で再公開すると同じ URL が復活し、既存のコードを変える必要はありません。
既存の共有リンクは以前のデータで引き続き機能します。ただし、その Kaleidr AI は地図を再公開するまで止まります。

停止がすべての場所へ反映されるのは即時ではありません：

既に読み込まれたデータはブラウザーに残ります。 地図を開いている人はレイヤーを引き続き見られ、数分間はブラウザーが以前のデータを再利用する場合があります。
発行済みダウンロードリンクは最長 1 時間有効な場合があります。 大きなデータセットでは一時的なダウンロード URL が渡され、削除や公開解除の前に発行されたものは期限切れまで（最長 1 時間）読めます。

読み込みの方式：

訪問者ごとにデータセット全体をダウンロードします。 地図の移動に応じた分割読み込みではありません。行・列が多いほど、特に低速回線では表示が遅くなります。必要な行と列だけ公開してください。
データセットが読み込めなくても地図全体は停止しません。 そのレイヤーなしで残りを描画します。

アップロード可能な範囲はデータセットの制限を参照してください。

閲覧数のカウント方法

訪問者が埋め込み地図を読み込むと、埋め込み先サイトではなく地図の所有組織に 1 回の地図読み込みとして計上されます。同じ訪問者が同じ地図を 24 時間以内に再読込しても再計上されません。Studio のプレビューなど、Kaleidr 自身のページでの閲覧も計上されません。

期間中の地図読み込み枠を使い切ると、リセットまで埋め込みに制限メッセージが表示され、map_loads_exhausted が送信されます。プランの枠はクォータとレート制限を参照してください。

動作確認

ページ上： Studio の Data パネルで設定したマーカー、ルート、データセット、画像がレイヤーとして表示され、ズームボタンが動き、下部にクレジットが表示されます。
コンソール： [kaleidr を含むエラーがありません。
Network タブ： https://map-embed.kaleidr.com/embed/YOUR_MAP_ID に 200 のリクエスト。SDK では https://cdn.kaleidr.com の kaleidr.js と viewer.js も表示されます。
リスナー： kaleidr-embed:ready を 1 回受信します。

動作しない場合

症状	原因	対処
`height` を変えても 500 ピクセル	マウント時に高さなし、`display:inline`、または Safari 16.4 未満で `display:block` なし。	`display:block` と高さを設定し、表示中にマウント。
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` 属性がないか誤記。	`product="viewer"` を指定。
地図 ID が無効と表示	`share-id` が空か無効。	Studio から ID をコピーし直す。 `[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.`
`[kaleidr:viewer] mount target not found: #map`	ターゲット要素作成前の実行、またはセレクター誤り。	要素の後で実行し、セレクターを確認。 `Kaleidr.mount`
`Kaleidr is not defined`	`async` の `kaleidr.js` より先にコードが実行された。	`async` を外すか `load` イベントを使う。
地図が利用不可と表示	未公開・公開解除・ID 誤り。	Go Live で公開して ID を確認。
ドメインが許可されない	ドメインがリスト外、またはリファラーなし。	許可リストとポリシーを確認。
地図読み込み枠に到達	組織の枠を消費。	リセットを待つか枠を増やす。クォータとレート制限を参照。
“Could not load the map”	通信などで取得できない。	再読込し、ネットワークと iframe URL を確認。
CSP `frame-src` 違反	iframe のブロック。	`https://map-embed.kaleidr.com` を許可。 `frame-src`
CSP `script-src` 違反	SDK ローダーのブロック。	`https://cdn.kaleidr.com` を許可するか通常の iframe を使用。 `script-src`
`setCamera` が動かない	要素で呼んだか、地図が未ロード。	`Kaleidr.mount` のハンドルで呼び、`kaleidr-embed:error` とコンソールを確認。地図が所定の待機時間内（通常は iframe 読み込み後 10 秒）に準備完了を報告しない場合も、呼び出しは送信され、コンソールに `[kaleidr] the map frame has not reported ready` と表示されます。エラー表示中のフレームには移動・変更する地図がありません。
`el.setCamera is not a function`	要素で `setCamera` を呼んだ。	ハンドルを使うかカメラ属性を変更。 Kaleidr.mount
ページのスクロールが地図で止まる	仕様どおり。ポインターが地図上にあると、スクロールで地図がズームする。	ポインターを地図の横に置いてスクロール。地図の高さを画面より小さくし、訪問者が地図を越えてスクロールできるようにする。
編集内容が反映されない	保存前に埋め込みを読み込んだ。	再読込。再公開は不要。
意図しない編集が公開された	公開地図は現在保存済みの状態を表示する。	取り消す。非公開で編集するなら公開解除またはコピーを作る。参照
データレイヤーがない	データセット削除か読み込み失敗。	Studio の Data パネルで確認し、再読込。
大きなデータの表示が遅い	各訪問者が全行列を取得する。	行・列を減らす。公開地図のアップロードデータを参照。

制限事項

埋め込みは読み取り専用で、ページからマーカーやレイヤーを追加したり、データやクリックイベントを取得したりできません。
ページへの通知は kaleidr-embed:ready と kaleidr-embed:error のみです。
埋め込み上で地図のスタイルやベースマップを変更できません。Studio で編集すると次の読み込み時に反映されます。
マウント後に share-id を変更しても無効です。要素を再作成するか handle.destroy() 後に再マウントしてください。
ドメイン制限はブラウザーのリファラーに依存し、機密情報の保護にはなりません。

次のステップ

Viewer リファレンス：オプション、属性、メッセージ。
公開地図で Kaleidr AI を使う：訪問者から質問できるようにする。
地図のデータセット：ファイル、制限、列の役割。
フレームワーク統合：React、Next.js、Vue でのマウントと破棄。
Content Security Policy：サイトにポリシーがある場合。

始める前に​

ステップ 1：地図を公開する​

ステップ 2：埋め込みコードをコピーする​

ステップ 3：ページに追加してサイズを設定する​

ステップ 4：初期カメラを設定する（任意）​

ステップ 5：地図を表示できるサイトを制限する（任意）​

ステップ 6：読み込み成功・失敗を検知する（任意）​

完全なページの例​

動作のしくみ​

公開地図上のアップロードデータ​

共有リンク​

地図の公開を解除する​

閲覧数のカウント方法​

動作確認​

動作しない場合​

制限事項​

次のステップ​