Tile
Tile 可在您的頁面中放置一張 Kaleidr 底圖。您選擇 kaleidr-morning 或 kaleidr-night 等樣式後，SDK 會通過 Kaleidr 托管的 iframe 顯示它。您的頁面無需加載地圖庫。
當您需要美觀且可交互的底圖，又不必自己在其上繪制元素時，可以使用 Tile：例如位置背景、“我們在哪裡”信息面板，或者供 Kaleidr 聊天面板展示回答的地圖。
如果您已有 Mapbox、MapLibre、Google Maps 或 Leaflet 地圖，就不需要 Tile。直接把 Chat 添加到現有地圖即可。
概覽
| 問題 | 回答 |
|---|---|
| 需要甚麼？ | 可發佈密鑰 (kld_pk_live_…) 且具有 maps 權限範圍。新密鑰默認包含該權限。 |
| 支持哪些套餐？ | 所有套餐，包括 Free。 |
| 如何渲染？ | 通過由 https://map-embed.kaleidr.com 提供的 iframe。 |
| 如何選擇外觀？ | 使用 style-id。下文列出了六種通用樣式。 |
| 如何收費？ | 每次 Tile 會話計一次地圖加載。參見地圖加載如何計數。 |
| 頁面可以操作地圖嗎？ | 可以設置或移動鏡頭、更換樣式，並監聽加載成功和錯誤消息。 |
最簡單的嵌入方式
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="display:block; height:480px"></kaleidr-map>
正常運行需要滿足三個條件：
- 密鑰。 在 kaleidr.com/api-keys 創建可發佈密鑰。參見獲取 API 密鑰。
- 允許的來源。 如果密鑰配置了允許的來源，頁面來源必須在其中。頁面必須通過 HTTP 或 HTTPS 提供，而不能直接從磁盤打開。
- 高度。 元素默認使用
display:block，所以其height屬性生效。示例中也寫有display:block，用於兼容 16.4 之前仍將該元素視為行內元素的 Safari。
樣式
style-id | 外觀 |
|---|---|
kaleidr-morning | 明亮：白色地面、青色水域、白色道路。 |
kaleidr-afternoon | 中等色調地面、綠色植被和灰色道路。 |
kaleidr-evening | 黃金時段：溫暖的沙色和橄欖色調。 |
kaleidr-night | 深海軍藍與炭灰色，搭配琥珀色高速公路。 |
kaleidr-plain | 白色畫布，含邊界和地點標籤。從縮放級別 15 開始顯示 3D 建築。 |
kaleidr-editorial | 去掉標籤的下午配色，適合小型或裝飾性地圖。 |
請始終傳入 style-id。如果省略，嵌入地圖會使用組織的默認底圖（如果已設置）；否則會顯示錯誤。
工作原理
- SDK 將您的可發佈密鑰發送給 Kaleidr，並取得短期 Tile 會話。這一步會檢查密鑰、權限範圍及頁面來源，同時計算一次地圖加載。若組織設置了默認底圖，響應也會攜帶該底圖信息。這就是 Tile 會話的全部用途：地圖不會再使用該會話調用接口。
- SDK 用顯示所選樣式的 iframe 替換元素內容。iframe URL 僅包含樣式 ID 和您指定的鏡頭信息，不會包含可發佈密鑰或會話令牌。
- 地圖在 iframe 內繪制。您頁面的內容安全策略只需允許加載器、會話請求和 iframe。
- 地圖繪制完成後，iframe 會向頁面發送
kaleidr-embed:ready消息。
訪客可以執行的操作
可以平移、旋轉和傾斜地圖，也可以通過地圖上的按鈕、雙指縮放或滾輪縮放。指標位於地圖上方時滾動會縮放地圖；指標位於地圖之外時，滾動會移動頁面。
您的頁面可以執行的操作
- 設置初始鏡頭： 使用
center、zoom、pitch和bearing。 - 稍後移動鏡頭： 使用
handle.setCamera(...)。 - 切換樣式： 使用
handle.setStyle('kaleidr-night')，無需重新加載。 - 搭配聊天面板： 聊天實例可指向 Tile 元素，在其上顯示回答內容。
- 獲知何時加載完成： 監聽
kaleidr-embed:ready消息。
地圖加載如何計數
Tile 用量以地圖加載次數計量，與您已發佈地圖的瀏覽計量單位相同。每次 SDK 獲取 Tile 會話都會計為一次地圖加載：
- 地圖首次掛載時計一次；
- 只要掛載仍在運行，SDK 每次在會話到期前不久續期時再計一次。默認會話時長為 15 分鐘；
- 銷毀並重新掛載實例，或移除元素後重新插入時，再計一次。
訪客瀏覽頁面幾分鐘會消耗一次地圖加載。頁面保持打開一小時則大約消耗五次。這並不是“每次頁面瀏覽只計一次”，因此應銷毀不再顯示的 Tile 實例。
當組織用完當前計費週期的地圖加載額度時，新的 Tile 會話會收到 HTTP 429 拒絕。新掛載的地圖不會顯示任何內容，而已經顯示的地圖仍會留在頁面上。額度說明見配額與速率限制。
限制
- Tile 是底圖。您的頁面無法在其上添加自己的標記、圖層或彈出窗口，也收不到點擊或鏡頭事件。配對 的聊天面板可以在其上標注地點。
- Tile 是受支持的 Kaleidr 底圖展示方式。
- 修改已掛載元素的
style-id不會產生效果。請使用handle.setStyle或插入新元素。 - 不存在專門的 Tile 密鑰。其他 Kaleidr 產品使用的可發佈密鑰也可用於 Tile。
後續步驟
- 使用 Kaleidr 底圖：分步教程。
- Tile 參考文檔：全部選項、控制句柄、消息及錯誤。
- Chat：可搭配 Tile 地圖使用的助手。
- 內容安全策略：嵌入 Tile 所需的三項指令。