將 Kaleidr Chat 添加到 Google 地圖

完成本指南後，網頁將顯示 Google 地圖及嵌入其中的聊天面板。訪客提出問題時，回答會逐步顯示，涉及的地點也會作為標記出現在 Google 地圖上，相機隨之移動以展示這些地點。所有套餐（包括 Free）均可使用公開密鑰啓用。問題會消耗組織的 AI 積分。

Google Maps 密鑰與 Kaleidr 密鑰相互獨立。Google 對地圖使用計費，Kaleidr 對提問計費。Kaleidr 不會收到您的 Google 密鑰。

開始之前

從 kaleidr.com/api-keys 獲取 Kaleidr 公開密鑰 (kld_pk_live_…)。新密鑰帶有聊天所需的 ai 權限。參閱獲取 API 密鑰。
如果密鑰設置了允許的來源，請加入頁面來源；本地測試可使用 http://localhost:8080。
來自 Google Cloud 項目的 Google Maps JavaScript API 密鑰，並啓用 Maps JavaScript API，在其 Referer 限制中允許頁面來源。
HTTP 網頁服務器，例如 npx serve 或 python -m http.server 8080。直接打開磁盤檔案無法運行。
如果網頁使用內容安全策略，還需允許 Content Security Policy 中列出的 Kaleidr 服務及 Google Maps 所需服務。

Google Maps JavaScript API 始終提供全局變量 google.maps，因此不需要額外將地圖 API 暴露給聊天組件。

第 1 步：佈置地圖和聊天層

將地圖和聊天掛載目標放在同一個定位容器中。聊天層覆蓋在地圖上方，但允許指針事件穿透。

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:relative; height:100%; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

地圖元素通過 height:100% 填滿包裝容器。使用 position:relative 和 z-index:0，可讓 Google 地圖自身的圖層保持在地圖元素內部，並位於聊天圖層之下。

**預期結果：**目前只顯示一個 520 像素高的空白區域。

第 3 步：載入 `kaleidr.js`

使用普通 script 標籤加載 Kaleidr 腳本，確保地圖回調函數運行前 Kaleidr 已經定義。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

**預期結果：**網頁不會發生明顯變化。在控制台中，Kaleidr.version 會傳回版本字符串。

第 3 步：定義創建地圖並掛載聊天面板的回調函數

Google Maps 腳本加載完成後會調用您指定的函數。請在該函數內部創建地圖並掛載聊天面板，因為腳本完成加載前 google.maps 尚不存在。

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

    Kaleidr.mount('#chat', {
      product: 'chat',
      publishableKey: 'kld_pk_live_…',
      map,
      contained: true,
    });
  }
</script>

**預期結果：**仍不顯示內容。函數已經定義，但還沒有被調用。

第 4 步：在回調定義之後加載 Google Maps 腳本

將 Google script 標籤放在定義 initMap 的腳本之後。

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

順序很重要。Google 腳本使用 async，瀏覽器下載完成後會立即執行並調用 initMap。如果把該腳本放在前面，可能在瀏覽器讀取到函數定義之前就執行，導致 Google 報錯：initMap 不是函數。先定義回調就能避免競態條件。 (initMap)

**預期結果：**顯示倫敦市中心的 Google 地圖，左上角有寫著 Ask Kaleidr 的輸入欄。

完整頁面

將文件保存為 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 Chat on Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

        Kaleidr.mount('#chat', {
          product: 'chat',
          publishableKey: 'kld_pk_live_…',
          map,
          contained: true,
        });
      }
    </script>

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

工作原理

訪客	聊天面板	Google 地圖
提交問題	展開對話窗口並逐步顯示回答	暫時不變化
等待回答	為回答中的每個地點顯示結果卡片	找到地點後逐個放置標記。單個地點會平移並調整縮放；多個地點會以四邊 56 像素邊距適配顯示。
點擊標記或結果	打開含簡介、照片和路線工具的地點卡片	點擊結果時移動至該地點
請求路線	顯示距離與耗時	繪制並適配路線
繼續提問	延續同一對話	新標記添加到地圖，原標記保留
關閉聊天	恢復輸入欄並結束對話	清除標記和路線

Google Maps 的特別說明：

標記通過自定義疊加層繪制 HTML 元素。 這樣不需要 Map ID。如果您的頁面加載了 Google 的 marker 庫，聊天組件會改用高級標記，此時 Google 要求地圖提供 mapId。
單地點移動先平移再調整縮放，並非連續的飛行動畫。
多地點適配在四周使用相同的 56 像素邊距。 不會避開聊天面板，因此地點可能被面板擋住；訪客可以拖動地圖或最小化面板。
**路線使用兩條折線：**白色描邊位於彩色路線下方。
地圖視為平面且朝北，助手不會修改朝向或傾斜。
面板掛載期間會在後台自動續期會話，無需管理令牌。

檢查是否正常工作

在網頁中

Ask Kaleidr 輸入欄顯示在地圖左上角。
輸入 Show me three museums in London 並按 Enter，回答文字逐步出現，地圖上顯示三個標記並調整視野以容納它們。

在控制台中

主控台中沒有包含 [kaleidr 的錯誤或警告，也沒有 Google Maps API 錯誤。

在 Network 面板中

要求	預期結果
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200，傳回類似下方示例的 JSON
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream`（提問後）	200，`content-type: text/event-stream`

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat" }

無法正常工作時

SDK 會記錄簡短信息，不會重復伺服器給出的詳細原因。要求失敗時，請在 Network 面板中打開它並查看 JSON 響應。403 和 404 的錯誤程式碼位於 detail；429 的程式碼位於 error，說明文字位於 detail。

現象	原因	解決方法
地圖不存在，Google 報錯 `initMap is not a function`。	Google 腳本比定義 `initMap` 的腳本更早執行。	把 Google script 標籤移到回調定義之後，參閱第 4 步。
無地圖，或灰色地圖與 Google 錯誤對話框。	Google 密鑰配置有誤：未啓用 Maps JavaScript API、未設置計費或來源被限制。	在 Google Cloud 項目中修正；與 Kaleidr 無關。
`initMap` 內提示 `Kaleidr is not defined`。	`kaleidr.js` 使用了 `async` 或 `defer`，或放在 Google 腳本後。	先以普通 script 標籤加載 `kaleidr.js`。
有地圖但無面板，`…/sdk/sessions` 返回 CORS 錯誤並有 `[kaleidr:chat]` 消息。	Kaleidr 密鑰未知、已撤銷或來源不在允許列表中。拒絕時不返回允許該來源的 CORS 頭，瀏覽器會隱藏響應。	核對密鑰，在 kaleidr.com/api-keys 加入包含協議和端口的準確來源。
`[kaleidr:chat] kaleidr session exchange failed (403)`	缺少 `ai` 權限（`insufficient_scope`）、產品受限（`product_not_allowed`）或套餐不允許（`tier_capability_not_allowed`）。	使用包含 `ai` 權限並允許 `chat` 產品的密鑰。 `detail`
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	把服務器密鑰放在瀏覽器中。	改用公開密鑰 (`kld_pk_live_…`)；如果已部署，應撤銷服務器密鑰。
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	腳本遭到 CSP 或廣告攔截器阻止。	在 `script-src` 中允許 `https://cdn.kaleidr.com`。
面板位於瀏覽器窗口左上角而非地圖上。	缺少 `contained` 或 `#chat` 未正確定位。	按第 1 步配置 `contained: true` 及樣式。
面板被地圖遮擋。	地圖元素沒有獨立堆疊上下文。	在 `#map` 上使用 `z-index:0`，在 `#chat` 上使用 `z-index:1`。
面板回答但地圖沒有標記也不移動。	作為 `map` 傳入的不是 `google.maps.Map` 實例，如 DOM 元素或封裝對象。	傳入 `new google.maps.Map(…)` 返回的對象，參閱支援的地圖。
面板回答且地圖移動，但沒有標記。	頁面加載了 `marker` 庫，但地圖未設置 `mapId`。	添加 `mapId` 或不加載 `marker` 庫。
每個問題都提示“Sorry — that didn't go through. Please try again.”	會話已失效，密鑰被撤銷或允許來源發生變化。	檢查密鑰並重新加載頁面。
提示“You've reached your usage limit for now.”	429：組織 AI 積分耗盡或密鑰達到速率限制；同一網頁的所有訪客共享密鑰限制。	參閱配額與速率限制。

更多問題請參閱疑難排解。

限制

頁面不會接收面板的回調或事件；無法通過代碼對問題、回答或標記點擊作出響應。
助手無法讀取您的疊加層、標記或當前地圖顯示區域；提問時只會發送縮放級別。
不能通過聊天面板向助手傳入自定義指令或自有數據。
回答語言、面板標題及輸入佔位文字可用掛載選項 lang、title、placeholder 設置，參閱聊天參考；其他標籤仍為英語。
Google Maps 的適配不會避開聊天面板。
聊天掛載中調用 handle.setCamera() 不會起作用，並會產生警告；請使用 Google Maps API 移動地圖。
在單頁應用中，地圖視圖移除時應調用 handle.destroy()；返回時重新掛載。

完整清單見功能和限制。

後續步驟

主題與佈局：讓聊天面板匹配您的網站。
支援的地圖：助手在 Google Maps 中可執行的操作。
聊天參考：完整選項、句柄和錯誤。
上線檢查清單：發佈前需要核查的項目。

開始之前​

第 1 步：佈置地圖和聊天層​

第 3 步：載入 kaleidr.js​

第 3 步：定義創建地圖並掛載聊天面板的回調函數​

第 4 步：在回調定義之後加載 Google Maps 腳本​

完整頁面​

工作原理​

檢查是否正常工作​

無法正常工作時​

限制​

後續步驟​