kaleidr.js — loader

하나의 script 태그가 window.Kaleidr를 설치하고 <kaleidr-map> 요소를 정의합니다:

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

이 façade는 가벼운 loader입니다. version, config, script loading, product registry, key passing, doorway selection, mount lifecycle, error normalization, dormancy flag만 담당합니다. 각 product의 실제 동작은 자체 bundle에 있으며 처음 사용할 때 URL에서 지연 로드됩니다.

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

product bundle이 백그라운드에서 로드되는 동안에도 handle을 동기적으로 반환합니다. 로드 전에 발생한 호출은 대기열에 저장되고 준비가 완료되면 실행됩니다.

옵션

옵션	유형	설명
product	'chat' | 'viewer' | 'editor' | 'tile'	필수. bundle + 기본 doorway를 선택합니다.
publishableKey	string	Publishable browser key (kld_pk_live_…). chat/editor/tile에 필요하며, viewer에는 키를 전달하면 안 됩니다. 전달 시 product_not_allowed로 거부됩니다. SDK는 런타임에 키를 단기 origin-bound session으로 교환합니다.
apiKey	string	publishableKey의 사용 중단된 alias. 레거시 kld_live_… 키도 허용합니다.
shareId / mapId	string	Viewer 전용. 필수 — 생략하면 bundle 로드 시 오류가 발생합니다.
styleId	string	Tile/editor. Tile: Kaleidr 베이스맵 style id(viewer의 canvas default가 기본값). Editor: style id 또는 전체 style URL — 생략 시 조직에 저장된 default가 적용되고, 그다음 kaleidr-morning이 적용됩니다.
map	map instance	Chat: 연결할 페이지 내 활성 Mapbox / MapLibre / Google 지도.
mapTarget	string	Chat: host map element의 CSS selector(선언형 경로).
contained	boolean	Chat 전용. 기본값 false. 패널을 document.body 위에 띄우는 대신 mount element 안에 고정합니다 — 없으면 패널이 레이아웃 밖으로 나가 깨진 것처럼 보입니다.
center zoom		초기 카메라(viewer, editor, tile).
pitch bearing		viewer, editor, tile의 초기 카메라.
theme	object or JSON object string	CSS-token 모음(예: { '--kd-accent': '#2da84a' }). Chat은 handle을 통한 실시간 업데이트도 지원합니다. 이름이 지정된 문자열 theme은 지원되지 않으며, 단순 문자열을 전달하면 경고가 기록되고 무시됩니다.
doorway	'iframe' | 'attach'	우회 옵션 — product 기본값을 재정의합니다.
base	string	bundle이 로드되는 CDN origin을 재정의합니다(dev / self-host).
viewerBase	string	Viewer/tile: iframe이 로드하는 origin. base와 별개이며 iframe은 CDN을 대상으로 하지 않습니다.
tileBase	string	Editor: 카탈로그 styleId 값을 해석하는 tile CDN. 기본값 https://tile.kaleidr.com.
apiBase	string	service path를 포함해야 합니다. 기본값 https://api.kaleidr.com/inference-api; https://api.kaleidr.com 같은 bare origin은 session exchange에서 404를 반환합니다. chat, editor, tile — session exchange를 수행하는 모든 product에 적용됩니다.
enabled	boolean	mount별 dormancy 재정의.

KaleidrHandle

handle 형태는 superset입니다 — 각 product는 지원 가능한 method만 구현합니다. 각 product에서 어떤 method가 어떤 역할을 하는지는 Handle matrix를 참조하세요.

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

현재 지원되지 않는 method를 호출하면 [kaleidr] 경고가 기록되고 반환됩니다 — loader는 예외를 발생시키지 않습니다. 이 동작은 v1 major alias의 contract입니다.

Kaleidr.init()

DOM에 이미 존재하는 모든 <kaleidr-map>을 upgrade합니다. 로드 시 자동으로 호출됩니다. 요소를 동적으로 추가한 경우 이후에 호출하세요.

Kaleidr.enable(on = true)

SDK는 기본적으로 활성화되어 있습니다 — 따로 enable할 필요가 없으며 quickstart는 작성된 그대로 동작합니다.

enable()은 끄기 스위치로 존재합니다. false를 전달하면 mount()가 어떤 bundle도 로드하지 않으므로 embed를 동의 배너 뒤에 두거나 markup을 제거하지 않고 페이지에서 비활성화할 수 있습니다. 동일한 스위치는 window.__KALEIDR_EMBED_ENABLED__ = false(script 실행 전) 또는 mount별 flag 속성 / enabled 옵션으로도 사용할 수 있습니다.

Kaleidr.version

loader version string.

CDN base 재정의

로컬 개발 또는 self-hosting의 경우 loader를 다른 origin으로 지정하세요:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>