Webサイトにインタラクティブマップを埋め込む方法

Webサイトには、直接配置するiframe、再利用可能なWebコンポーネント、またはライブマップに接続するJavaScript SDKを使ってインタラクティブな地図体験を埋め込めます。独立した公開地図にはiframe、管理された実装を簡潔なHTMLで利用する場合はWebコンポーネント、ホスト側でカメラ、ライフサイクル、製品操作を制御する場合はSDKが適しています。本番環境では、サイズ指定、ドメイン制御、アクセシビリティ、検索可能なテキスト、操作分析も必要です。

以下では、方式の選択、Kaleidr Viewerの設定、レスポンシブコンテナ、セキュリティ、アクセシビリティ、SEO、よくある誤りを解説します。ライブレンダラーに会話機能を接続する方法は、地図にAIチャットを追加する方法を参照してください。SDKという製品分類については、AIマップSDKとは何かを参照してください。

埋め込みの基本

方式を先に決める： iframe、Webコンポーネント、SDK、ネイティブ地図ライブラリは、コード例の長さではなく、ホストページに必要な制御範囲で選びます。

高さを確保する： 読み込み前に地図コンテナの高さを明示し、領域のつぶれやレイアウトシフトを防ぎます。

公開Viewer： Kaleidr Viewerはproduct="viewer"と共有IDを使用し、共有リンクと公開者が許可したドメインによってアクセスを制御します。

キャンバス外にもテキストを置く： 見出し、要約、場所一覧を用意し、キーボード利用者、支援技術、検索エンジンにも有用なページにします。

タスクを計測する： 地図の表示回数だけでなく、読み込み、選択、経路案内、コンバージョンを追跡します。

iframe、Webコンポーネント、JavaScript SDKの3つの連携経路が、ドメイン制御、アクセシビリティ、分析機能を備えた1つのレスポンシブインタラクティブマップ体験へと融合します。

インタラクティブな地図体験を埋め込むには？

このガイドでは、マーケティングサイト、観光ガイド、不動産ページ、店舗検索、記事、ソフトウェア製品に対応するレスポンシブな地図セクションを作成します。完成形には、公開済みのインタラクティブマップ、デスクトップとモバイルに対応するコンテナ、地図外の明確なタイトルと要約、ホストページからの任意のカメラ制御、ドメインまたは認証情報の制限、読み込み・失敗状態、地図だけに依存しないアクセシブルな代替情報、利用状況を測るイベントが含まれます。例では、1つのローダーと1つのカスタム要素で公開地図を埋め込めるKaleidr Viewerを使用します。同じ判断基準は、プロバイダーのiframe、地図Webコンポーネント、Mapbox、Google Maps、MapLibre、Leafletによる独自実装にも適用できます。

適切な埋め込み方式を選ぶには？

最初の決定は、ホストサイトがどの程度の管理を必要としているかである。コンテンツページ上の公開地図は、通常、SaaSワークフロー内のマップと同じアーキテクチャを必要としないため、デフォルトで最も複雑な方法を選択することは避けてください。

方法	最高のフィット	ホストページ管理	主なトレードオフ
ダイレクトiフレーム	自己完結型の地図またはプロバイダーの埋め込み	低	最速のセットアップ、限定な統合
Webコンポーネント	簡単なHTMLで再公開可能な地図	ミディアム	クリーンマークアップ;動作はコンポーネント契約に依存します
JavaScript SDK	カメラ、ライフサイクル、イベント、またはAIとの製品統合	高	さらに実施責任
Nativeマップライブラリ	完全カスタムマップアプリケーション	最も高	最大制御、最大のエンジニアリング面

直接iframe、Webコンポーネント、JavaScript SDK、およびネイティブマップライブラリを、設定、制御、ライフサイクル、カスタマイズ、セキュリティ上で比較したメソッド決定アーキテクチャを埋め込みます。

地図が自己完結しており、ホストページでは表示だけが必要で、実装工数を最小限にしたい場合は直接iframeを使います。HTMLのiframe要素は別の埋め込みブラウジングコンテキストを作るため、分離には有効ですが、固有のリソースとアクセシビリティ上の配慮を持つ別の文書環境になります。宣言的なHTML要素を使い、地図IDやカメラなどの属性で十分で、内部実装をプロバイダーに任せる場合はWebコンポーネントを選びます。カスタム要素は、安定した公開仕様の背後に読み込みやメッセージ処理を隠せます。カメラやテーマの更新、ルート変更時の破棄、ライブレンダラーへの接続、ブラウザー認証、イベント、AIワークフローの連携が必要ならJavaScript SDKを使います。

Kaleidr Viewerの埋め込みはどのように動作する？

Kaleidr Viewerは、共有IDを使って公開済みのKaleidrマップを埋め込みます。Viewerは独自の地図を管理し、<kaleidr-map>コンポーネント内部のiframe境界で動作します。ホストページはSDKハンドルと文書化されたメッセージングインターフェースを通じて、対応する動作を制御できます。現在の仕様には4つの重要な特性があります。product="viewer"は公開地図Viewerを選択し、share-idは公開地図を識別し、Viewerへのアクセスは共有リンクで制御されAPIキーを必要とせず、公開者が指定した許可ドメインも引き続き適用されます。Viewerは独自の地図を管理する一方、Kaleidr Chatはホストアプリケーションですでに動作しているMapbox、Google Maps、MapLibre、Leafletのインスタンスに接続できます。

公開されているビューアーのセキュリティとライフサイクル:ホストサイトは、バージョン化されたローダーを読み込み、共有IDでkaleidr-mapを宣言します。Webコンポーネントは出自を検証し、iframe境界を作成します。また、公開された地図サービスでは、共有リンクと許可されたドメインチェックを別の分析パスで実施します。

製品をマウントする前に、バージョン指定されたローダーをhttps://cdn.kaleidr.com/embed/v1/kaleidr.jsから一度だけ読み込みます。ローダーは<kaleidr-map>を定義してwindow.Kaleidrを設定し、選択した製品バンドルを必要時に読み込みます。公開地図を最小構成で埋め込む場合は、カスタム要素に高さを明示します。

<kaleidr-map
  product="viewer"
  share-id="abcd1234"
  style="display:block; height:520px;">
</kaleidr-map>

この例は、現行のクイックスタート、<kaleidr-map>リファレンス、Viewer埋め込みドキュメントに沿っています。abcd1234を公開地図の共有IDに置き換えてください。地図は公開済みで、ホストドメインでの表示を許可されている必要があります。公開仕様に含まれない内部Viewer URLを組み立てず、文書化されたコンポーネントを使用してください。

レスポンシブでアクセシブルな地図ページを作るには？

埋め込まれた地図には、明示的な高さが必要です。1つがないと、コンテナが崩壊したり、レイアウトが不安定になったり、プロバイダー固有のデフォルトに後退する可能性があります。マップが読み込まれる前にスペースを空けるシェルで要素を包み込む。全幅、最小の高さ、および狭いスマートフォンでは、デスクトップ上で16:9のアスペクト比、より高い固定最小サイズで配置されることが多い。スペースの貯蔵により、予期しないレイアウトの移動が減少します。定義された寸法のない埋め込みは、累積レイアウトシフトの一般的な原因です。web.dev CLSのガイドライン)実際の地図はアスペクト比に頼るのではなく、実際にテストする。デスクトップでは浅いワイドスクリーンマップが頻繁に動作するが、スマートフォンでは使いにくくなる。

デスクトップおよびモバイル向けインタラクティブマップレイアウト。予約された高さ、可視フォーカスリング、検索とマーカーによるキーボードパス、および同等の位置情報リスト。

Viewer要素は、対応している場合にcenter、zoom、pitch、bearing、themeを監視します。centerは経度、緯度の順です。注目する地区、開発計画と交通、検索やフィルターを備えた全国表示など、地図の目的がすぐに伝わる初期カメラを選びます。ホストページでハンドルが必要な場合は、ローダーの読み込み後に命令型APIでマウントします。

const viewer = Kaleidr.mount("#featured-map", {
  product: "viewer",
  shareId: "abcd1234",
  center: [-0.12, 51.5],
  zoom: 11
});

// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
  viewer.destroy();
});

Kaleidr.mount()は製品バンドルの読み込み中でも同期的にハンドルを返し、準備完了前の呼び出しはキューに入ります。ハンドルは常にdestroy()を提供し、選択した製品が対応していればsetCamera()やsetTheme()も利用できます。シングルページアプリケーションでは、ルートのライフサイクルに破棄処理を結び付け、画面遷移の繰り返しで埋め込みが重複しないようにします。

インタラクティブな地図は、重要な情報にアクセスする唯一の方法であることはできない。 WCAG 2.2 利用可能なWebコンテンツのフレームワークを提供する:地図に意味のある見出しとラベル付き領域を指定し、名前、住所、カテゴリ、アクションを含む同等の位置情報リストを公開し、キーボードユーザーがトラップなしで地図に到達して残せることを確認し、色だけのマーカーを避けます。生のiフレームの場合、「map」などの一般的なラベルではなく、記述型のtitle属性を含める。

ドメイン、パフォーマンス、SEOをどう扱うべきか？

共有IDは、無制限の公開権限を意味しません。Kaleidr Viewerは共有リンクでアクセスを制御し、公開者が指定した許可ドメインも適用します。承認されたサイトに限定された地図は、共有IDを知っているだけでは別のサイトに表示できません。本番環境、必要に応じたwwwの有無、ステージング、対応するローカル開発環境をドメイン一覧に含めてください。Kaleidrの現行料金ではProとEnterpriseが埋め込みに対応しています。Viewer自体にAPIキーは不要ですが、本番導入前にプラン、地図読み込み枠、公開設定を確認する必要があります（料金）。

地図を意味のある応用分野として扱い、活用する。読み込み前の寸法を予備する。初期ビューポート(ネイティブ)に必須でない場合、レイジーロードまたは低展開マップを延期する loading="lazy" 生のiフレームに適用されますが、カスタムコンポーネントにはホスト側のインターセクションオブザーバーまたはクリック・ツー・ロードのファサードが必要になる場合があります。ページの最優先事項である地図を延期しないでください。重複したマップスタックを1ページにロードし、ローダーの時間、インタラクティブな時間、タイルの転送、および実際のデバイスでのモバイルメモリの読み込みを測定します。

ホストページには依然としてクローブル可能で説明的なテキストが必要です。地図が上部付近に何を含んでいるかを記述し、HTMLで重要な場所や結論を公開し、わかりやすい見出しを使用し、目に見えるコンテンツと一致する場合にのみ構造化データを追加します。Googleは、JavaScriptのレンダリングが検索システムに追加の段階をもたらすと文書化しています。JavaScript SEOの基本)埋め込みを、マップ中心だけで異なる多数のほぼ識別可能なURLではなく、安定した正理のページ内に配置してください。埋め込みステップの前に作成された地図の作成と公開は、以下の内容で表されます AIインタラクティブマップビルダー.

間違い	何が起きるか	推奨訂正
明示的な地図の高さはありません	地図が崩壊したり、レイアウトが変更されたりする	リロード前にレスポンシブサイズをリザーブ
内部ビューアーの生のURLを使用する	ホストは文書化されていない詳細によって異なります	使用 `<kaleidr-map>` `Kaleidr.mount()`
Domainは許可されていません	ある環境で作業が失敗、生産に失敗	承認された正確なデプロイメントドメインを追加する
すべての地図をすぐに読み込み、	不要なJavaScript、タイル、およびデータ	地図を以下で区立てするか、クリック・ツー・ロードを使用してください
マプのみのコンテンツ	ユーザーと検索システムは重要な事実を見逃しています	テキストの要約と同等の場所リストを追加する
スパでの催涙なし	重複インスタンスとリスナーが蓄積	ハンドルとコールを保存 `destroy()`
地図のビューのみを追跡する	露出はタスクの完了と誤認される	詳細、詳細、および変換の追跡
プライベートな運用データの埋め込み	共有可能な表面は誤った記録を露出させる	アプリケーションの承認されたワークフローを使用してください

結論

自己完結したプロバイダー地図で十分なら直接iframeを使います。管理された公開仕様に基づく簡潔で宣言的な埋め込みにはWebコンポーネントを使います。カメラ制御、ライフサイクル管理、AI連携、認証、より深い製品統合が必要ならJavaScript SDKを選びます。Kaleidr Viewerは、ブラウザー向けAPIキーなしで複数のWebサイトに一貫して表示する公開地図向けです。ホストページがkaleidr.jsを読み込み、共有IDを渡し、レスポンシブコンテナを確保し、許可ドメインに従います。適切な埋め込みは安定して読み込まれ、目的を明確に伝え、モバイルとキーボードで利用でき、重要情報を地図外にも提示し、訪問者が測定可能なタスクを完了できるようにします。

公開済みのKaleidrマップを埋め込む

Kaleidr Studioで地図を公開し、共有IDをコピーして、バージョン指定されたJavaScriptローダーからViewerを追加します。コンポーネントとメッセージングの仕様は、**Viewer埋め込みドキュメントを参照してください。地図をより大きな製品ワークフローに組み込む場合は、開発者ドキュメント**でChat、Editor、Tiles、認証、Platform APIを確認してください。

よくある質問

Webサイトにインタラクティブマップを埋め込むには？

公開された地図またはプロバイダーを選択し、サポートされているiframe、Webコンポーネント、またはJavaScript SDKをページに追加し、レスポンシブコンテナを予約してアクセスを設定し、地図外で利用可能なテキストを提供します。

iframeは地図を埋め込む最も簡単な方法ですか？

通常です。iframeは、地図が自給自足され、ページがほとんど制御されない場合に適合します。WebコンポーネントやSDKは、ホストが安定した製品契約、カメラの更新、ライフサイクル管理、イベント、またはAIの連携を必要とする場合に優れています。

Kaleidr ViewerにはAPIキーが必要ですか？

いいえ。現在のビューアーは共有リンクゲートで、公開された地図の共有IDを使用しています。パブリッシャー定義の許可ドメイン制限は引き続き適用されます。

埋め込み地図をレスポンシブにするには？

グラフを表示し、明示的な寸法をマッピングし、フル幅を使用し、最小の高さを確保し、狭い画面に対して高さやレイアウトを調整してください。モバイルで実際のコントロールおよび情報パネルをテストしてください。

JavaScriptから埋め込みKaleidrマップを操作できますか？

はい。必須のビューアー統合により、カメラのアップデートをサポートし、常に提供できるハンドルが返される destroy() 引き裂ぎ、断裂。

参考文献

Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls

@misc{kaleidr_viewer_embed,
  title  = {Viewer -- Embed a Published Map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{mdn_iframe,
  title  = {iframe: The Inline Frame Element},
  author = {{MDN Web Docs}},
  note   = {Accessed 2 August 2026},
  url    = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}

@misc{w3c_wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 2 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}

@misc{google_javascript_seo,
  title  = {Understand JavaScript SEO Basics},
  author = {{Google}},
  note   = {Google Search Central; accessed 2 August 2026},
  url    = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}