跳至主要内容

快速入門

本頁按大多數團隊的使用順序，介紹三種最簡便且可運行的集成方式：

  1. 在現有地圖上添加聊天。 聊天面板回答有關地點的問題，並將結果作為圖釘、相機移動和路線顯示在你的地圖上。
  2. 已發佈地圖。 將在 Kaleidr Studio 設計的地圖嵌入你的網頁。
  3. 底圖。 將 Kaleidr 設計的現成底圖放在你的網頁中。

每種方式只需要一個 HTML 檔案。三種方式均可使用 Free 套餐。

方式產品所需金鑰顯示位置
在你的地圖上聊天chat發佈金鑰網頁中，覆蓋在地圖上方
已發佈地圖viewer無需金鑰Kaleidr iframe 內
底圖tile發佈金鑰Kaleidr iframe 內

如果想先瞭解整體模型，請閱讀 Kaleidr 的工作原理。如果不確定需要哪個產品，請閱讀選擇適合的方案。

開始之前​

  • Kaleidr 賬戶。 在 kaleidr.com 注冊。Free 套餐足以運行本頁所有示例。

  • 發佈金鑰，用於聊天和底圖。請前往 kaleidr.com/api-keys 建立；它以 kld_pk_live_ 開頭。取得 API 金鑰介紹表單的操作方式。已發佈地圖不需要金鑰。

  • 網頁服務器。 即使在本地，也請通過 HTTP 提供檔案服務。在檔案所在目錄中可使用以下任一種方法：

    python -m http.server 8000
    # or
    npx serve -l 8000

    然後打開 http://localhost:8000/your-file.html。不要直接從硬盤打開檔案：file:// 網頁沒有可以加入金鑰允許來來源清單的來來源。

  • 如果金鑰設定了允許來來源，必須包含你的網頁來來源。 未設定允許來來源的金鑰可在任何網站使用；設定清單後只能在所列網站使用，因此測試時請添加 http://localhost:8000。

  • 如果網站使用內容安全策略，必須允許 Kaleidr 資來源加載。 未傳送 Content-Security-Policy 標頭的網站不需要額外設定。否則請閱讀內容安全策略。

三種方式都使用同一個 script 標籤。你只需自行加載這一個檔案，掛載產品時它會取得對應產品的程式碼。

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

在你的地圖上聊天​

完成後，你將得到一張 MapLibre GL JS 地圖，聊天面板停靠在地圖中。詢問“在 Bryant Park 附近哪裡能吃到拉麵？”時，回答會流式顯示在面板內，為每個地點添加圖釘，並移動相機以展示這些地點。

此示例使用 MapLibre GL JS。Chat 也可連接 Mapbox GL JS、Google Maps JavaScript API 和 Leaflet；參閱支持的地圖。

1. 建立網頁​

將檔案保存為 chat.html，並把 kld_pk_live_… 替換為你的發佈金鑰。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

請注意檔案中的三個細節：

  • 地圖程式庫必須是網頁全局變量。 聊天程式碼從 window.maplibregl 查找 MapLibre。通過 script 標籤加載 MapLibre 會自動設定它。如果改從 npm 導入，請在掛載前自行賦值：window.maplibregl = maplibregl。
  • map 是地圖對象。 請傳入你建立的實例，而不是 CSS 選擇器。
  • contained: true 需要有定位方式和高度的容器。 面板顯示在掛載目標內。如果沒有 contained，面板會作為固定窗口出現在瀏覽器視口左上角。

示例樣式是一張細節較少的世界地圖。圖釘仍會落在正確的坐標，但如需查看街道，請使用自己的地圖樣式。

2. 提供網頁服務並提問​

在檔案所在目錄啓動本地服務器，打開 http://localhost:8000/chat.html。

預期結果：

  • 地圖填滿窗口，左上角出現帶文本輸入框的聊天面板。
  • 在瀏覽器“網路”標籤頁中，對 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 的請求傳回 200。這表示 SDK 正在用金鑰換取短期工作階段。
  • 輸入一個有關地點的問題，例如 Where can I get ramen near Bryant Park?。回答會流式進入面板，每個地點出現圖釘，相機也會調整以顯示它們。“網路”標籤頁會出現對 …/b2b/v1/chat/control/stream 的請求，並在回答生成期間保持打開。
  • 控制台不應出現包含 [kaleidr 的行。

3. 如果無法正常運行​

現象原因解決方法
面板未顯示，控制台先對 …/sdk/sessions 報 CORS 錯誤，隨後出現 [kaleidr:chat] 錯誤金鑰錯誤、已被撤銷，或網頁來來源不在金鑰的允許來來源清單中。API 響應不包含 CORS 標頭，瀏覽器因此報告 CORS 失敗。檢查金鑰。在 kaleidr.com/api-keys 添加包含端口的精確來來源，或在測試期間清空清單。
面板在瀏覽器左上角，而不是地圖內部缺少 contained: true，或掛載目標沒有定位傳入 contained: true，並為目標設定 position: relative 和高度。
面板能回答，但地圖上沒有圖釘地圖程式庫不是網頁全局變量，聊天無法建立圖釘用 script 標籤加載程式庫，或先設定 window.maplibregl 再調用 Kaleidr.mount。

故障排除按控制台原始消息解釋各種症狀。

下一步：將 Chat 連接到 MapLibre提供完整指南；功能和限制說明面板能做甚麼、不能做甚麼。

已發佈地圖​

完成後，你將在自己的網頁中顯示 Kaleidr Studio 設計的地圖。這種方式無需 API 金鑰，只需地圖的公開 ID。

1. 發佈地圖並複製 ID​

  1. 在 Kaleidr Studio 打開地圖，選擇 Publish（發佈）。
  2. 在 Publish & embed（發佈與嵌入） 頁面選擇 Go Live（上線）。
  3. 在 Embed code（嵌入程式碼） 下複製程式碼片段。ID 是地址的最後一段，例如 https://map-embed.kaleidr.com/embed/abc123 的 ID 為 abc123。

**預期結果：**項目狀態顯示 live，嵌入程式碼下的實時預覽會呈現訪客看到的地圖。

2. 建立網頁​

將檔案保存為 map.html，把 YOUR_SHARE_ID 替換為複製的 ID。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

元素需要設定高度，否則地圖使用 500 像素的後備高度。<kaleidr-map> 預設是 display:block，所以高度生效。程式碼片段也寫了 display:block，以兼容 Safari 16.4 之前的版本；那些版本中元素保持行內狀態，設定高度無效。

如果無法添加腳本（例如網站構建器或 CMS 字段），請使用 Studio 的 iFrame 標籤頁提供的普通 iframe。它不需要加載器：

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_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>

3. 提供網頁服務​

打開 http://localhost:8000/map.html。

預期結果：

  • 地圖寬度與頁面相同、高 480 像素，並從你在 Studio 保存的視圖開始顯示。
  • 指標位於地圖上方時滾動會縮放地圖；指標位於地圖旁邊時，滾動會移動頁面。
  • 在“元素”面板中，有一個 <iframe> 位於 <kaleidr-map> 內，其地址以 https://map-embed.kaleidr.com/embed/ 開頭。

如果框架顯示 "This map isn't available — it may have been unpublished, paused, or the link is incorrect."，說明 ID 錯誤或地圖尚未上線。如果顯示 "This map isn't allowed to render on this site. Please contact the map owner."，說明地圖只允許在其他域名顯示。

下一步：嵌入地圖說明如何限制地圖的顯示域名；已發佈地圖上的聊天可讓訪客無需金鑰即可聊天。

底圖​

完成後，你的網頁將顯示 Kaleidr 設計的現成互動底圖，無須安裝地圖程式庫，也不用自己編寫樣式。

1. 建立網頁​

保存為 basemap.html，將 kld_pk_live_… 替換為你的發佈金鑰。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>
  • style-id 指定底圖樣式。請始終填寫。kaleidr-morning 是通用樣式之一；其他樣式見 Tile。
  • center 採用 longitude,latitude 格式。設定 center 後再設定 zoom：單獨的 zoom 在沒有 center 時會被忽略。

2. 提供網頁服務​

打開 http://localhost:8000/basemap.html。

預期結果：

  • 底圖以曼哈頓中城為中心，高 480 像素。
  • “網路”標籤頁中，對 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 的請求傳回 200，隨後從 https://map-embed.kaleidr.com 加載 iframe。
  • 指標位於地圖上方時滾動即可縮放地圖。

如果沒有顯示內容，控制台對 …/sdk/sessions 報 CORS 錯誤，說明金鑰錯誤或你的來來源不在允許來來源清單中，與聊天方式的情況相同。

每個 Tile 工作階段都計入你所在組織每月地圖加載額度的一次加載。參閱配額與速率限制。

下一步：使用 Tile介紹運行時切換樣式與控制相機。

實際加載了甚麼​

三種方式使用的是相同的兩個組件：

  • Kaleidr.mount(target, options) 從 JavaScript 掛載產品，立即傳回句柄。產品程式碼在後台加載，產品就緒前對句柄發出的調用會被保留並在就緒後執行。
  • <kaleidr-map> 通過 HTML 完成同樣的工作。其屬性是帶連字符的掛載選項（share-id、style-id、publishable-key），但有兩個例外：enabled 對應 flag 屬性，聊天的 title 選項對應 chat-title 屬性。

在自己的地圖上使用 Chat 時，請調用 Kaleidr.mount，因為它需要實時地圖對象。其他產品可以使用任意一種方式。

所有產品的句柄都包含 destroy() 方法。其他方法取決於產品，例如 setCamera 可用於 viewer、tile 和 editor，但不支持 chat；在 Chat 中，助手會自行移動地圖，而你仍可使用地圖程式庫自己的相機方法。完整清單參閱元素 <kaleidr-map>。

現在需要瞭解的限制​

  • Chat 會添加自己的圖釘、路線和相機移動。 它不會修改你的圖層或標記，也不會向 Kaleidr 傳送這些內容；網頁不會收到面板事件。參閱功能和限制。
  • Viewer 和 Tile 在 iframe 中運行。 不能向它們添加自己的圖層或標記。需要自定義圖層時，請保留自己的地圖並連接 Chat。
  • Kaleidr 底圖通過 Tile 顯示。 不支持在你自己的地圖程式庫中直接加載 Kaleidr 樣式或圖磚。
  • SDK 用於網頁。 沒有 npm 軟件包或原生移動 SDK。後端應調用服務器 API。
  • 使用金鑰的掛載會消耗額度。 Chat 回答消耗組織的 AI 積分，每個 Tile 工作階段消耗一次地圖加載。參閱Kaleidr 的工作原理。

下一步選擇​

你想做甚麼閱讀
將 Chat 接入 Mapbox GL JS連接 Chat 與 Mapbox
將 Chat 接入 MapLibre GL JS連接 Chat 與 MapLibre
將 Chat 接入 Google Maps連接 Chat 與 Google Maps
將 Chat 接入 Leaflet連接 Chat 與 Leaflet
放置面板並匹配品牌色彩主題和佈局
讓訪客在已發佈地圖上聊天已發佈地圖上的聊天
嵌入地圖並限制域名嵌入地圖
顯示底圖並切換樣式使用 Tile
在網頁中放入地圖編輯器連接編輯器
在 React、Next.js 或 Vue 中使用 SDK框架集成
從後端調用 Kaleidr服務器快速入門
使用自己的業務資料生成回答你的資料
發佈到生產環境上線檢查清單