地圖編輯器 SDK：如何為 SaaS 產品加入地圖建立功能

地圖編輯器 SDK 能將地圖建立或編輯功能加入 SaaS 產品，不必迫使使用者切換到另一套建置工具。主應用程式繼續管理身分、權限、專案、計費、資料所有權與發佈政策，SDK 則提供頁面內的畫布與工具。Kaleidr Editor 會掛載自己的 MapLibre 地圖，以限制來源的可發佈金鑰驗證身分，並在主系統定義持久化方式之前，將編輯內容保留在記憶體中。

以下章節說明產品邊界、架構、掛載、持久化、安全性、使用者體驗與常見錯誤。若要將對話功能連接至即時算繪器，請參閱如何為地圖加入 AI 聊天。若要了解更廣泛的 SDK 類別，請參閱什麼是 AI 地圖 SDK？。

地圖編輯器 SDK 的要點

編輯介面與產品： 編輯器負責編輯畫布；主系統負責使用者、專案、權限、持久化與發佈。

預設存於記憶體： 獨立版 Kaleidr Editor 不會永久儲存編輯內容，因此應在上線前規劃儲存與發佈。

可發佈金鑰 + design： 使用具有 design scope 且限制來源的瀏覽器金鑰；絕不可暴露伺服器金鑰。

掛載一次，銷毀一次： 將生命週期與 SPA 路由及租戶切換連結。

分離發佈權限： 編輯草稿與發佈公開地圖不應使用相同權限。

SaaS 產品外框內嵌以 MapLibre 為基礎的地圖編輯器，並包含主系統後端持久化與獨立的已發佈 Viewer 路徑。

如何為 SaaS 產品加入地圖編輯器 SDK？

本指南將地圖建立工作區放入既有 SaaS 工作流程。使用者可以開啟專案、在 MapLibre 畫布上編輯、選擇底圖樣式、使用地圖上的可用工具，並在離開時不殘留 SDK 狀態。持久化整合完成後，儲存、發佈與交付仍由主系統控制。範例使用 Kaleidr Editor，因為其文件說明了如何透過共用載入器使用頁面內的 Editor 產品；評估任何第三方地圖編輯器 SDK 時，也可採用相同的責任劃分模型。

地圖編輯器 SDK 與 Studio、Viewer 或 GIS 有何不同？

地圖編輯器 SDK 是可重複使用的元件，可為另一個應用程式加入製作工具，包括導覽、選取、繪製、樣式設定及相關控制項。它不應取代主系統的帳戶系統、資料庫、使用權、稽核記錄或專案工作流程。可靠的邊界是：編輯器負責編輯介面，主產品負責使用者、專案、權限、持久化與發佈決策。

產品類型	主要用途	最適合的情境
地圖編輯器 SDK	在產品內建立或編輯	必須讓使用者留在應用程式內的 SaaS 工作流程
獨立地圖建置工具	專用製作應用程式	可以離開主產品工作的團隊
已發佈地圖 Viewer	唯讀交付	供客戶或大眾瀏覽地圖
地圖算繪器	相機與圖層 API	由開發者完全自訂的地圖產品
GIS	權威空間作業	由組織管理的分析與治理

在共同基礎上比較 Embedded Editor、Kaleidr Studio、Published Viewer 與 Platform Design API 的四路徑決策模型。

Kaleidr Studio 是以提示詞為起點，並依 Prompt → Process → Refine → Deploy 組織的完整製作產品。Kaleidr Editor 是可內嵌的編輯介面，Kaleidr Viewer 則顯示已發佈的地圖。這些路徑共用算繪與樣式概念，但不是可互相替換的產品介面。

SaaS 架構應如何管理編輯器狀態？

正式環境的地圖編輯工作流程，需要明確劃分產品外框、編輯器、認證資訊、後端政策、資料系統與交付的責任。主 SaaS 負責身分、租戶、導覽、專案、計費、權限與工作流程。Kaleidr Editor 負責頁面內編輯介面、自有的 MapLibre 地圖、生命週期及可用的用戶端工具。可發佈金鑰讓瀏覽器能存取 Editor 產品與 design 功能。主系統後端負責授權、持久化、版本控制、稽核、匯入、匯出與發佈政策。權威資料系統負責資料集與商業規則。Viewer 或其他目的地負責交付經核准的唯讀結果。

將瀏覽器中的記憶體內 Editor 工作階段，與主系統後端授權、版本控制、租戶專案儲存區及已發佈 Viewer 交付分離的架構。

主系統後端不得在未重新授權的情況下，信任瀏覽器提供的專案 ID、租戶 ID、資料集 ID 或發佈目標。掛載編輯器會讓地圖建立具有原生體驗，但瀏覽器仍是不受信任的環境。公開文件說明：product: "editor" 會選擇 Editor bundle；預設入口是 attach/in-process，而不是 iframe；styleId 接受目錄中的底圖 ID 或完整樣式 URL；預設底圖為 kaleidr-morning；handle 一定提供 destroy()；在支援的情況下也可更新相機與主題。獨立內嵌不會持久儲存編輯內容；若沒有額外的後端設定，也不包含完整的 AI 驅動 Studio 介面、Control Tower 或自足式 3D 素材庫。

如何安全地掛載 Kaleidr Editor？

請確認：API 金鑰與內嵌具有 Pro 或 Enterprise 存取權；可發佈金鑰獲准使用 Editor 且具有 design scope；開發、測試與正式環境設定了精確的允許來源；目標元素具有明確高度；已選定初始樣式；主系統已有專案與權限模型；並已規劃持久化策略和 SPA 銷毀流程。只從 https://cdn.kaleidr.com/embed/v1/kaleidr.js 載入一次有版本的載入器。載入器預設為休眠狀態，因此應在載入前啟用內嵌，或在每次掛載時傳入 enabled 選項。最小掛載範例如下：

const editor = Kaleidr.mount("#editor", {
  product: "editor",
  publishableKey: "kld_pk_live_REPLACE_ME",
  styleId: "kaleidr-morning",
  enabled: true
});

window.addEventListener("pagehide", () => {
  editor.destroy();
});

將預留金鑰替換為真正的可發佈金鑰，為編輯工具保留足夠的畫布高度，並在地圖外部宣告載入或失敗狀態。此範例遵循目前的 Editor attach 參考、Editor 整合指南及 kaleidr.js 載入器參考。它只負責掛載編輯器，不會儲存記憶體中的規格，因為公開的 handle 參考並未記載持久化方法。若宣告式標記已足夠，可以在 <kaleidr-map> 元素中指定 product="editor"、publishable-key 與 style-id。主系統需要明確的 handle 或由框架管理的生命週期時，應使用命令式 API。在 React 或其他 SPA 中，只在 effect 內掛載一次，並於清理時呼叫 destroy()；不要在每次表單欄位變更時重新掛載。

如何規劃持久化、安全性與使用者體驗？

獨立內嵌會將編輯內容保留在記憶體中。團隊通常選擇三條路徑之一：將 Editor 當作原型設計的暫時介面；若使用者可以離開 SaaS 外框，則在 Kaleidr Studio 中完成全部製作；或者建立與主系統整合的工作流程，包括專案載入、驗證、草稿儲存、版本控制、衝突處理、核准、發佈、復原與稽核。公開的 Editor SDK 參考並未記載可以自行假設的方法，例如未記載的儲存方法或變更監聽器；在向客戶承諾儲存功能前，請與 Kaleidr 確認受支援的狀態傳輸介面。資料集分析、部分套用地圖規格、樣式或主題目錄等平台 design 路由，應透過伺服器金鑰放在主系統後端。瀏覽器中的 Editor 則繼續透過 SDK 使用可發佈金鑰。

多租戶安全模型，將瀏覽器可發佈金鑰、Kaleidr 工作階段、主系統授權、依租戶隔離的專案儲存區，以及從草稿到發佈的狀態分開。

將可發佈金鑰限制在精確來源，於本機開發以外強制使用 HTTPS，將金鑰限制在 design 和必要產品，並在切換帳戶或租戶時銷毀編輯器。在後端依使用者與租戶授權每個專案和資料集，獨立於瀏覽器狀態驗證所有權，在持久儲存或發佈前驗證地圖規格，並分離草稿、審查與發佈權限。OWASP API Security Top 10 將物件層級授權失效列為主要風險：瀏覽器提供的專案 ID 從來不足以構成授權。保持產品外框可見，讓使用者知道正在編輯哪個專案；將儲存與發佈放在主系統介面，不要只根據記憶體中的編輯內容產生錯誤的「已儲存」狀態；並保留比 Viewer 一般所需更多的垂直空間。為編輯器區域設定無障礙名稱，保留對周邊操作的鍵盤存取，避免焦點陷阱，宣告儲存與錯誤狀態，並依 WCAG 2.2 儘可能提供不需拖曳的替代操作。

錯誤	後果	建議修正
假設獨立版 Editor 會永久儲存工作	工作階段結束時，使用者會遺失變更	明確設計持久化並確認整合介面
假設未記載的 handle 方法	正式環境依賴不存在的 API	僅使用已記載的方法
在瀏覽器程式碼中暴露伺服器金鑰	後端 bearer 變成公開資訊	使用限制來源的可發佈金鑰
未啟用 SDK 就掛載	載入器維持休眠	啟用內嵌或傳入 `enabled: true`
未設定容器高度	編輯器塌縮或無法使用	保留足夠的響應式高度
將 Editor 與 Studio 視為相同產品	預期超出獨立內嵌的能力	區分內嵌編輯與 Studio 的完整製作
信任瀏覽器中的租戶 ID	可能發生跨租戶存取	在後端重新授權每個專案
忽略 SPA 銷毀處理	重複的編輯器與監聽器持續累積	保留 handle 並呼叫 `destroy()`

最終結論

地圖編輯器 SDK 可以為 SaaS 產品加入地圖建立功能，不必從頭重建完整的編輯畫布、算繪器整合與瀏覽器身分驗證模型。Kaleidr Editor 目前提供以 MapLibre 為基礎、可內嵌於頁面的介面，並透過具有 design scope 的可發佈金鑰驗證。獨立內嵌將編輯內容保留在記憶體中，因此掛載編輯器不等於交付完整的持久化製作系統。產品需要整合式編輯介面，且主系統團隊將負責專案、權限、持久化、發佈與可稽核性時，應選擇 Editor SDK。若可接受獨立的完整製作工作流程，則選擇 Kaleidr Studio。在向客戶承諾儲存功能之前，應確認狀態傳輸以及所有 AI 輔助介面。

為 SaaS 產品加入地圖編輯功能

使用有版本的 JavaScript 載入器、限制來源的可發佈金鑰與 design scope 掛載 Kaleidr Editor。請**閱讀 Editor 整合指南，了解連接選項與生命週期。關於身分驗證、design 端點和主系統整合工作流程，請查閱開發者文件**與 Enterprise 要求。

常見問題

什麼是地圖編輯器 SDK？

地圖編輯器 SDK 是可重複使用的元件，可為另一個應用程式加入地圖建立或編輯工具。主產品通常繼續管理使用者、專案、權限、持久化與發佈。

Kaleidr Editor 可以內嵌於 SaaS 產品嗎？

可以。目前的 SDK 記載了如何使用 product: "editor" 在目標元素中掛載。Editor 會在頁面中建立自己的 MapLibre 地圖。

獨立版 Editor 會儲存使用者的地圖嗎？

不會。公開文件說明編輯內容存在於記憶體內的規格中，獨立內嵌不會將其持久儲存。請在上線前規劃主系統持久化。

Editor 使用哪一種認證資訊？

透過 SDK 使用具有 design scope、且僅限核准來源的瀏覽器可發佈金鑰。絕不可在瀏覽器程式碼中放置伺服器金鑰。

Kaleidr Editor 與 Kaleidr Studio 相同嗎？

不同。Studio 是以提示詞為起點的完整建立與發佈產品。Editor 是供其他應用程式內使用的可內嵌編輯介面。

References

Kaleidr. Attach the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/guides/attach-the-editor
Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
Kaleidr. CORS & Allowed Origins. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
Kaleidr. Editor — Mount the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/editor-attach
Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/endpoints
Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
Kaleidr. Pricing & Plans. kaleidr.com. Accessed 3 August 2026. https://kaleidr.com/pricing
MapLibre. Map — MapLibre GL JS. Accessed 3 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
OWASP. OWASP Top 10 API Security Risks — 2023. Accessed 3 August 2026. https://owasp.org/API-Security/editions/2023/en/0x11-t10/
World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 3 August 2026. https://www.w3.org/TR/WCAG22/

@misc{kaleidr_editor_attach,
  title  = {Editor -- Mount the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/editor-attach}
}

@misc{kaleidr_editor_guide,
  title  = {Attach the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/guides/attach-the-editor}
}

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

@misc{kaleidr_auth_scopes,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{owasp_api_security,
  title  = {OWASP Top 10 API Security Risks -- 2023},
  author = {{OWASP}},
  note   = {Accessed 3 August 2026},
  url    = {https://owasp.org/API-Security/editions/2023/en/0x11-t10/}
}

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