`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,
});

매개변수	유형	설명
`target`	CSS 선택자 또는 `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, chat	Viewer: 게시된 지도의 ID. 키가 없는 Chat: 지도 소유자가 채팅을 제공하는 게시된 지도.
`mapId`	문자열	없음	viewer	`shareId`가 없을 때 사용하는 `shareId`의 별칭.
`styleId`	문자열	조직의 기본 베이스맵	tile, editor	`kaleidr-morning` 같은 스타일 ID 또는 전체 스타일 URL.
`map`	실행 중인 지도 인스턴스	없음	chat	AI가 제어할 Mapbox GL JS, MapLibre GL JS, Google Maps 또는 Leaflet 지도 객체. 지원 지도 참조. 채팅만 사용할 경우 생략합니다.
`mapTarget`	CSS 선택자	없음	chat	제어할 Viewer 또는 Tile의 `<kaleidr-map>` 요소. `map` 대신 사용합니다.
`contained`	불리언	`false`	chat	패널을 위치와 크기가 지정된 마운트 대상 내부에 고정합니다. 기본값은 화면 왼쪽 위에 고정된 창입니다.
`lang`	문자열	페이지의 유효한 `<html lang>`, 아니면 영어	chat	`en`, `ko`, `pt-BR` 같은 BCP 47 응답 언어 태그. Chat 언어 참조.
`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, editor	Chat: CSS 사용자 지정 속성. 예: `{ '--highlight-color': '#0b5fff' }`. Editor: 17개 테마 키. JSON이 아닌 문자열은 경고 후 무시됩니다.
`enabled`	불리언	없음	전체	마운트별 활성화 게이트 설정. 마운트할 때만 읽습니다.
`base`	URL	`https://cdn.kaleidr.com`	전체	제품 번들의 출처. 출처만 사용하며 항상 그 출처의 `/embed/v1/`에서 로드합니다. 기본 주소 재정의에 허용된 출처만 사용하며 나머지는 경고 후 무시합니다.
`viewerBase`	URL	`https://map-embed.kaleidr.com`	viewer, tile	iframe 출처. 출처만 사용합니다.
`apiBase`	URL	`https://api.kaleidr.com/inference-api`	chat, editor, tile	세션 교환 및 제품 요청 대상. `/inference-api` 경로가 필수이며 출처만 지정하면 404입니다.
`tileBase`	URL	`https://tile.kaleidr.com`	editor	스타일 ID를 해석할 호스트.

참고:

apiKey는 더 이상 권장되지 않는 publishableKey의 별칭입니다.
네 가지 …Base 옵션은 다른 배포 환경 테스트용입니다. 운영 사이트에는 필요하지 않습니다. base는 번들만 옮기므로 지도 페이지, API, 베이스맵 호스트는 각각 바꾸지 않는 한 Kaleidr에 남습니다.
lang, title, placeholder는 마운트 시에 읽습니다. 변경하려면 파괴하고 다시 마운트하세요.
해당 제품이 사용하지 않는 옵션은 안내 없이 무시됩니다.

기본 주소 재정의

base(옵션 및 요소 속성)와 페이지 전역 window.__KALEIDR_EMBED_BASE__는 제품 번들을 불러올 출처를 지정합니다. 다음 중 하나일 때만 재정의가 적용됩니다:

허용되는 출처	예
Kaleidr CDN	`https://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;
}

모든 핸들에는 메서드가 전부 존재하지만 동작 여부는 제품에 따라 다릅니다:

메서드	chat	viewer	editor	tile
`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가 미지원인데 지도를 소유하지 않기 때문입니다. 다만 답변할 때 AI는 연결된 지도를 움직입니다. 직접 움직이려면 사용 중인 지도 라이브러리 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가 아무것도 로드하거나 전송하지 않고, 아무 동작도 하지 않는 핸들을 반환합니다. 방문자 동의를 기다리거나 HTML을 지우지 않고 임베드를 끌 때 사용하세요.

세 가지 제어

제어	적용 대상	설정 방법
페이지 플래그	페이지의 모든 마운트	보류할 마운트 전에 `window.__KALEIDR_EMBED_ENABLED__ = false` 설정
`Kaleidr.enable()`	호출 이후의 모든 마운트	`Kaleidr.enable(false)`
마운트별	하나의 마운트	`enabled: false` 옵션 또는 `flag="false"` 속성

마운트 결정 방법

마운트할 때마다 SDK는 세 가지 제어를 모두 읽습니다:

하나라도 명시적으로 false면 마운트를 보류합니다.
그렇지 않고 하나라도 명시적으로 true면 마운트합니다.
그 외에는 켜진 기본값을 따릅니다.

중요한 결과 세 가지:

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__`	`true`	`false`	실제 불리언이 아닌 모든 값. 문자열 `"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는 코드에 준비 완료나 실패 신호를 주지 않습니다. 확인할 수 있는 것은:

제품	로딩 성공	실패
viewer	iframe이 `kaleidr-embed:ready` 전송.	iframe이 `kaleidr-embed:error` 전송 또는 콘솔의 `[kaleidr:viewer]` 오류.
tile	iframe이 `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가 없거나 잘못됨	`[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" 세션 교환이 성공하면 지도 로드 1회가 계산됩니다. 코드는 오류에 설명되어 있습니다.

첫 세션 교환이 실패한 마운트는 재시도하지 않습니다. 원인을 해결하고 다시 마운트하세요.

세션 교환 요약

Chat, Editor, Tile에서 SDK는 게시 가능 키를 런타임 API 호출에 직접 쓰지 않고 먼저 세션으로 교환합니다.

마운트 시 SDK는 POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions에 헤더 x-api-key: <your publishable key>와 본문 {"product":"<product>"}로 요청합니다. 브라우저가 페이지 Origin을 추가합니다.
Kaleidr는 순서대로 키가 게시 가능인지, 출처가 있는지, 허용 출처 목록이 있다면 일치하는지, 키와 요금제에서 제품을 허용하는지, 필요한 스코프가 있는지 확인합니다. Chat은 ai, Editor는 design, Tile은 maps, Viewer는 필요 없습니다.
응답은 {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …}입니다. basemap_style_id는 조직의 기본 베이스맵이며 없으면 null입니다.
제품은 출처와 제품에 묶인 세션 토큰으로 요청합니다.
SDK는 만료 90초 전, 또는 백그라운드 탭 복귀 시 세션 만료가 임박했으면 갱신합니다. 실패하면 마운트가 존재하는 동안 30초마다 재시도합니다.
handle.destroy()는 갱신을 중지합니다.

Viewer에는 세션이 필요 없습니다. 키 없이 shareId로 마운트한 게시 지도 Chat은 키 대신 지도에서 세션을 얻습니다. 게시 지도에서의 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를 사용하세요.

스크립트 불러오기​

window.Kaleidr​

Kaleidr.mount(target, options)​

옵션​

기본 주소 재정의​

핸들​

Kaleidr.init()​

활성화 게이트​

세 가지 제어​

마운트 결정 방법​

허용되는 값​

예시: 동의할 때까지 임베드 보류하기​

페이지 전역 변수​

마운트 성공 확인​

마운트 실패 시​

세션 교환 요약​

기타 콘솔 메시지​

제공되지 않는 기능​

관련 페이지​