<kaleidr-map> — 요소
선언형 façade입니다. 요소를 배치하고 속성을 설정하면 connect 시 마운트되고 제거 시 해제됩니다.
<kaleidr-map product="viewer" share-id="abcd1234" style="height:480px"></kaleidr-map>
속성 표
kaleidr-sdk/packages/embed/src/element.ts를 기준으로 검증되었습니다. 속성 이름은
kebab-case이며, kaleidr.js의 대응하는 Kaleidr.mount(...) 옵션 이름은
camelCase입니다.
| 속성 | 제품 | 필수 | 기본값 | 의미 |
|---|---|---|---|---|
product | 전체 | 예 | — | chat | viewer | editor | tile |
publishable-key | chat, editor, tile | 예* | — | kld_pk_live_…; 런타임에 session token으로 교환됨 |
api-key | chat, editor, tile | — | — | 사용 중단된 alias; 레거시 kld_live_…도 허용 |
share-id | viewer | 예 | — | 게시된 map / share id; 생략하면 bundle 로드 시 오류 발생 |
map-id | viewer | — | — | share-id의 alias |
style-id | tile, editor | 선택 | tile: viewer default; editor: org default → kaleidr-morning | Basemap style id 또는 (editor) 전체 style URL |
map-target | chat | 선택 | — | host map element의 CSS selector |
contained | chat | 선택 | false | 패널을 document.body 위에 띄우는 대신 mount element 안에 고정 |
center | viewer, tile, editor | 선택 | — | lon,lat |
zoom | viewer, tile, editor | 선택 | editor: 2 | 초기 zoom |
pitch | viewer, tile, editor | 선택 | 0 | 초기 pitch |
bearing | viewer, tile, editor | 선택 | 0 | 초기 bearing |
theme | chat, editor | 선택 | — | JSON CSS-token object string |
doorway | 전체 | 선택 | product default | iframe | attach 재정의 |
base | 전체 | 선택 | https://cdn.kaleidr.com | lazy bundle(/embed/v1/*.js)용 CDN origin |
viewer-base | viewer, tile | 선택 | https://map-embed.kaleidr.com | iframe이 로드하는 origin — bundle CDN과 별개 |
api-base | chat, editor, tile | 선택 | https://api.kaleidr.com/inference-api | /inference-api를 포함해야 합니다. https://api.kaleidr.com 같은 bare origin은 session exchange에서 404를 반환합니다. session exchange를 수행하는 모든 product(chat, editor, tile)에 적용됩니다. |
tile-base | editor | 선택 | https://tile.kaleidr.com | 카탈로그 style-id 값을 해석하는 Tile CDN |
flag | 전체 | 선택 | — | 요소별 dormancy 재정의 |
* 인증/과금 사용에 필수입니다. Viewer에는 키가 필요 없 으며 Viewer embed에
키를 전달하면 product_not_allowed로 거부됩니다.
요소에 높이를 지정하세요(inline style 또는 CSS). 모든 product는
container를 채우며, 크기가 지정되지 않은 container 안의 iframe product는
표시 상태를 유지하기 위해 고정 500px로 대체됩니다.
Handle matrix
/embed/v1/에 배포된 그대로의 동작입니다. 지원되지 않는 조합은 오류를 발생시키지 않으며,
SDK는 [kaleidr] 경고를 기록하고 반환합니다. 이는 v1 major alias의 contract이며,
호출 가능한 method를 제거하면 behavior breaking 변경이 됩니다.
| Method | chat | viewer | editor | tile |
|---|---|---|---|---|
destroy() | 예 | 예 | 예 | 예 |
setCamera(camera) | no-op | 예 | 예 | 예 |
setTheme(theme) | 예 (live) | n/a | mount 시에만 | n/a |
setStyle(styleId) | n/a | n/a | n/a | tile에서만 노출 |
Chat은 지도 카메라를 제어하지 않습니다 — Kaleidr.mount(...) 후에는
지도 인스턴스 자체의 camera API를 사용하세요. Editor의 live-setTheme은 후속 SDK
릴리스에서 제공되며, mount 시 theme은 이미 작동합니다.
실시간 업데이트
center, zoom, pitch, bearing이 관찰되며 remount 없이 viewer,
editor, tile을 다시 프레이밍합니다. theme 변경은 chat에 실시간 반영되며,
editor theme은 mount 시점에만 적용됩니다.
Chat + map-target
Chat은 활성 지도에 연결되며, 문자열 속성으로는 map instance를 전달할 수 없습니다. 이를 제공하는 방법은 두 가지입니다:
- Imperative(권장):
Kaleidr.mount(el, { product: 'chat', publishableKey, map, contained: true }). - Declarative: host element에 map instance를
hostEl.__kaleidrMap__ = map으로 저장한 후map-target="#host"를 지정합니다.
지도 없이 chat을 실행하면 headless 모드로 동작합니다(지도 상호작용 없음).