Viewer
Viewer 可將你在 Kaleidr Studio 發佈的地圖嵌入自己的網頁。地圖在 Kaleidr 託管的 iframe 中呈現，因此網頁不必載入地圖函式庫，也不需要 API 金鑰。只要已發佈地圖的 ID 即可。
若地圖已在 Studio 中建立，而你想提供訪客查看，例如商店搜尋器、校園地圖、活動路線或文章中的資 料地圖，請使用 Viewer。
概覽
| 問題 | 回答 |
|---|---|
| 需要什麼？ | 已發佈地圖的 ID。不需要 API 金鑰或工作階段。 |
| 哪些方案？ | 包括 Free 的所有方案。發佈需要 Kaleidr 帳戶。 |
| 如何顯示？ | 透過 https://map-embed.kaleidr.com 提供的 iframe。 |
| 顯示什麼？ | 作者發佈的地圖：標記、路線、設定樣式的圖層，以及在 Studio 資料面板上傳的資料集和影像覆蓋層。 |
| 如何嵌入？ | 使用一般 <iframe> 或 SDK 的 <kaleidr-map product="viewer"> 元素。 |
| 如何計費？ | 每次檢視都計入地圖擁有者組織的一次地圖載入。 |
| 網頁能操作地圖嗎？ | 可設定及移動相機，並接收載入完成與錯誤訊息。除此之外不支援其他操作。 |
最簡嵌入
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer"
share-id="YOUR_MAP_ID"
style="display:block; height:480px"></kaleidr-map>
將 YOUR_MAP_ID 替換為發佈後 Studio 嵌入程式碼中顯示的 ID。元素預設為 display:block，所以 height 會生效。範例也明確設定 display:block，以支援 Safari 16.4 之前的版本； 這些版本會讓元素保持行內顯示並忽略 height。
如果無法在網頁加入指令碼（例如網站建立工具、CMS 或支援 HTML 的電子報工具），請改用 Studio 產生的 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>
兩種方式顯示同一張地圖。嵌入已發佈地圖說明何時應選擇哪種方式。
運作方式
- 你在 Studio 發佈地圖。Studio 會指派 ID 並提供嵌入程式碼。
- 網頁載入該程式碼。SDK 元素或一般 iframe 會指向
https://map-embed.kaleidr.com/embed/YOUR_MAP_ID。 - iframe 中的網頁擷取並繪製已發佈地圖，以及作者上傳的資料集和影像覆蓋層。若地圖有允許的網域清單，會先檢查你的網頁網域是否在清單內。
- 地圖繪製完成時，iframe 會向網頁傳送
kaleidr-embed:ready訊息。若無法繪製，則傳送kaleidr-embed:error，並在地圖位置顯示簡短說明。
你的網頁不會收到地圖資料，也無法存取 iframe 內部。地圖函式庫、樣式及網路要求都在 iframe 內，因此內容安全政策只需要允許該框架。
訪客可以執行的操作
- 平移、旋轉與傾斜地圖，並使用地圖上的縮放按鈕、雙指縮放或滾輪調整比例。指標位於地圖上方時捲動會縮放地圖，與 Studio 中相同；指標位於地圖之外時，捲動會移動網頁。
- 瀏覽器請求權限後，使用定位按鈕顯示自己的位置。
- 若作者在 Studio 啟用了地點彈出視窗，點選地圖即可開啟。
- 閱讀地圖圖例，以及底部的資料來源與署名。
- 向 Kaleidr AI 詢問地圖相關問題：若作者在 Studio 的 Kaleidr AI 圖塊中開啟了 Control Tower，可使用 Ask Kaleidr 面板；若開啟了 Popup Window，可在彈出視窗中提問。參閱已發佈地圖上的 Kaleidr AI。
嵌入地圖為唯讀。訪客無法編輯地圖，也不會儲存任何訪客操作。
網頁可以執行的操作
- 設定初始相機：使用
center、zoom、pitch與bearing。預設採用作者儲存的視圖；網頁傳入的各個相機欄位具有優先權。 - 稍後移動相機：使用
handle.setCamera(...)，或更改元素的相機屬性。 - 得知地圖載入或失敗：監聽 iframe 傳送的兩種訊息。
- 移除地圖：使用
handle.destroy()或移除元素。
地圖擁有者的控制項
這些控制項位於 Studio，而不是嵌入程式碼內：
- 發佈與取消發佈。 已發佈地圖顯示 Studio 目前儲存的內容，所以儲存的修改會在下次載入嵌入地圖時公開，不需要重新發佈。重新發佈 會記錄新的發佈版本，但保留相同連結。若要私下修改 ，應先取消發佈，完成後再發佈。取消發佈 會停止地圖的所有嵌入，再次發佈則還原相同的嵌入 URL。參閱取消發佈地圖。
- 上傳的資料。 已發佈地圖顯示的資料集和影像覆蓋層會提供給訪客。若要停止提供，可在資料面板刪除資料集，或取消發佈地圖。分享連結在取消發佈後仍然有效；刪除資料集也會從分享連結移除該資料。已發佈地圖為公開內容，請只發佈任何人都能閱讀的資料。參閱已發佈地圖的上傳資料。
- 允許的網域。 限制可顯示地圖的網站。檢查依據網頁傳送的 Referrer，因此未傳送 Referrer 的網頁無法顯示受網域限制的地圖。
- Kaleidr AI。 在地圖的 Kaleidr AI 圖塊中開啟 Ask Kaleidr 面板（Control Tower）與彈出視窗中的 AI 聊天（Popup Window）。
限制
- Viewer 不使用金鑰，所以金鑰層級的允許來源限制不適用。請使用地圖的允許網域。
- 網頁無法讀取地圖圖層、加入標記或接收點擊事件。
- 嵌入內容不會自行調整高度，請為元素或 iframe 設定高度。
- 當擁有者組織用完當期地圖載入額度時，嵌入位置會顯示額度訊息，直到額度重設。
- 訪客會完整下載地圖顯示的每個資料集，因此使用大型表格的地圖載入速度較慢。
後續步驟
- 嵌入已發佈地圖：發佈、嵌入、限制網域並確認運作正常。
- Viewer 參考文件：所有選項、控制物件、訊息和錯誤碼。
- 已發佈地圖上的 Kaleidr AI：讓訪客針對地圖提出問題。
- 內容安全政策：Viewer 嵌入所需的兩項指令。