<kaleidr-map> 요소

<kaleidr-map>는 Kaleidr 제품을 선언적으로 마운트하는 방식입니다. HTML에 속성과 함께 요소를 작성하면 문서에 추가될 때 자동으로 마운트되고 제거될 때 해제됩니다. 이 요소는 kaleidr.js에서 정의하므로 해당 스크립트를 페이지에 로드해야 합니다.

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

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

이 요소는 속성을 옵션으로 바꾸어 자기 자신에 Kaleidr.mount를 호출하는 얇은 래퍼입니다. 요소가 하는 일은 모두 Kaleidr.mount로 할 수 있지만 그 반대는 아닙니다. 요소는 실행 중인 지도 객체를 전달받을 수 없으며 핸들을 반환하지 않습니다.

요소를 사용할 때	Kaleidr.mount를 사용할 때
임베드가 정적 HTML 마크업인 경우	setCamera, setStyle, setTheme, destroy를 사용할 핸들이 필요한 경우
CMS나 템플릿이 HTML을 생성하는 경우	자체 지도에 Chat을 붙이기 위해 map 옵션이 필요한 경우
문서에서 요소를 제거하면 자동으로 정리되기를 원하는 경우	프레임워크가 마운트와 언마운트를 제어하는 경우

속성

속성 이름은 kebab-case이고 해당 마운트 옵션은 camelCase입니다.

속성	마운트 옵션	제품	필수	기본값	마운트 후 감시	설명
product	product	전체	예	없음	아니요	chat, viewer, editor, tile 중 하나입니다.
publishable-key	publishableKey	chat, editor, tile	예. 게시된 지도에서 Chat을 쓰는 경우 제외	없음	아니요	kld_pk_… 키입니다. Viewer에서는 사용하지 않습니다.
share-id	shareId	viewer, chat	viewer: 예	없음	아니요	Viewer는 게시된 지도 ID입니다. 키 없는 Chat은 대화를 제공할 게시된 지도입니다.
map-id	mapId	viewer	아니요	없음	아니요	share-id의 별칭입니다.
style-id	styleId	tile, editor	tile에 권장	조직의 기본 베이스맵; editor에서는 없으면 kaleidr-morning	아니요	베이스맵 스타일 ID 또는 스타일 URL입니다.
map-target	mapTarget	chat	아니요	없음	아니요	AI가 제어할 <kaleidr-map> Viewer 또는 Tile 요소를 지정하는 CSS 선택자입니다.
contained	contained	chat	아니요	꺼짐	아니요	패널을 요소 안에 배치합니다. 요소에 위치 지정과 크기가 필요합니다.
lang	lang	chat	아니요	유효한 <html lang> 값, 아니면 영어	아니요	en, ko, pt-BR 같은 BCP 47 응답 언어입니다. Chat 언어를 참고하세요.
chat-title	title	chat	아니요	패널 기본 제목	아니요	머리글 제목입니다. 속성은 chat-title이지 title이 아닙니다. HTML의 title은 마우스를 올릴 때 나오는 도움말입니다.
placeholder	placeholder	chat	아니요	패널 기본 안내 문구	아니요	입력란에 표시할 자리표시자 텍스트입니다.
layout	layout	viewer	아니요	map	아니요	bar는 채팅 바를 마운트합니다. 채팅 바도 chat-title, placeholder, theme, lang을 읽지만 기본값은 따로 있습니다. Viewer 옵션을 참고하세요. locator와 listings는 장소 라이브러리 컬렉션 목록 옆에 지도를 표시합니다. 장소 레이아웃을 참고하세요. guide는 시설 지도 옆에 채팅을 엽니다. 가이드 레이아웃을 참고하세요. live는 차량과 오늘의 정류장을 표시합니다. 실시간 레이아웃을 참고하세요.
collection	collection	viewer 매장 찾기, 매물 목록, 가이드, 실시간	아니요	지도가 그리는 레이아웃 유형의 첫 번째 컬렉션	아니요	목록에 표시할 컬렉션의 ID입니다. live에서는 차량 컬렉션의 ID입니다.
stops	stops	viewer 실시간	아니요	지도가 그리는 첫 번째 정류장 컬렉션	아니요	정류장 컬렉션의 ID입니다.
filters	filters	viewer 매장 찾기 및 매물 목록	아니요	컬렉션의 모든 필터	아니요	|로 구분한 표시할 방문자 필터: search, category, price, beds, baths, open_now.
card	card	viewer	아니요	auto	아니요	compact 장소 카드는 제목, 부제목, 작업만 표시합니다.
prompt	prompt	viewer	아니요	없음	아니요	지도가 열릴 때 지도의 Kaleidr AI에 던질 질문입니다. 채팅 바에서는 입력란에 미리 채워지는 텍스트입니다.
prompt-param	promptParam	viewer	아니요	없음	아니요	방문자가 같은 출처의 페이지에서 온 경우, 페이지 URL의 해당 쿼리 매개변수에서 prompt를 읽습니다.
prompts	prompts	viewer 채팅 바	아니요	없음	아니요	|로 구분한 예시 질문입니다.
accent	accent	viewer 채팅 바	아니요	#2da84a	아니요	CSS 색상입니다.
results-url	resultsUrl	viewer 채팅 바	아니요	없음	아니요	방문자를 ?q=<question>과 함께 해당 페이지로 보냅니다.
center	center	viewer, tile, editor	아니요	제품 기본값	예	"longitude,latitude" 형식입니다. 예: "-0.1276,51.5072".
zoom	zoom	viewer, tile, editor	아니요	제품 기본값	예	숫자입니다. Viewer 및 Tile은 마운트 시 center와 함께 제공할 때만 적용됩니다.
pitch	pitch	viewer, tile, editor	아니요	제품 기본값	예	기울기(도)입니다.
bearing	bearing	viewer, tile, editor	아니요	제품 기본값	예	회전 각도(도)입니다.
theme	theme	chat, editor	아니요	없음	예 (Chat에만 적용)	JSON 객체 문자열입니다. Chat은 CSS 사용자 정의 속성을, Editor는 17가지 테마 키를 사용합니다.
flag	enabled	전체	아니요	없음	아니요	요소별 활성화 게이트 설정입니다.
base	base	전체	아니요	https://cdn.kaleidr.com	아니요	번들을 불러올 출처입니다. Kaleidr CDN(https://cdn.kaleidr.com), kaleidr.js가 로드된 출처 또는 페이지 자체의 출처만 허용됩니다. 다른 값은 경고 후 무시합니다. 기본 주소 재정의를 참고하세요.
viewer-base	viewerBase	viewer, tile	아니요	https://map-embed.kaleidr.com	아니요	iframe을 로드하는 출처입니다.
api-base	apiBase	chat, editor, tile	아니요	https://api.kaleidr.com/inference-api	아니요	세션 교환과 제품 요청을 전송하는 곳입니다. /inference-api 경로가 포함되어야 합니다.
tile-base	tileBase	editor	아니요	https://tile.kaleidr.com	아니요	스타일 ID를 확인하는 호스트입니다.

api-key는 지원 중단된 publishable-key 별칭입니다. 네 가지 …-base 속성은 다른 배포 환경을 시험하는 용도로, 프로덕션에서는 필요하지 않습니다.

불리언 속성

flag와 contained는 불리언으로 해석합니다.

작성 방식	해석 결과
값 없는 contained, contained=""	참
"true", "1", "yes", "on"	참
"false", "0", "no", "off"	거짓
속성이 없음	지정 안 됨
나머지 값	콘솔 경고 후 무시

대소문자나 앞뒤 공백은 구별하지 않으므로 flag="False"도 요소를 비활성화합니다. 값 없는 속성은 참이기 때문에 템플릿에서 flag=""를 출력하면 요소를 활성화하게 됩니다. false를 명시적으로 사용하세요.

숫자 및 카메라 속성

zoom, pitch, bearing은 숫자로 파싱합니다. center는 쉼표로 구분한 두 숫자이며 경도가 먼저입니다. 해석할 수 없는 값은 메시지 없이 무시하고 제품의 기본값을 사용합니다.

마운트 이후의 속성

요소는 문서에 들어갈 때 한 번만 속성을 읽습니다. 이후 관찰하는 속성은 다음 다섯 개뿐입니다.

변경된 속성	viewer	tile	editor	chat
center, zoom, pitch, bearing	지도가 새 카메라 위치로 즉시 이동합니다.	지도가 즉시 이동합니다.	지도가 즉시 이동합니다.	콘솔 경고만 표시되고 아무 일도 일어나지 않습니다.
theme	콘솔 경고	콘솔 경고	콘솔 경고. Editor는 마운트 시에만 읽습니다.	패널의 스타일이 바뀝니다.
다른 속성	변화 없음	변화 없음	변화 없음	변화 없음

속성으로 카메라를 바꾸면 애니메이션 없이 이동합니다. 애니메이션을 원하면 Kaleidr.mount로 마운트한 뒤 handle.setCamera({ …, duration: 800 })를 호출하세요.

카메라 속성 하나가 바뀌면 요소는 현재 설정된 카메라 속성을 모두 전송합니다. zoom만 변경해도 요소에 center가 있으면 그 중심점이 다시 적용됩니다.

share-id, style-id, publishable-key, product, flag, contained, lang, chat-title, placeholder를 변경하려면 요소를 제거하고 새 속성이 지정된 요소를 다시 삽입하세요. Tile은 handle.setStyle을 이용해, 단 Kaleidr.mount로 마운트한 경우에만 다시 마운트하지 않고 스타일을 바꿀 수 있습니다.

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

수명 주기

이벤트	요소의 동작
문서에 들어옴	속성을 읽고 마운트합니다. Chat, Editor, Tile은 세션 교환을 시작합니다.
kaleidr.js가 로드되기 전에 이미 문서에 있음	스크립트 로드 전에는 아무 일도 하지 않다가 로드 후 마운트합니다.
문서에서 제거됨	추가된 항목을 제거하고 세션 갱신을 중지하며 마운트를 파괴합니다.
다시 문서에 들어옴	속성을 다시 읽고 새 세션 교환으로 다시 마운트합니다.
다른 부모 요소로 이동	문서에서 나갔다가 다시 들어온 것으로 처리되어 해제 후 재마운트합니다.
product가 누락되거나 네 제품 중 하나가 아님	[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"를 기록하며 마운트하지 않습니다. 나중에 product를 설정해도 소용없습니다.

이에 따른 주의 사항:

• 요소를 삽입하기 전에 속성을 지정하세요. JavaScript로 만들 때는 모든 속성을 먼저 설정하고 요소를 추가하세요. 먼저 추가하면 그때 가진 속성으로 마운트됩니다.

  const el = document.createElement('kaleidr-map');
  el.setAttribute('product', 'tile');
  el.setAttribute('publishable-key', 'kld_pk_live_…');
  el.setAttribute('style-id', 'kaleidr-night');
  el.style.cssText = 'display:block; height:480px';
  document.getElementById('slot').appendChild(el); // mounts here

• 재마운트에는 비용이 듭니다. Tile을 다시 마운트하면 지도 로드가 또 계산됩니다. Editor는 편집 내역을 잃고 Chat은 새 대화를 시작합니다. 프레임워크의 목록 다시 렌더링처럼 DOM 노드를 재생성하거나 재정렬하는 코드가 의도치 않게 이를 일으킬 수 있습니다. 프레임워크 통합을 참고하세요.

• 숨긴 요소도 마운트됩니다. display:none은 마운트를 지연시키지 않습니다. 닫힌 탭 안의 Tile도 세션을 시작합니다.

• 지도로 대체되기 전까지 자식 콘텐츠가 표시됩니다. 요소 안에 넣은 콘텐츠는 보입니다. Viewer 및 Tile은 로드되면 콘텐츠를 iframe으로 교체하므로 자식 요소를 로딩 표시나 활성화 게이트에 의해 보류되거나 실패했을 때의 대체 콘텐츠로 사용할 수 있습니다. Chat과 Editor는 자식 콘텐츠를 제거하지 않습니다. 필요한 경우가 아니라면 비워 두세요.

크기 지정

<kaleidr-map>의 기본값은 display:block이므로 height를 설정할 수 있습니다.

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

이 기본 동작에 관한 세 가지 사항:

• 직접 지정한 display가 우선입니다. 인라인 스타일, CSS 스타일시트의 규칙, hidden 속성 모두 기본값을 덮어씁니다. display:inline이면 height가 적용되지 않습니다.
• 콘텐츠 보안 정책에서 별도 허용할 필요가 없습니다. 기본값은 <style> 태그나 style 속성으로 전달되지 않으므로 'unsafe-inline' 없이도 동작합니다.
• Safari 16.4 이전에는 이 기본값이 적용되지 않습니다. 요소가 인라인으로 남아 width와 height를 무시합니다. 문서 예제에 display:block을 style 속성에 유지하는 이유입니다. 최신 브라우저에는 해롭지 않으며 오래된 브라우저에서는 크기 지정에 필요합니다.

따라서 문서 예제에서는 다음 형식을 사용합니다.

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

또는 사이트 전체에 한 번만 지정할 수 있습니다.

kaleidr-map { display: block; height: 480px; }

제품	크기 동작
viewer, tile	iframe의 너비는 요소의 100%입니다. 마운트 시 요소에 높이가 있다면 높이도 100%이고, 그렇지 않으면 고정 500픽셀입니다. 요소에 인라인 위치가 없다면 position:relative를 설정하고 overflow:hidden을 적용합니다.
editor	요소 너비와 높이의 100%를 차지합니다. 높이가 없으면 보이지 않습니다.
chat	contained가 없으면 패널이 화면 왼쪽 위에 고정되며 요소 크기는 관계없습니다. contained가 있으면 요소 내부에 배치되므로 position:relative 등의 위치 지정과 크기가 필요합니다.

500픽셀 대체 높이는 마운트 시 한 번 결정됩니다. 그때 높이가 없던 요소는 나중에 높이를 지정해도 iframe이 500픽셀로 유지됩니다.

콘텐츠 보안 정책에서 인라인 style 속성을 금지하면 스타일시트로 요소 크기를 지정하세요. 요소 자체의 기본 블록 표시에는 영향이 없습니다.

핸들 매트릭스

요소는 핸들을 제공하지 않습니다. 메서드를 호출하려면 핸들을 반환하는 Kaleidr.mount로 마운트하세요.

메서드	chat	viewer	editor	tile
destroy()	예	예	예	예
setCamera(camera)	지원 안 함	예	예	예
setTheme(theme)	예	지원 안 함	지원 안 함	지원 안 함
setStyle(style)	지원 안 함	지원 안 함	지원 안 함	예
send(text)	지원 안 함	예	지원 안 함	지원 안 함
setFilters(filters)	지원 안 함	예	지원 안 함	지원 안 함
showVehiclesLayer(layer)	지원 안 함	예	지원 안 함	지원 안 함
clearVehiclesLayer()	지원 안 함	예	지원 안 함	지원 안 함

모든 핸들에는 이 메서드가 모두 있습니다. '지원 안 함'으로 표시된 메서드를 호출하면 아무 일도 일어나지 않고 콘솔 경고가 기록됩니다. 예외를 던지지 않습니다. 이는 /embed/v1 계약의 일부입니다.

제품별 동작:

• chat: setTheme은 패널의 스타일을 변경합니다. setCamera는 Chat이 지도를 소유하지 않으므로 지원되지 않습니다. AI는 답할 때 연결된 지도를 이동시키며 개발자는 자체 지도 라이브러리의 API로 지도를 이동할 수 있습니다.
• viewer: setCamera는 게시된 지도를 이동시킵니다. setFilters는 장소 레이아웃의 방문자 필터를 설정합니다. showVehiclesLayer는 내 차량을 지도에 그리고 clearVehiclesLayer는 이를 지웁니다. 차량 레이어를 참고하세요.
• editor: setCamera는 Editor 지도를 이동시킵니다. 테마와 베이스맵은 마운트 시 고정됩니다.
• tile: setCamera는 지도를 이동시키고 setStyle은 재마운트 없이 베이스맵을 교체합니다.

setCamera는 { center, zoom, pitch, bearing, duration }를 받습니다. 모든 필드는 선택 사항이고 center는 [longitude, latitude]이며 duration 단위는 밀리초입니다. 자세한 내용은 kaleidr.js를 참고하세요.

Chat과 map-target

Chat은 두 종류의 지도를 제어할 수 있습니다.

• 자체 지도(Mapbox GL JS, MapLibre GL JS, Google Maps, Leaflet): 지도 객체는 속성에 넣을 수 없으므로 Kaleidr.mount를 map 옵션과 함께 호출해야 합니다. Chat 참조를 참고하세요.

• 같은 페이지의 Kaleidr Viewer 또는 Tile 요소: CSS 선택자로 map-target을 해당 요소에 연결합니다.

  <div style="position:relative">
    <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
                 style-id="kaleidr-morning"
                 style="display:block; height:480px"></kaleidr-map>
  
    <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
                 map-target="#basemap"
                 style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
  </div>

  두 요소의 순서는 상관없습니다. Chat은 필요한 순간 대상을 찾습니다.

map 또는 map-target이 없으면 Chat은 지도 없는 패널입니다.

래퍼와 Chat 요소 스타일은 패널을 지도 위에 표시합니다. 각 선언은 테마 및 레이아웃에서 설명합니다. 게시된 지도에서의 Chat은 게시된 지도에서 Chat 사용을 참고하세요.

콘솔 메시지

메시지	의미
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product가 없거나 잘못되었습니다. 요소는 마운트되지 않습니다.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag 또는 contained에 허용되지 않는 값이 지정되었습니다. 메시지에서 flag="…" 또는 contained="…"를 확인하세요.
[kaleidr] base "<value>" 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.	base 속성이 허용되지 않는 출처를 가리킵니다. 번들은 기본 CDN에서 로드됩니다.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	flag가 마운트를 보류했습니다. 해당 설정 없이 요소를 교체하세요.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	Chat 요소의 카메라 속성이 변경되었습니다.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	Viewer, Tile 또는 Editor 요소의 theme 속성이 변경되었습니다.

마운트 실패는 [kaleidr:<product>] … 형식으로 기록됩니다. 목록은 kaleidr.js에 있습니다.

지원하지 않는 기능

• 이벤트: 요소는 DOM 이벤트를 발생시키지 않습니다.
• 속성 또는 메서드: 요소에 setCamera나 handle 속성, ready 프로미스가 없습니다.
• 속성 다시 읽기: 감시하는 다섯 속성을 제외하고 마운트 이후 변경은 무시됩니다.

관련 문서

• kaleidr.js 로더
• 프레임워크 통합
• Viewer, Tile, Editor 및 Chat 참조