嵌入已發佈的地圖

完成本指南後，您在 Kaleidr Studio 中製作的地圖便可顯示在自己的網頁上，限制允許展示地圖的網站，並讓頁面獲知地圖是否成功加載。所有套餐（包括 Free）都支援。發佈地圖需要 Kaleidr 賬戶，但不需要 API 密鑰。

開始之前

您準備好向公眾展示的 Kaleidr Studio 地圖。
可自行編輯的網頁。SDK 元素需要 <script> 標籤，普通 iframe 只需要 HTML。
如果網站使用內容安全策略（CSP），需要允許嵌入 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 區域及其下方的實時預覽。

已發佈地圖展示的是 Studio 中當前儲存的內容，而不是點擊 Go Live 時生成的副本。Studio 會在編輯過程中儲存更改，因此發佈後每次儲存的編輯（包括新添加的數據集）都會在下次加載嵌入地圖時公開。無需為這些修改再次點擊 Re-publish。該按鈕只會記錄一個新的已發佈版本，地圖 ID、鏈接和嵌入代碼不變；訪客在重新發佈前後看到的地圖相同。

若要修改已發佈地圖而不讓訪客看到編輯過程，請先選擇 Unpublish，完成後重新發佈，或者在地圖副本中進行編輯。取消發佈會讓該地圖所有嵌入停止工作，直到重新發佈。

發佈範圍包含您上傳的數據。地圖 Data 面板中的數據集與圖像疊加層會按照設定的圖層樣式向訪客顯示。在發佈可能包含敏感信息的數據前，請閱讀已發佈地圖上的上傳數據。

第 2 步：複製嵌入代碼

Embed code 區域提供兩種格式。

Studio 中的格式	獲得的代碼	適用場景
iFrame	指向已發佈地圖的普通 `<iframe>`。	網頁無法運行自定義腳本（例如網站構建器、CMS 區塊、維基頁面），或者只需顯示地圖。
Developer	SDK 加載腳本及 `<kaleidr-map product="viewer">` 元素。	能控制網頁代碼，希望從程序控制或移動相機、在地圖上疊加聊天面板，或管理單頁應用中的地圖生命週期。

選擇格式，然後點擊 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 像素的高度，即使之後設置高度也不會自動調整。在隱藏標籤頁或折疊面板中，元素可能沒有高度；應等到可見時再掛載，或預先設置明確高度。
響應式高度可以使用任何能計算出高度的 CSS，例如 height:60vh、aspect-ratio:16/9 或 flex/grid 佈局單元。

第 4 步：設置初始相機視角（可選）

地圖初始展示作者儲存的視角。作者可以針對桌面、平板和手機寬度分別儲存視角，也可以讓地圖自動包含全部內容；後一種模式會根據嵌入容器寬度選擇視角，並在容器調整大小時重新適配。如果需要在其他位置打開地圖，請傳入相機參數。center 的坐標順序為先經度、後緯度。

在 SDK 元素上：

<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 時需要瞭解兩點：

setCamera 是 Kaleidr.mount 傳回的句柄上的方法，不是元素本身的方法。document.querySelector('kaleidr-map').setCamera 為 undefined。如果通過元素掛載地圖，請修改它的 center、zoom、pitch 或 bearing 屬性，地圖會立即跳到新視角，沒有動畫。
Kaleidr.mount 傳回後可隨時調用該方法。即使 iframe 中的地圖尚未準備完成，相機命令也會被保留，並在收到就緒訊息後執行，因此不必等待第 6 步介紹的 kaleidr-embed:ready 訊息。初始視角應通過掛載參數設置。
與初始相機設置一樣，之後調用此方法也會覆蓋作者儲存的視角並關閉尺寸變化時的自動重新適配；未傳入的欄位仍保持當前值。

第 5 步：限制哪些網站可以顯示地圖（可選）

默認情況下，知道已發佈地圖 ID 的任意網站都可以嵌入該地圖。限制方法如下：

在 Studio 打開地圖並選擇 Share。打開 Share 對話框時，如果地圖尚未發佈，會自動發佈，並且每次都會新建一個分享鏈接。
打開 Embed 標籤頁。
將訪問權限下拉菜單從 Any domain 改為 Specific domains。
每行輸入一個網域，例如：
```
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。

檢查依賴於 Referer 信息

地圖通過瀏覽器加載 iframe 時發送的來源信息來判斷網站是否被允許。如果沒有收到 Referer，設置了網域限制的地圖不會顯示。這可能發生於：

網頁在響應頭或 <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 中，Referer 將是外層框架的位址，因此應將該框架的網域加入允許列表。

允許網域只控制地圖可顯示在哪些網站，並不能讓已發佈地圖的內容保密，包括地圖繪制的數據集。參閱已發佈地圖上的上傳數據。不要發佈必須保密的數據。

第 6 步：獲知地圖加載成功或失敗（可選）

SDK 沒有 ready Promise，元素也不會觸發事件。加載結果通過 iframe 向頁面發送的兩種訊息傳遞：

訊息	發送時間	欄位
`kaleidr-embed:ready`	地圖首次完成繪制。	`type`、`id`（地圖 ID）、`source`（`"publish"` 或 `"share"`）
`kaleidr-embed:error`	地圖加載失敗或部分內容無法繪制。	`type`、`id`、`code`、`message`

在 window 上監聽訊息，並檢查訊息的來源及發送訊息的 iframe：

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 的已發佈地圖：可能尚未發佈、已取消發佈或 ID 有誤。	“This map isn't available — it may have been unpublished, paused, or the link is incorrect.”
`domain_not_allowed`	網站不在允許網域列表，或瀏覽器沒有發送 Referer。	“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: 訊息。這些不是公開接口；只匹配上述兩種訊息，忽略其他內容。

完整網頁示例

儲存為 index.html，將 YOUR_MAP_ID 替換為地圖 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 當前儲存的內容；訪客下次加載即可看到修改，不需要重新發佈。
上傳數據	地圖 Data 面板中添加的數據集和圖像疊加層會按照樣式向訪客顯示。參閱上傳數據。
取消發佈	地圖取消發佈後，嵌入框顯示不可用提示。重新發佈後相同的嵌入 URL 恢復。參閱取消發佈地圖。
彈出窗口	僅當作者啓用了彈出窗口時，點擊地圖才會打開地點彈窗。
高度	掛載時元素有明確高度則按該高度顯示，否則固定為 500 像素。
加載	SDK iframe 延遲加載，在接近可視區域時啓動。
密鑰	不需要。不要向 Viewer 掛載傳入公開密鑰；這會產生不必要的會話請求，若請求被拒絕，地圖也無法顯示。

已發佈地圖上的上傳數據

Studio 的 Data 面板中的數據集是發佈地圖的一部分。訪客會看到按照您設定樣式繪制的數據圖層，以及對應位置的圖像疊加層。無論普通 iframe、SDK 元素還是分享鏈接，行為都相同；無需額外開啓功能，嵌入頁面也不需要密鑰。

由於已發佈地圖始終展示當前儲存的內容，即使地圖已經發佈，新增數據集也會在儲存後立即公開，無需重新發佈。

哪些數據會被提供、誰能訪問：

只有已發佈地圖的數據。 數據集僅作為已發佈地圖或分享鏈接的一部分提供給訪客，且僅限地圖包含的數據集。未發佈地圖上的數據集不會提供。
不能單獨獲取數據集。 沒有列出地圖全部數據集的接口；脫離所屬的已發佈地圖，數據集 ID 不能獨立訪問內容。
能打開地圖的人就能讀取數據。 已發佈地圖是公開的。允許網域決定地圖能在哪些網站顯示，不會對數據保密。
發送所有列，而不僅是用於樣式的列。 每個訪客的瀏覽器會收到所有行和所有列。發佈前應從檔案中刪除不宜公開的列，並重新上傳。

如何停止向訪客提供數據集：

您在 Studio 中的操作	對已發佈地圖的影響	對分享鏈接的影響
在 Data 面板刪除數據集	數據集被刪除，不再向訪客提供；地圖其他部分不變。	分享鏈接仍能打開地圖，但不再繪制該數據集圖層。
取消發佈地圖	地圖及其數據集停止提供。	不影響已有分享鏈接；鏈接繼續展示創建時的數據。

如要刪除資料集，請在「Data」面板中找到該資料集所在列，點選垃圾桶圖示並確認。刪除或取代資料集說明完整步驟，以及之後使用復原（Undo）時會發生什麼情況。僅刪除呈現該資料集的圖層並不等於刪除資料集：資料集仍會儲存並保留在地圖中，因此仍會提供給訪客。

分享連結是地圖設計的快照。 它呈現的是建立連結時的地圖狀態：之後編輯地圖或取消發佈，都不會改變連結顯示的內容。快照也包含當時的地圖名稱、允許網域清單及 Kaleidr AI 開關，因此之後變更這些設定，不會改變先前建立的分享連結可在哪裡呈現，或提供哪些 Kaleidr AI 功能。分享連結的 Kaleidr AI 也取決於地圖本身：僅在地圖處於已發佈狀態時運作，且僅限地圖目前允許的網域所包含的網頁，因此取消發佈地圖或移除網域都會使其停止。費用由地圖擁有者支付；請參閱已發佈地圖上的 Kaleidr AI。

分享鏈接是地圖設計的快照。 它展示生成鏈接時地圖的樣子；之後編輯或取消發佈原地圖不會改變該鏈接。不過數據集是例外：分享鏈接會讀取與原地圖相同的已存儲數據，因此刪除數據集也會讓所有使用它的分享鏈接不再顯示該數據。

每次打開 Studio 的 Share 對話框時，Studio 都會發佈地圖並生成一個新分享鏈接。因此多次分享的地圖可能有多個鏈接，每個都保留各自創建時的設計快照。

Studio 沒有暫停或刪除分享鏈接的控制項。鏈接會一直有效，除非刪除其展示的數據或聯繫 Kaleidr 移除鏈接。需要分享較新的地圖狀態時，請再次打開 Share 獲取新鏈接；原來的鏈接保持原有內容。

取消發佈地圖

在 Publish & embed 頁面，已上線地圖的 Re-publish 旁邊有 Unpublish 按鈕。Studio 會詢問：“Unpublish this map? Embeds of it stop working. Share links you have already handed out still show the map, but their Kaleidr AI stops.”確認選擇 Unpublish，否則選擇 Cancel。

地圖的所有嵌入立即停止：框架顯示“不可用”提示併發送 not_found。
地圖保留原 ID。再次選擇 Go Live 後，同樣的嵌入 URL 恢復可用，無需修改網頁代碼。
已經分享出去的鏈接繼續有效，並保留其對應數據。它們的 Kaleidr AI 會停止，直到您再次發佈地圖。

並非所有位置都會立即停止訪問：

已經加載數據的瀏覽器會保留這些數據。 已打開地圖的訪客仍能看到圖層，瀏覽器也可能在接下來的幾分鐘內復用緩存數據。
已經簽發的下載鏈接可能繼續有效最多一小時。 對大型數據集，瀏覽器收到一個臨時下載鏈接；在刪除數據集或取消發佈前簽發的鏈接最長到期時間為一小時。

數據加載方式：

每位訪客都會下載整個數據集。 地圖不會隨著拖動按區域分塊加載數據集。因此行數或列數多的數據表顯示更慢，網絡連接較慢時尤為明顯。請只發佈地圖需要的行和列。
單個數據集加載失敗不會導致整張地圖不可用。 其他地圖內容仍能顯示，只是缺少該圖層。

上傳配額請參閱數據集限制。

地圖瀏覽量如何計算

訪客每次加載嵌入地圖時，都會在地圖所屬組織（而非嵌入網站）的配額中計入一次地圖加載。同一訪客在 24 小時內再次加載同一地圖不會重復計數。Studio 預覽等 Kaleidr 自有頁面中的瀏覽不計入配額。

如果組織在當前週期已耗盡地圖加載配額，嵌入框會顯示達到限制的提示，併發送 map_loads_exhausted，直至配額重置。請參閱配額與速率限制。

檢查是否正常運行

**網頁中：**地圖顯示標記、路線，以及 Studio Data 面板上傳的數據集和圖像疊加層；它們按設定的圖層樣式繪制。地圖縮放按鈕正常工作，地圖底部有版權與來源信息。
**主控台中：**沒有包含 [kaleidr 的錯誤。
**網絡面板中：**請求 https://map-embed.kaleidr.com/embed/YOUR_MAP_ID，狀態為 200。SDK 元素還會從 https://cdn.kaleidr.com 加載 kaleidr.js 和 viewer.js。
**訊息監聽器中：**收到一條 kaleidr-embed:ready 訊息。

故障排查

現象	原因	解決方法
無論設置怎樣的 `height`，地圖都只有 500 像素高。	掛載時元素沒有高度、CSS 將其設為 `display:inline`，或舊版 Safari 未指定 `display:block`。	在元素可見時掛載，並設置 `display:block` 和高度。
完全沒有顯示，主控台出現 `[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`。	`product` 屬性缺失或拼寫錯誤。	設置 `product="viewer"`。
主控台：`[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.`	`share-id` 缺失、為空或包含不允許的字元。	從 Studio 重新複製 ID。
主控台：`[kaleidr:viewer] mount target not found: #map`	`Kaleidr.mount` 運行時目標元素尚不存在，或選擇器錯誤。	在元素後執行腳本或更正選擇器。
主控台：`Kaleidr is not defined`	SDK 腳本尚未載入完成。Studio 示例用 `async` 載入。	移除載入標籤中的 `async`，或在腳本的 `load` 事件中運行代碼。 `kaleidr.js`
框架提示 “This map isn't available…”	地圖尚未發佈、已取消發佈，或 ID 錯誤。	在 Studio 選擇 Go Live，並使用正確 ID；重新發佈保留原 ID。
框架提示 “This map isn't allowed to render on this site.”	網站不在允許網域列表，或沒有發送 Referer。	在 Studio 加入網域，或修改網頁的 Referer 策略。參閱第 5 步。
框架提示 “This map has reached its map load limit.”	地圖所屬組織已用完週期內的地圖載入額度。	等待重置或提高配額。參閱配額與速率限制。
框架提示 “Could not load the map. Please try again in a moment.”	地圖請求失敗。	重新載入；如持續失敗，檢查網路並嘗試在新標籤頁打開 iframe URL。
空白框架且主控台提示 `frame-src` CSP 違規。	安全策略不允許載入框架。	在 `frame-src` 中允許 `https://map-embed.kaleidr.com`。
主控台提示 `script-src` CSP 違規。	安全策略不允許 SDK 載入腳本。	在 `script-src` 中允許 `https://cdn.kaleidr.com`，或者使用普通 iframe。
`setCamera` 沒有效果。	地圖尚未載入、調用仍在等待，或句柄已銷毀。	查看 `kaleidr-embed:error` 訊息和主控台；地圖就緒後會執行之前的相機命令。若 iframe 載入後經過有限等待時間（通常是 10 秒）仍未回報就緒，保留的呼叫仍會送出，主控台會顯示 `[kaleidr] the map frame has not reported ready`；若 iframe 正在顯示錯誤，則沒有地圖可供操作。
`el.setCamera is not a function`	在元素上調用了 `setCamera`。	通過 `Kaleidr.mount` 傳回的句柄調用，或修改元素的相機屬性。
滾動頁面時在地圖處停住。	這是預期行為。指標位於地圖上方時，滾動會縮放地圖。	將指標移到地圖旁邊再滾動。讓地圖高度小於螢幕高度，以便訪客能滾動越過它。
嵌入地圖沒有顯示最新修改。	嵌入地圖只在載入時讀取 Studio 已儲存的內容；頁面在儲存前已經載入。	重新載入嵌入網頁，不需要重新發佈。
嵌入地圖顯示了不該公開的修改。	已發佈地圖會展示 Studio 當前儲存的內容。	撤銷修改；需要私下編輯時先取消發佈，或使用地圖副本。參考
已上傳資料集對應的圖層不見了。	資料集被刪除或此時載入失敗；地圖其他部分仍顯示。	檢查 Studio Data 面板是否仍有該資料集及圖層，然後重新載入網頁。
大型資料集的圖層出現較晚。	每位訪客都要下載整個資料集。	減少上傳的行數和列數，參閱上傳資料。

限制

嵌入地圖是只讀的。網頁不能為其添加標記或圖層、讀取數據或接收點擊事件。
網頁只能接收 kaleidr-embed:ready 和 kaleidr-embed:error 兩種訊息。
不能從嵌入組件直接修改地圖樣式或更換底圖，應在 Studio 中修改，下次加載時生效。
元素掛載後再修改 share-id 不會生效；應移除並重新創建元素，或調用 handle.destroy() 後重新掛載。
允許網域的檢查依賴瀏覽器的 Referer，不是保密措施。

後續步驟

Viewer 參考文檔：所有選項、屬性和訊息。
已發佈地圖上的 Kaleidr AI：讓訪客就地圖提問。
地圖數據集：支援上傳的檔案、限制及欄位角色。
框架集成：在 React、Next.js 和 Vue 中掛載及銷毀地圖。
Content Security Policy：網站安全策略配置。

開始之前​

第 1 步：發佈地圖​

第 2 步：複製嵌入代碼​

第 3 步：將代碼添加到頁面並設置尺寸​

第 4 步：設置初始相機視角（可選）​

第 5 步：限制哪些網站可以顯示地圖（可選）​

第 6 步：獲知地圖加載成功或失敗（可選）​

完整網頁示例​

運行方式​

已發佈地圖上的上傳數據​

分享連結​

取消發佈地圖​

地圖瀏覽量如何計算​

檢查是否正常運行​

故障排查​

限制​

後續步驟​