跳至主要内容

kaleidr.js 載入器

kaleidr.js 是所有 Kaleidr 嵌入功能的入口腳本。它定義全局對象 window.Kaleidr 和自定義元素 <kaleidr-map>。腳本體積小，不包含地圖程式庫或產品程式碼。掛載產品時，它從同一 CDN 載入該產品的包並傳入選項。

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

沒有 npm 包。SDK 只能通過 script 標籤載入。React、Next.js、Vue 和 TypeScript 用法請參閱框架集成。

載入腳本​

問題答案
標籤放在哪裡？任意位置。<kaleidr-map> 元素無論位於標籤前後都能掛載。
何時調用 Kaleidr.mount？腳本執行後。對於普通 <script src> 標籤，頁面中後續腳本即可調用。
能使用 async 或 defer 嗎？元素可以。調用 Kaleidr.mount 時須等待標籤的 load 事件，因為此前 window.Kaleidr 尚未定義。
載入幾次？每頁一次。
能添加 integrity 嗎？不能。檔案會在原路徑更新，固定哈希將在下一次發佈時失效。參見 CDN 版本管理。
能在伺服器上運行嗎？不能，需要 window 和 document。服務端渲染的應用程式應僅在瀏覽器中載入。

使用 async 載入腳本，並在載入後掛載：

<div id="map" style="height:480px"></div>
<script>
  const s = document.createElement('script');
  s.src = 'https://cdn.kaleidr.com/embed/v1/kaleidr.js';
  s.async = true;
  s.onload = () => {
    Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });
  };
  document.head.appendChild(s);
</script>

window.Kaleidr​

成員說明
Kaleidr.mount(target, options)將產品掛載到元素中並返回操作句柄。
Kaleidr.init()初始化文檔中已有的 <kaleidr-map> 元素，通常無需手動調用。
Kaleidr.enable(on)開啓或關閉後續掛載。
Kaleidr.version載入器版本字串，用於診斷。

Kaleidr.mount(target, options)​

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
  contained: true,
});
參數類型說明
targetCSS 選擇器或 HTMLElement掛載目標。選擇器通過 document.querySelector 僅解析一次。
options對象必填。參見選項。

返回一個操作句柄。

運行行為：

  • 立即返回。 會話交換和產品包載入在後台進行。此期間的句柄調用會排隊，在產品就緒後依次執行。對於 Viewer 和 Tile，就是 iframe 內地圖回報就緒之時，因此能在調用 setCamera 之前執行 mount，下一行的設置仍有效。
  • 掛載失敗不會拋異常。 找不到目標、載入包失敗、會話被拒絕或 ID 無效時，控制台記錄含 [kaleidr:<product>] 的錯誤。仍會返回句柄，但其方法不執行操作。唯一會拋異常的是缺少選項對象的 Kaleidr.mount('#map')，它會拋出 TypeError。
  • 不向程式碼反饋結果。 沒有可等待的 Promise 或回調。參見判斷掛載是否成功。
  • 每個目標只允許一個掛載。 再次掛載前先調用原句柄的 handle.destroy()。即使首次掛載尚在載入，銷毀後在同一元素重新掛載也安全；已銷毀的掛載不會干擾新掛載。

選項​

選項類型預設值適用產品說明
product'chat' | 'viewer' | 'editor' | 'tile'無，必填全部選擇掛載的產品。
publishableKey字串無chat、editor、tile可發佈金鑰 kld_pk_…。SDK 將其交換為短期會話，僅把會話交給產品。不要傳給 Viewer。伺服器金鑰 (kld_sk_…) 會在請求發送前被拒絕。
shareId字串無viewer、chatViewer：已發佈地圖的 ID。無金鑰的 Chat：由地圖所有者提供聊天服務的已發佈地圖。
mapId字串無viewershareId 的別名，僅在沒有 shareId 時使用。
styleId字串組織的預設底圖tile、editor例如 kaleidr-morning 的樣式 ID，或完整樣式 URL。
map運行中的地圖實例無chat供助手操控的地圖：Mapbox GL JS、MapLibre GL JS、Google Maps 或 Leaflet。參見支持的地圖。純聊天面板可省略。
mapTargetCSS 選擇器無chat供助手操作的 Viewer/Tile <kaleidr-map> 元素，用來代替 map。
contained布爾值falsechat將面板停靠到有定位和尺寸的目標內部。預設是在視口左上角的固定懸浮窗口。
lang字串頁面有效的 <html lang>，否則英語chat回答語言，使用 BCP 47 標籤，如 en、ko 或 pt-BR。參見聊天語言。
title字串面板自身標題chat面板標題欄的文本，元素屬性為 chat-title。
placeholder字串面板自身佔位文字chat輸入框佔位提示。
center[longitude, latitude]產品預設值viewer、tile、editor初始中心點。
zoom數值產品預設值viewer、tile、editor初始縮放級別。Viewer/Tile 只有和 center 同時提供才生效。
pitch數值產品預設值viewer、tile、editor初始傾斜角（度）。
bearing數值產品預設值viewer、tile、editor初始旋轉角（度）。
theme對象或對象的 JSON 字串無chat、editorChat：自定義 CSS 屬性，如 { '--highlight-color': '#0b5fff' }。Editor：參閱 17 個主題鍵。非 JSON 字串會被忽略並警告。
enabled布爾值無全部每次掛載獨立控制的啓用開關，僅在掛載時讀取。
baseURLhttps://cdn.kaleidr.com全部產品包來源。只採用源站，並始終從其 /embed/v1/ 載入。只有基礎地址覆蓋規則允許的源站才生效；其他值會被忽略並警告。
viewerBaseURLhttps://map-embed.kaleidr.comviewer、tileiframe 的來源，只使用源站。
apiBaseURLhttps://api.kaleidr.com/inference-apichat、editor、tile會話交換和產品請求的 API 地址，必須含 /inference-api；只填寫源站會返回 404。
tileBaseURLhttps://tile.kaleidr.comeditor解析樣式 ID 的主機。

註意：

  • apiKey 是 publishableKey 已棄用的別名。
  • 四種 …Base 選項用於測試其他部署，生產環境通常不需要。base 只改變包的來源；地圖頁面、API 和底圖主機仍使用 Kaleidr 地址，除非分別覆蓋。
  • lang、title 和 placeholder 在掛載時讀取，更改它們需要銷毀並重新掛載。
  • 產品不使用的選項會靜默忽略。

基礎地址覆蓋規則​

base（選項和元素屬性）以及頁面全局變量 window.__KALEIDR_EMBED_BASE__ 用於指定產品包的來源。覆蓋只在來源屬於下列之一時有效：

允許的源站示例
Kaleidr CDNhttps://cdn.kaleidr.com
載入 kaleidr.js 的源站kaleidr.js 從 https://static.example.com 載入，且 base 為 https://static.example.com。
當前頁面的源站頁面在 https://www.example.com/…，且 base 為 https://www.example.com。

其他值均被忽略。掛載仍繼續，包從預設 CDN 載入，同時控制台顯示一條警告：

[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.

頁面全局變量必須是字串，其他類型會被靜默跳過。若載入器與包從同一源站提供，自行托管也遵循此規則。

各產品預設攝像機設置：

產品預設視角
viewer地圖作者保存的視圖。
tile樣式預設視圖，否則顯示全球。
editor中心 [0, 0]，縮放 2，傾斜 0，旋轉 0。
chat不適用，Chat 不建立地圖。

詳細說明見各產品頁面：Chat、Viewer、Tile、Editor。

操作句柄​

Kaleidr.mount 對所有產品返回結構相同的句柄。

interface KaleidrHandle {
  readonly product: 'chat' | 'viewer' | 'editor' | 'tile';
  setCamera(camera: {
    center?: [number, number]; // [longitude, latitude]
    zoom?: number;
    pitch?: number;
    bearing?: number;
    duration?: number;         // milliseconds
  }): void;
  setTheme(theme: string | Record<string, string>): void;
  setStyle(style: string): void;
  destroy(): void;
}

每個句柄都有全部方法，但具體效果因產品而異：

方法chatviewereditortile
setCamera(camera)警告是是是
setTheme(theme)是警告警告警告
setStyle(style)警告警告警告是
destroy()是是是是

“警告”表示調用無效，並在控制台顯示提示。

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

這是 /embed/v1 協議的一部分：不支持的方法不會拋異常。

方法說明：

  • setCamera：未提供的字段保持原值。duration 指定動畫時長；省略或設為 0 則立即跳轉。Chat 不支持 setCamera，因為它不擁有地圖，但助手回答時仍會移動所連接的地圖。若需主動移動，請調用地圖程式庫自己的 API。
  • setTheme：僅 Chat。接收自定義 CSS 屬性對象或其 JSON 字串。
  • setStyle：僅 Tile。接收樣式 ID 或 URL。
  • destroy：移除掛載內容、停止會話續期並清空等待中的調用。重復調用無害。銷毀的句柄不能重用，須重新掛載。

調用 mount 後可立即使用句柄。 對 Viewer 和 Tile，地圖 iframe 就緒前的 setCamera（Tile 還有 setStyle）調用會按順序緩存，待地圖發出 kaleidr-embed:ready 或首次攝像機位置後執行，最多保留最近 256 次。若 iframe 載入後經過有限等待（通常 10 秒）仍未就緒，緩存的調用仍會發送，並顯示一次警告：

[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. The frame may be showing an error (an unpublished map, a blocked request).

等待從 iframe 實際載入時開始。視口外尚未載入的 iframe 會繼續保留調用。因此無需等待 kaleidr-embed:ready 才能操作句柄。該消息和 kaleidr-embed:error 仍用於判斷成功與否，見 Viewer 消息。

句柄沒有 ready Promise、on() 方法，也沒有 map 或 iframe 成員。

Kaleidr.init()​

初始化調用時文檔中所有 <kaleidr-map> 元素。載入器會自動調用；後續插入的元素也會自行掛載，因此很少需要手動調用。重復調用無害。

啓用開關​

嵌入預設啓用。開關關閉時，Kaleidr.mount 不載入、不發送任何資料，且返回方法均無效的句柄。可用於等待訪客同意，或無需修改標記就暫時禁用嵌入。

三種控制方式​

控制作用範圍設置方式
頁面標誌當前頁面的所有掛載在希望阻止的掛載之前設置 window.__KALEIDR_EMBED_ENABLED__ = false
Kaleidr.enable()調用後的所有掛載Kaleidr.enable(false)
單次掛載一個掛載選項 enabled: false 或屬性 flag="false"

如何決定是否掛載​

每次掛載時，SDK 都讀取全部三個控制：

  1. 任一個明確為 false，就阻止掛載。
  2. 否則，只要有一個明確為 true，就繼續掛載。
  3. 否則採用預設開啓狀態。

這會產生三個重要結果：

  • false 只能通過設置它的控制方式解除。 Kaleidr.enable(true) 無法解除單次掛載的 enabled: false，也無法解除設為 false 的頁面標誌。各控制不能相互覆蓋。
  • 僅在掛載時檢查。 解除開關不會自動啓動此前被阻止的掛載，之後關閉開關也不會卸載現有產品。解除後須重新調用 Kaleidr.mount，或移除並重新插入元素。
  • 頁面標誌在每次掛載時讀取，不只是腳本載入時。因此稍後設置會影響下一次掛載。
阻止來源解除方法
window.__KALEIDR_EMBED_ENABLED__ = false將它設為 true 或刪除。
Kaleidr.enable(false)調用 Kaleidr.enable(true)，或以 Kaleidr.enable(null) 恢復預設值。
enabled: false 或 flag="false"不帶該設置重新掛載。修改已掛載元素的 flag 屬性無效。

被阻止時，控制台只顯示一條指出控制來源的警告：

[kaleidr] embed is disabled — window.__KALEIDR_EMBED_ENABLED__ is false. Reassigning it releases that lever — Kaleidr.enable() cannot.

可接受的值​

控制值嚴格按布爾規則解釋，以免意外的字串錯誤地啓用嵌入。

控制視作 true視作 false忽略並警告
window.__KALEIDR_EMBED_ENABLED__truefalse任何非真正布爾值，包括字串 "true" 和 "false"
Kaleidr.enable(x)無參數、true、"true"、"1"、"yes"、"on"false、0、""、"false"、"0"、"no"、"off"其他字串、undefined、對象、函數
enabled 選項true、"true"、"1"、"yes"、"on"false、0、""、"false"、"0"、"no"、"off"其他字串、對象、函數
flag 屬性無值的 flag、"true"、"1"、"yes"、"on""false"、"0"、"no"、"off"任何其他值

比較時忽略大小寫和首尾空格。從存儲中讀取時有兩個註意事項：

  • Kaleidr.enable(null) 會重置為預設狀態，不表示“沒有意見”。沒有保存值時，localStorage.getItem(key) 返回 null，這恰是訪客尚未同意時的狀態，所以不要直接傳入存儲值，先比較：Kaleidr.enable(stored === 'true')。
  • 被忽略的值保持控制原有狀態，既不啓用也不禁用。

示例：取得同意前阻止嵌入​

本頁用頁面標誌阻止所有嵌入；它適用於載入器運行時自動掛載的元素。訪客同意後，通過同一標誌解除阻止，再將元素重新插入以觸發掛載。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Consent-gated map</title>
  <script>
    // A real boolean, set before the loader. A stored string is compared, never passed through.
    window.__KALEIDR_EMBED_ENABLED__ =
      localStorage.getItem('embeds-consent') === 'true';
  </script>
  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
</head>
<body>
  <div id="banner">
    This page shows an interactive map from Kaleidr.
    <button id="accept">Show the map</button>
  </div>

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

  <script>
    const banner = document.getElementById('banner');
    if (window.__KALEIDR_EMBED_ENABLED__) banner.hidden = true;

    document.getElementById('accept').addEventListener('click', () => {
      localStorage.setItem('embeds-consent', 'true');
      banner.hidden = true;

      // 1. Release the lever that held the embeds.
      window.__KALEIDR_EMBED_ENABLED__ = true;

      // 2. A held element does not mount by itself. Re-insert each one.
      document.querySelectorAll('kaleidr-map').forEach((el) => {
        const parent = el.parentNode;
        const next = el.nextSibling;
        el.remove();
        parent.insertBefore(el, next);
      });
    });
  </script>
</body>
</html>

同意前，“網路”面板只會顯示 kaleidr.js，不會有其他 Kaleidr 產品包、會話請求或 iframe。

如果通過 JavaScript 掛載，則不必使用開關：取得同意前不要調用 Kaleidr.mount。開關主要適合直接寫在 HTML 中的元素，或標籤管理器、其他團隊程式碼會調用 mount 而你需要控制整頁的情況：

Kaleidr.enable(false);            // hold every later mount
// …
Kaleidr.enable(true);             // release it
const handle = Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });

頁面全局變量​

全局變量類型讀取時間用途
window.__KALEIDR_EMBED_ENABLED__布爾值每次掛載啓用開關的頁面標誌。
window.__KALEIDR_EMBED_BASE__URL 字串每次掛載自行托管時的產品包來源。只使用源站，且必須滿足基礎地址覆蓋規則。參見 CDN 版本管理。

判斷掛載是否成功​

SDK 不向程式碼提供就緒或失敗信號，但可以觀察：

產品已載入失敗
vieweriframe 發送 kaleidr-embed:ready。iframe 發送 kaleidr-embed:error，或控制台出現 [kaleidr:viewer] 錯誤。
tileiframe 發送 kaleidr-embed:ready。會話被拒只在控制台顯示；繪制失敗發送 kaleidr-embed:error。
chat無信號，面板出現在頁面中。僅控制台。
editor無信號，編輯器出現在頁面中。僅控制台。

這兩種消息在 Viewer 消息中有說明。

掛載失敗時的情況​

原因表現發送請求？
選擇器找不到目標[kaleidr:<product>] mount target not found: <selector>否
元素缺少有效 product[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"否
傳入伺服器金鑰[kaleidr:<product>] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.否
金鑰未知、被撤銷或頁面來源不允許瀏覽器對 sessions 報 CORS 錯誤，隨後 [kaleidr:<product>] 請求失敗；沒有內容顯示。是
缺少權限範圍、產品限制或套餐不支持[kaleidr:<product>] kaleidr session exchange failed (403)；無內容。是
地圖載入額度耗盡（tile）或會話請求過多[kaleidr:<product>] kaleidr session exchange failed (429)；無內容。是
產品包無法載入[kaleidr:<product>] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/<product>.js不適用
Viewer 缺少 ID 或 ID 格式錯誤[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.否
Editor 缺少金鑰[kaleidr:editor] [editor-embed] attach() requires an { apiKey }否
Chat 既沒有金鑰也沒有 shareId面板仍會顯示，但每個問題均失敗。掛載時不發送
啓用開關關閉[kaleidr] embed is disabled — …否

SDK 不顯示伺服器給出的具體原因。 會話被拒時僅記錄 HTTP 狀態。原因在響應正文：403/404 的程式碼在 detail 字段，如 {"detail":"insufficient_scope"}；429 的程式碼在 error 字段，並有 detail 解釋。例外是 map_load_quota_exceeded，程式碼在 detail。在“網路”面板選擇 sessions 請求查看響應；若被 CORS 隱藏，請在終端重現請求：

curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "x-api-key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "content-type: application/json" \
  -d '{"product":"chat"}'
HTTP/2 403
content-type: application/json

{"detail":"origin_not_allowed"}

使用出錯頁面的實際來源。測試時用 "chat"、"editor" 或 "viewer"；成功的 "tile" 交換會計入一次地圖載入。所有程式碼詳見錯誤。

首次會話交換失敗後，該掛載不會自動重試。修復原因後重新掛載。

會話交換概要​

對於 Chat、Editor 和 Tile，SDK 不會用可發佈金鑰直接調用運行時 API，而是先將它換成會話。

  1. 掛載時，SDK 向 POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 發送請求，攜帶請求頭 x-api-key: <your publishable key> 和正文 {"product":"<product>"}。瀏覽器添加頁面 Origin。
  2. Kaleidr 依次驗證：金鑰是否可發佈；請求是否有來源；如設有允許來源列表，來源是否匹配；金鑰和組織套餐是否允許產品；金鑰是否含必要的權限範圍：Chat 用 ai，Editor 用 design，Tile 用 maps，Viewer 不需要。
  3. 響應為 {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …}。basemap_style_id 是組織的預設底圖，沒有則為 null。
  4. 產品在請求中使用綁定了來源與產品的會話令牌。
  5. SDK 在會話到期前 90 秒續期；後台分頁重新顯示且會話即將到期時也續期。續期失敗則在掛載期間每 30 秒重試。
  6. handle.destroy() 停止續期。

Viewer 不需要會話。使用 shareId 且不提供金鑰的已發佈地圖 Chat，從地圖本身而非金鑰獲取會話。參見已發佈地圖上的聊天。

請求和響應詳見端點。金鑰類型、會話及來源白名單的保護範圍與局限，請參閱安全模型。

其他控制台消息​

消息含義
[kaleidr] <method>() is not supported on product "<product>" — the call is a no-op. …調用了該產品不支持的句柄方法。
[kaleidr] <method>() IS supported on product "<product>", but this mount did not expose it, so the call did nothing. …瀏覽器緩存中的產品包比載入器舊，請繞過緩存重新載入。
[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. …Viewer/Tile 地圖未在句柄規定的等待時間內就緒，緩存的 setCamera、setStyle 已發送，可能無地圖接收；請監聽 kaleidr-embed:error。
[kaleidr] theme must be an object of CSS tokens, not an array; ignored.theme 是陣列。
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.theme 字串不是以 { 開頭。
[kaleidr] theme JSON parse failed (…); ignored.theme 是格式錯誤的 JSON。
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. …flag 或 contained 的值無法識別；消息中會指明 flag="…" 或 contained="…"。
[kaleidr] base "<value>" is IGNORED — bundles load from <origin>. …base 或 window.__KALEIDR_EMBED_BASE__ 指定的來源不符合基礎地址覆蓋規則，因此使用預設 CDN。
[kaleidr] window.__KALEIDR_EMBED_ENABLED__ must be a boolean; got <type> (…). …頁面標誌不是布爾值，被忽略。
[kaleidr] Kaleidr.enable(): "<value>" is not a recognized boolean — the value is IGNORED. …Kaleidr.enable 收到無效值。
[kaleidr] enabled: "<value>" is not a recognized boolean — the value is IGNORED. …enabled 掛載選項收到無效值。
[kaleidr] Kaleidr.enable(undefined) is IGNORED and leaves the gate exactly as it was. …Kaleidr.enable 收到 undefined，開關狀態不變。
[kaleidr] Kaleidr.enable(null) RESET the gate to the build default, releasing the <value> set earlier. …Kaleidr.enable(null) 清除了之前的設置並恢復預設狀態。

尚不提供​

  • npm 包、ES 模塊版本或自帶類型定義；可從框架集成複製聲明。
  • iOS、Android、React Native 或 Flutter 原生 SDK。
  • 句柄上的 ready Promise、事件或回調。
  • 不掛載產品即可調用 API 的 JavaScript 客戶端；請在後端使用伺服器 API。

相關頁面​