地図エディターを組み込む

このガイドを完了すると、ブランドに合わせた Kaleidr の地図編集ツールを Kaleidr ベースマップ上に表示できます。Free を含むすべてのプランで利用できます。新しいキーに標準で含まれる design スコープ付きの公開可能キーが必要です。

編集内容は保存されません

埋め込みエディターの作業内容はページのメモリ上にのみ保持されます。埋め込みから保存・エクスポート・公開することはできず、ページに変更コールバックも送られません。ページの再読み込みや handle.destroy() により編集内容は失われます。永続的な地図が必要な場合は Kaleidr Studio で作成し、Viewer で埋め込んでください。

準備するもの

• kaleidr.com/api-keys で発行した公開可能キー（kld_pk_live_…）。API キーの取得を参照してください。
• テストページのオリジン（例：http://localhost:3000）をキーの許可済みオリジンに登録してください。制限がなければ任意のサイトで使用できます。
• npx serve . など、HTTP でページを配信する方法。
• サイトにコンテンツセキュリティポリシーがある場合は、Content Security Policy に記載されたエディター用の許可設定。エディターはページ内で実行されるため、iframe 製品とは異なり connect-src、img-src、worker-src、font-src、style-src の設定が必要です。
• 同じページに別の Kaleidr エディターがないこと。

ステップ 1：サイズを指定したコンテナーを追加してマウントする

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

表示される内容： コンテナー全体に世界表示の Kaleidr ベースマップ（組織で別の既定値を設定していない場合は kaleidr-morning）が表示され、地図上に Create ボタンが現れます。Create を押すと、テキスト、画像、マーカー、ポップアップのツールを備えたサイドバーが開きます。

コンテナーには高さが必要です。エディターはコンテナーの幅と高さを 100% 使用し、すべてのパネルはコンテナー内に収まります。

カスタム要素も使用できます。既定で display:block なので高さが適用されます。Safari 16.4 より前のバージョンにも対応するため、例では display:block を明示しています：

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

ステップ 2：ベースマップと初期カメラを選ぶ

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

表示される内容： 傾斜と回転を付けたロンドン中心部の暗いベースマップ。

ベースマップは次の優先順位で選択されます：

1. styleId を指定した場合、そのスタイルを使用します。例：kaleidr-morning、kaleidr-afternoon、kaleidr-evening、kaleidr-night、kaleidr-plain、kaleidr-editorial。説明は Tile リファレンスをご覧ください。
2. それ以外は、組織の既定のベースマップがあればそれを使用します。
3. どちらもなければ kaleidr-morning を使用します。

カメラの初期値は中心 [0, 0]、ズーム 2、ピッチ 0、方位 0 です。Viewer や Tile とは異なり、エディターでは center なしで zoom を指定できます。

Kaleidr.mount に渡したカメラ設定が有限の数値でなければ無視され、コンソールに通知されます。要素のカメラ属性が数値でない場合は通知なく破棄されます。

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

ステップ 3：パネルのテーマを設定する（任意）

theme を渡してエディターのパネルを製品デザインに合わせます。オブジェクトには最大 17 個の定義済みキーを指定できます。リスト外のキーは無視されます。

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

表示される内容： 選択中のツール、フォーカスリング、主要ボタンがブランドカラーになり、パネルに指定フォントが適用されます。

17 個のキーの一覧はエディターリファレンスにあります。

知っておくべき 3 点：

• 値は CSS 値です。brandColor には CSS 色、cardRadius には CSS 長さ、fontPrimary には任意の font-family 値を使えます。フォントの読み込みはご自身で行ってください。
• エディターのマウント中、テーマはドキュメント全体に適用され、破棄時に元に戻ります。同じカスタムプロパティを使用する場合を除き、独自のスタイルは変更されません。
• テーマを読み取るのはマウント時のみです。エディターでは handle.setTheme を使用できません。変更するには破棄して再マウントする必要があり、編集内容は失われます。

要素では theme を JSON 文字列で指定します：

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

ステップ 4：ページからカメラを動かす（任意）

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

表示される内容： 地図の表示がパリへ移動します。地図上に配置したものはそれぞれの位置に残ります。

setCamera は、ページからエディターの地図を操作できる唯一の方法です。ハンドルから地図オブジェクトは取得できません。

ステップ 5：破棄する

handle.destroy();

destroy() はエディター、地図、パネルをコンテナーから削除し、テーマの値を復元します。編集内容は破棄されます。

シングルページアプリでは、エディターを含むルートまたはコンポーネントが取り除かれるときに destroy() を呼び出してください。カスタム要素の場合はドキュメントから削除すると同じ動作になります。フレームワークとの統合を参照してください。

1 ページに同時に存在できるエディターは 1 つだけです。別のエディターをマウントする前に現在のエディターを必ず破棄してください。

完全なページ例

index.html として保存し、キーを入力して、そのキーで許可されたオリジンから HTTP 配信してください。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

動作の仕組み

項目	動作
実行場所	ページのドキュメント内。地図キャンバスとエディターパネルはマウント先の要素です。
セッション	SDK はエディター起動前にキーを短期間有効なセッションに交換し、マウント中に更新します。
編集内容	メモリ上だけに保持され、保存・エクスポート・公開・ページへの通知は行われません。
ベースマップ	ページが https://tile.kaleidr.com から読み込み、マウント時に固定されます。
テーマ	マウント時にドキュメント全体へ適用され、破棄時に元に戻ります。
カメラ	マウント時に設定し、handle.setCamera で移動できます。
使用量	エディターのセッション要求は地図読み込み回数に計上されず、埋め込みエディターに AI クレジットを消費する機能はありません。 キーを伴うベースマップのリクエストはまとめてマップロードに計上され、1 時間あたり 20 件ごとに 1 回となります。詳しくはマップロードを参照してください。
通知	準備完了、変更、エラーのコールバックはありません。

利用者に知らせること

エディター自体は作業が一時的であることを警告しません。利用者が時間をかけて作業する場合は、後で地図を再取得できると誤解しないよう、上記の完全な例と同様に画面で説明してください。

動作確認

• ページ上： ベースマップがコンテナーを埋め、Create でサイドバーが開き、地図に文字やマーカーを配置できます。
• コンソール： [kaleidr を含むエラーがありません。
• ネットワーク： https://cdn.kaleidr.com からの kaleidr.js と editor.js、ステータス 200 の POST …/sdk/sessions、https://tile.kaleidr.com へのスタイル・タイル要求を確認できます。

問題がある場合

SDK はマウント失敗を [kaleidr:editor] … としてコンソールに記録します。セッション拒否時には HTTP ステータスしか表示しません。原因はネットワークタブの sessions 応答で確認してください。403 は detail、429 は error にコードがあり、説明は detail にあります。

症状	原因	対処
何も表示されず、コンソールに [kaleidr:editor] [editor-embed] attach() requires an { apiKey } が出る	キーを渡していない。	publishableKey を指定します。
表示されず、…/sdk/sessions の CORS エラーと [kaleidr:editor] の取得エラーが出る	キーが不明・失効している、またはオリジンが許可されていない。	キーを確認し、kaleidr.com/api-keys でスキーム・ホスト・ポートを含む正確なオリジンを追加し、数分待ちます。
[kaleidr:editor] kaleidr session exchange failed (403)	キーに design スコープがない（insufficient_scope）、他製品限定（product_not_allowed）、またはプランで禁止（tier_capability_not_allowed）。	ネットワークタブで detail を確認し、既定スコープのキーを作ります。
[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…	サーバーキーを使用した。	公開可能キーを使い、公開済みのページならサーバーキーをローテーションします。
コンテナーが空で高さがない	マウント先に高さがない。	高さを設定し、古い Safari には display:block も指定します。
パネルは表示されるが地図が空白で、https://tile.kaleidr.com が "error":"tile_access_restricted" を含む 429 を返す	ベースマップのホストが拒否した。	公開可能キーと許可オリジンを確認し、変更後数分待って再読み込みします。解決しなければサポートへ連絡してください。 [kaleidr:editor] …
パネルだけ表示され、コンソールに CSP 違反が出る	ポリシーがベースマップ、ワーカー、画像を遮断している。	Content Security Policy のエディター用ディレクティブを追加します。
エディターのスタイルがない	ポリシーがインラインスタイルを禁止している。	style-src に 'unsafe-inline' を許可します。
2 つ目が異常、または最初が止まる	エディターが同時に 2 つある。	先に最初のエディターを破棄します。
[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.	テーマはマウント時のみ読み込まれる。	マウント時に theme を渡します。
[kaleidr] theme string must be JSON…	theme 属性が JSON オブジェクトではない。	属性を単一引用符、JSON 内を二重引用符で囲みます。
テーマキーが効かない	サポート外またはスペル違いで、静かに無視される。	キー一覧を確認します。
編集内容が消えた	ページを更新、エディターを破棄、または要素を移動・削除した。	想定どおりです。冒頭の注意を参照してください。

制限事項

• 埋め込みから保存・エクスポート・公開することはできません。
• 変更コールバック、準備完了通知、エラーコールバックはありません。
• 地図オブジェクトにアクセスできず、独自レイヤーの追加や描画内容の取得はできません。
• データタブ、デザインカタログ、AI パネル、3D モデルライブラリ、共有、プロジェクトはありません。ツールレールには Text、Image、Marker、Popup、Background、Layer、Design、Legend が含まれます。対象範囲を参照してください。
• エディターは 1 ページに 1 つだけです。
• マウント後のベースマップとテーマの変更はできません。

次のステップ

• エディターリファレンス：すべてのオプションとテーマキー。
• フレームワークとの統合：React、Next.js、Vue でのマウントと破棄。
• Content Security Policy：エディターに必要な設定。
• 公開済み地図を埋め込む：永続的な地図を作る場合。