Viewer 참고 문서
product="viewer"는 Kaleidr Studio에서 게시한 지도를 표시합니다. SDK는 마운트 대상의 내용을 https://map-embed.kaleidr.com/embed/<id>를 로드하는 iframe으로 교체합니다. 지도는 이 iframe 안에 그려집 니다.
| 키 | 필요 없습니다. 전달하지 마세요. |
| 요금제 | Free를 포함한 모든 요금제. |
| 렌더링 위치 | https://map-embed.kaleidr.com에서 제공하는 iframe. |
| 사용량 | 조회당 지도 로드 1회, 지도 소유자 조직에 청구. |
| CSP | script-src https://cdn.kaleidr.com 및 frame-src https://map-embed.kaleidr.com. |
단계별 안내는 게시된 지도 임베드를 참조하세요.
마운트
요소를 사용하는 경우:
<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>
JavaScript에서:
const handle = Kaleidr.mount('#map', {
product: 'viewer',
shareId: 'YOUR_MAP_ID',
});
SDK 없이:
<iframe src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID"
width="100%" height="480" style="border:0;" loading="lazy"
referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
title="Kaleidr map"></iframe>
채팅 바
layout="bar"는 Viewer를 채팅 바로 바꿉니다. 페이지에 질문 입력란 하나만 두고, 방문자가 질문하기 전까지는 지도를 표시하지 않습니다. 질문하면 게시된 지도가 열리고 지도의 Kaleidr AI가 그곳에서 답합니다.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
chat-title="Ask about the neighborhood"
prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>
답변은 다음 두 곳 중 하나에서 열립니다.
| 설정 | 질문 시 동작 |
|---|---|
results-url 없음(기본값) | 지도가 페이지 위에 창 전체를 채우며 열리고 질문을 보냅니다. 방문자는 닫기 버튼으로 지도를 닫습니다. 이후의 질문도 같은 지도에 보내므로 대화가 이어집니다. |
results-url="/map" | 브라우저가 ?q=<question>과 함께 해당 페이지로 이동합니다. 그 페이지에서 prompt-param="q"를 지정한 Viewer가 지도 가 열릴 때 질문을 보냅니다. 단, 방문자가 같은 출처의 페이지에서 온 경우에만 그렇습니다. |
결과 페이지:
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
style="display:block; height:600px"></kaleidr-map>
- 답변은 지도가 합니다. 질문은 지도 자체의 Ask Kaleidr 패널로 전달되므로 지도에서 Control Tower가 켜져 있어야 하며(Studio, Kaleidr AI), 게시된 지도의 Kaleidr AI 규칙이 적용됩니다. 비용은 소유자가 부담하고, 답변하는 위치는 지도의 허용 도메인이 정합니다. Control Tower가 없는 지도에서는 지도는 열리지만 질문은 전달되지 않습니다.
- 채팅 바는 지도를 로드하지 않습니다. 방문자가 질문할 때 지도가 로드되며 지도 로드 1회로 집계됩니다.
- 채팅 바는 자체 섀도 루트에 그려지므로 페이지의 CSS가 스타일을 바꾸지 않으며, 스타일에
style-src권한이 필요 없습니다. 너비는 요소와 같고 높이는 콘텐츠에 맞춰집니다. - 채팅 바 자체의 레이블은
lang을 따르며,lang이 없으면 방문자의 브라우저 언어를 따릅니다. 지원 언어는 영어, 스페인어, 프랑스어, 독일어, 포르투갈어, 일본어, 한국어, 중국어 간체 및 번체, 아랍어입니다. 직접 지정한chat-title,placeholder,prompts는 작성한 그대로 표시됩니다. prompt는 입력란을 미리 채우고,handle.send()는 코드에서 질문합니다.handle.send('Parks nearby')는 해당 질문을 보내고,handle.send()는 입력란의 내용을 질문합니다.
template.kaleidr.com의 빌더가 선택한 지도에 맞는 두 스니펫을 모두 작성해 줍니다.
장소 레이아웃
layout="locator"와 layout="listings"는 지도가 그리는 장소 라이브러리 컬렉션의 목록을 컬렉션의 필터 및 카드와 함께 게시된 지도 옆에 표시합니다.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
filters="search|category|open_now"
style="display:block; height:600px"></kaleidr-map>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
filters="price|beds|baths"
style="display:block; height:720px"></kaleidr-map>
| 레이아웃 | 목록 | 핀 |
|---|---|---|
locator | 거리순으로 정렬된 장소. 검색 필드, 내 주변 버튼, 필터, 개수가 있습니다. 목록의 어떤 장소와도 일치하지 않는 검색은 검색한 장소로 지도를 이동합니다. | Studio에서 스타일을 지정한 컬렉션 레이어. |
listings | 사진 카드. 넓은 프레임에서는 두 열로 표시되며 거리, 가격 낮은 순, 가격 높은 순으로 정렬합니다. | 가격 레이블. |
- 프레임 너비가 768픽셀 이상이면 목록이 지도 옆에 있고, 그보다 좁으면 방문자가 위로 끌어 올리는 지도 위 시트에 있습니다.
- 목록과 지도는 함께 움직입니다. 목록에서 장소를 선택하면 지도가 그곳으로 이동해 카드를 열고, 핀을 선택하면 목록이 그 장소로 스크롤됩니다. 목록, 핀, 개수는 항상 같은 장소를 보여 줍니다.
- 목록은 한 번에 50곳을 표시하며, 더 보기로 더 표시합니다.
- 내 주변은 방문자에게 위치를 요청합니다. SDK가 만드는 iframe은 이를 허용하지만, 직접 사용하는 iframe에는
allow="geolocation"이 필요합니다. - 컬렉션을 그리지 않는 지도에서는 두 레이아웃 모두 지도만 표시합니다.
filters는 컬렉션 자체의 방문자 필터 중 표시할 것을 |로 구분해 고릅니다. 작성한 순서와 관계없이 컬렉션의 순서대로 나타나며, 컬렉션이 제공하지 않는 필터는 무시됩니다. filters가 없으면 레이아웃은 컬렉션의 모든 필터를 표시합니다.
| 필터 | 표시 | 일치 대상 |
|---|---|---|
search | 텍스트 필드 | 이름, 주소 또는 카테고리에 해당 텍스트가 포함된 장소. |
category | 카테고리 버튼(가장 많은 30개까지) | 선택한 카테고리 중 하나에 속한 장소. |
price | 최솟값과 최댓값 | 가격이 범위 안에 있는 장소. 범위를 좁히면 가격이 없는 장소는 숨겨집니다. |
beds, baths | 전체, 1+, 2+, 3+, 4+ | 그 수 이상인 장소. |
open_now | 스위치 | 장소 자체의 시간대 기준으로 지금 영업 중인 장소. 켜져 있는 동안 영업시간이 없는 장소는 숨겨집니다. |
방문자가 설정한 필터는 모두 함께 적용됩니다.
card는 장소 카드에 표시할 양을 정합니다. 기본값인 auto는 Studio에서 디자인한 카드입니다. compact는 작은 프레임을 위해 제목, 부제목, 작업만 표시합니다.
장소 작업은 컬렉션이 정의한 대로 동작합니다. 길찾기는 지도 안에 경로를 그리고 Apple 지도와 Google 지도를 제공합니다. 링크는 새 탭에서 열리고, 전화는 전화 링크를 엽니다. Schedule a Tour 같은 요청 작업은 업체의 요청 양식을 지도 위에 엽니다.
가이드 레이아웃
layout="guide"는 시설 지도를 열고 그 옆에 Ask Kaleidr 패널을 표시합니다. 호텔의 동네 안내나 시설 주변 지도에 사용합니다. 시설 컬렉션(collection, 없으면 지도가 그리는 첫 번째 시설 컬렉션)을 나열하며 Control Tower가 켜져 있어야 합니다. 시설 컬렉션을 그리지 않는 지도에서는 지도만 표시합니다.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
style="display:block; height:640px"></kaleidr-map>
- 채팅이 먼저입니다. 너비 769픽셀 이상인 프레임에서는 패널이 너비 400픽셀로 지도 왼쪽에 놓입니다. 더 좁으면 지도 위에 높이 45%의 시트로 표시되며, 방문자가 85%까지 끌어올릴 수 있습니다. 답변이 AI로 생성된다는 안내는 입력란 아래에 그대로 남습니다.
- 입력란 위의 카테고리 칩은 컬렉션에서 가장 많은 카테고 리 8개입니다. 칩을 누르면 해당 카테고리의 핀을 보여 주고, 방문자의 언어로 "앵커 근처의 카테고리 보여 줘"라고 질문합니다. Plan My Day는 "앵커 주변으로 하루 일정을 짜 줘"라고 질문합니다.
- 앵커는 Studio의 지도 설정에서 지정하는 지도의 기준 핀입니다. 지도가 그리는 컬렉션의 장소이거나, 호텔처럼 지도 위에 놓은 지점입니다. 이름이 붙은 별도의 핀으로 그려지며, 가이드에서 "근처"는 그 근처를 뜻합니다. 앵커가 없는 지도는 지도 중심을 사용합니다.
- 하루 일정. 하루 일정을 요청받으면 가이드는 앵커에서 출발해 먼저 내 컬렉션의 장소를, 그다음 Kaleidr 자체 장소 데이터를 방문하는 경로를 그리고, 이름과 시간이 있는 정류 지점 카드로 방문자의 언어로 보여 줍니다.
- 시설 카드는 Studio에서 디자인한 카드를 보여 주고, 표시한 장소에는 Staff Pick이 붙으며, 그 아래에 연결의 카드가 표시됩니다. 연결된 콘텐츠는 카드에만 나타나고 가이드의 답변에는 쓰이지 않습니다.
- 요청. 시설의 Reserve 작업은 업체의 요청 양식을 엽니다.
채팅 스트림의 가이드
viewer는 지도의 Kaleidr AI에 어떤 레이아웃을 표시 중인지 알립니다. POST /chat/control/stream 클라이언트는 가이드에 속한 필드 두 개를 보게 됩니다.
| 필드 | 위치 | 형태 |
|---|---|---|
layout | 요청 본문 | 가이드 레이아웃을 표시하는 동안 "guide"이며, 그렇지 않으면 생략되어 일반 지도 턴이 됩니다. 최대 16자이며, 넘으면 요청이 422 invalid_layout으로 거부됩니다. |
itinerary | 스트림의 이벤트이며 end 이벤트에도 반복됩니다 | { title, stops: [{ name, time?, note? }] }: 하루 일정의 제목과 이름이 있는 정류 지점 1~12개로, 이미 방문자의 언어로 되어 있습니다. note는 내 장소에만 붙습니다. |
하루 일정을 표시하지 않는 클라이언트는 이 이벤트를 무시해도 됩니다.
실시간 레이아웃
layout="live"는 차량이 지금 어디에 있고 오늘 어디에 정차하는지 보여 줍니다. 푸드트럭 노선, 셔틀, 이동형 서비스에 사용합니다. 컬렉션 두 개를 읽습니다. 위치가 실시간 추적에서 오는 차량 컬렉션과, 일정이 담긴 정류장 컬렉션입니다.
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
style="display:block; height:640px"></kaleidr-map>
| 옵션 | 기본값 | 읽는 내용 |
|---|---|---|
collection | 지도가 그리는 첫 번째 차량 컬렉션 | 실시간으로 표시할 차량. |
stops | 지도가 그리는 첫 번째 정류장 컬렉션 | 정류장과 운행 시간대. |
둘 다 그리지 않는 지도에서는 지도만 표시합니다. 패널은 너비 769픽셀 이상인 프레임에서는 지도 옆에, 그보다 좁으면 지도 위의 시트로 표시됩니다.
- 패널 맨 위에 실시간 표시가 나오며, 근무 중인 차량이 없 으면 현재 운행하지 않음이 표시됩니다.
- 표시된 차량마다 한 줄: 차량 이름, 이동 중, 정차 중, 정차 위치와 정류장 이름, 또는 마지막 보고가 플릿의 오래됨 표시 기준보다 오래되면 5분 전에 확인됨. 그리고 다음 정류장과 약 12분, 예상 태그.
- 오늘의 경로: 오늘의 정류장을 시간대 순서로 나열하고, 각각의 시간대, 담당 차량, 배지를 표시합니다.
- **나까지 얼마나 걸리나요?**는 방문자의 위치를 요청하고, 거부하면 도시의 대략적인 위치를 사용해 표시된 차량이 도착하는 데 걸리는 시간을 보여 줍니다. 위치는 이 추정에만 쓰이며 저장되지 않습니다.
- 차량을 선택하면 방문자가 지도를 움직일 때까지 그 차량을 따라갑니다. 정류장을 선택하면 오늘의 시간대나 다음 운행 날짜가 담긴 카드가 열립니다.
| 배지 | 조건 |
|---|---|
| 지금 여기 | 차량이 그 정류장에 체크인했습니다. |
| 오늘 휴무 | 운전자가 차량을 오늘 휴무로 표시했습니다. |
| 영업 중 | 정류장의 시간대에 지금이 포함됩니다. |
| 다음: 11:00–14:00 | 정류장에 오늘 이후 시간대가 있습니다. |
| 오늘 없음 | 정류장에 오늘 시간대가 없습니다. 카드에는 14일 이내의 다음 운행 날짜가 표시됩니다. |
방문자에게 보이는 움직임은 부드럽고, 추측하지 않습니다. 차량은 보고된 위치에서 다음 위치로 미끄러지듯 이동하며 마지막 보고보다 앞서 나가지 않습니다. 위치는 10초마다 새로 고쳐지며(지도 작성자가 5~60초의 다른 간격을 고른 경우 그 간격), 페이지가 숨겨져 있는 동안은 멈춥니다. 오늘의 상태와 추정 시간은 1분마다 새로 고쳐집니다. 새로 고침에 실패하면 마지막 화면을 유지합니다.
근무 중인 차량만 표시되며, 정밀도는 플릿의 공개 정밀도가 허용하는 수준입니다. 근무가 끝난 차량은 다음 새로 고침에서 사라집니다.
모든 시간은 추정치입니다. 도로 거리와 일반적인 속도로 계산하며 교통 상황은 포함하지 않습니다. 분 단위로 올림하여 약 12분 또는 약 1시간 20분처럼 표시하고, 도착 시각으로는 표시하지 않습니다. 두 지점 사이에 도로 경로가 없으면 예상 없음라고 표시됩니다. 도로 경로는 OpenStreetMap 데이터로 만들며, © OpenStreetMap contributors, ODbL에 따릅니다.
Request Pickup은 정류장 컬렉션의 요청 작업입니다. 작성자가 방문자가 픽업 위치와 목적지를 고르게 하기를 켰다면, 방문자는 먼저 픽업 위치(바꾸지 않으면 정류장 자체)와 목적지를 주소 검색이나 지도 탭으로 정한 다음 요청 양식을 작성합니다. 두 지점 모두 요청과 함께 전달됩니다.
패널의 레이블은 viewer의 언어를 따르며, 채팅 바와 같은 10개 언어를 지원합니다.
옵션
| 마운트 옵션 | 속성 | 형식 | 기본값 | 필수 | 설명 |
|---|---|---|---|---|---|
product | product | 'viewer' | 없음 | 예 | Viewer 선택. |
shareId | share-id | 문자열 | 없음 | 예 | Studio의 임베드 코드에서 가져온 게시된 지도 ID. ^[A-Za-z0-9._~-]{1,100}$와 일치해야 합니다. |
mapId | map-id | 문자열 | 없음 | 아니요 | shareId의 별칭이며 shareId가 없을 때만 사용합니다. |
center | center | [longitude, latitude]; 속성은 "longitude,latitude" | 저장된 뷰 | 아니요 | 초기 중심. |
zoom | zoom | 숫자 | 저장된 뷰 | 아니요 | 초기 줌. 마운트 시 center가 없으면 무시합니다. |
pitch | pitch | 숫자, 도 | 저장된 뷰 | 아니요 | 초기 기울기. |
bearing | bearing | 숫자, 도 | 저장된 뷰 | 아니요 | 초기 회전. |
viewerBase | viewer-base | URL | https://map-embed.kaleidr.com | 아니요 | iframe을 로드하는 출처. 출처만 사용하며 운영 환경에선 필요 없습니다. |
base | base | URL | https://cdn.kaleidr.com | 아니요 | SDK가 viewer.js를 로드하는 출처입니다. 출처 만 사용하고 기본 주소 재정의에 나열된 출처만 허용합니다. |
enabled | flag | 불리언 | 없음 | 아니요 | 마운트별 활성화 게이트. |
prompt | prompt | 문자열 | 없음 | 아니요 | 지도가 열릴 때 지도의 Kaleidr AI에 던질 질문. 채팅 바에서는 입력란에 미리 채워지는 텍스트. 최대 500자. |
promptParam | prompt-param | 문자열 | 없음 | 아니요 | 페이지 자체 URL의 이 쿼리 매개변수에서 prompt를 읽습니다. 채팅 바의 결과 페이지에서는 q입니다. 방문자가 같은 출처의 페이지에서 온 경우에만 읽으므로, 다른 곳에서 온 링크로는 지도가 어떤 질문도 하게 만들 수 없습니다. |
layout | layout | 'map', 'bar', 'locator', 'listings', 'guide' 또는 'live' | 'map' | 아니요 | bar는 채팅 바를 마운트합니다. locator와 listings는 컬렉션 목록 옆에 지도를 표시합니다. 장소 레이아웃을 참고하세요. guide는 시설 지도 옆에 채팅을 엽니다. 가이드 레이아웃을 참고하세요. live는 차량과 오늘의 정류장을 표시합니다. 실시간 레이아웃을 참고하세요. |
collection | collection | string | 지도가 그리는 레이아웃 유형의 첫 번째 컬렉션 | 아니요 | 매장 찾기, 매물 목록, 가이드: 목록에 표시할 컬렉션의 ID. 실시간: 차량 컬렉션의 ID. |
stops | stops | string | 지도가 그리는 첫 번째 정류장 컬렉션 | 아니요 | 실시간: 정류장 컬렉션의 ID. |
filters | filters | 문자열 배열. 속성에서는 |로 구분 | 컬렉션의 모든 필터 | 아니요 | 매장 찾기와 매물 목록: 컬렉션이 제공하는 것 중 search, category, price, beds, baths, open_now 가운데 표시할 필터. |
card | card | 'auto' 또는 'compact' | 'auto' | 아니요 | compact 카드는 제목, 부제목, 작업만 표시합니다. |
prompts | prompts | 문자열 배열. 속성에서는 |로 구분 | 없음 | 아니요 | 채팅 바: 예시 질문. 누르면 해당 질문을 보내는 버튼으로 표시됩니다. |
title | chat-title | 문자열 | 없음 | 아니요 | 채팅 바: 입력란 위의 레이블. |
placeholder | placeholder | 문자열 | 채팅 바의 언어로 표시되는 "Ask about this map" | 아니요 | 채팅 바: 입력란의 자리표시자. |
accent | accent | CSS 색상 | #2da84a | 아니요 | 채팅 바: 전송 버튼, 아이콘, 포커스 링의 색상. |
theme | theme | 'light', 'dark' 또는 'auto' | 'light' | 아니요 | 채팅 바: 색상. auto는 방문자의 시스템 설정을 따릅니다. |
lang | lang | 언어 태그 | 방문자의 브라우저 언어 | 아니요 | 채팅 바: 자체 레이블의 언어. |
resultsUrl | results-url | URL | 없음 | 아니요 | 채팅 바: 지도를 페이지 위에 여는 대신 방문자를 ?q=<question>과 함께 이 페이지로 보냅니다. |
publishableKey, styleId, map, mapTarget, contained는 Viewer 마운트에 영향을 주지 않습니다. 키를 전달하면 오히려 문제가 생깁니다. SDK가 Viewer에서 쓰지 않는 세션을 요청하고, 그 요청이 거부되면 지도도 표시되지 않습니다.
ID
shareId에는 Studio가 생성하는 다음 두 유형의 지도 ID를 사용할 수 있습니다.
- 게시된 지도 ID. 게시 및 임베드 페이지의 코드와 공유 대화상자의 임베드 탭에 표시되며 두 곳에서 같은 ID를 사용합니다.
- 공유 링크 ID. 공유 대화상자의 링크 공유 탭에 있는 URL 끝의 16자리 ID입니다.
게시된 지도 ID는 현재 저장된 지도를 보여줍니다. 공유 링크 ID는 링크를 만들었을 때 저장된 디자인 스냅샷을 보여줍니다. Kaleidr AI는 두 ID를 모두 받습니 다. 공유 링크에서는 지도가 게시되어 있는 동안, 지도의 현재 허용 도메인에서 스냅샷의 Kaleidr AI 스위치를 따릅니다. 게시된 지도의 Chat을 참조하세요.
ID가 비어 있거나 형식이 잘못돼도 예외를 던지지 않습니다. SDK는 다음을 기록하고
[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.
아무것도 렌더링하지 않습니다. Kaleidr.mount는 핸들을 반환하지만 그 메서드는 작동하지 않습니다.
직접 사용하는 iframe URL
https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>
| 쿼리 매개변수 | 값 | 효과 |
|---|---|---|
camera | longitude,latitude 또는 longitude,latitude,zoom | 초기 중심 및 선택적 확대 수준. |
pitch | 숫자, 도 | 초기 기울기. |
bearing | 숫자, 도 | 초기 회전. |
q | 텍스트, 최대 500자 | 지도가 열릴 때 지도의 Kaleidr AI에 던질 질문. Viewer가 페이지에 임베드된 경우에만 질문하며, Control Tower가 없는 지도에서는 무시됩니다. |
layout | locator, listings, guide 또는 live | 장소 레이아웃, 가이드 또는 실시간 레이아웃. 다른 값은 지도를 표시합니다. |
collection | 컬렉션 ID | 레이아웃이 나열하는 컬렉션. live에서는 차량 컬렉션. |
stops | 컬렉션 ID | live에서 정류장 컬렉션. |
filters | |로 구분한 필터 이름 | 레이아웃이 표시하는 필터. |
card | auto 또는 compact | 장소 카드에 표시할 양. |
SDK는 카메라 옵션, prompt, layout, collection, stops, filters, card에서 동일한 URL을 구성합니다.
카메라
초기 카메라는 다음 출처의 설정을 순서대로 반영하며, 나중 출처는 자신이 제공한 필드만 덮어씁니다.
- 바탕지도의 기본 뷰.
- 작성자가 Studio에 저장한 뷰. 작성자는 데스크톱, 태블릿, 휴대전화 너비에 맞춰 각각 뷰를 저장할 수 있고, 지도는 iframe 너비에 맞는 뷰를 선택합니다. 지도 콘텐츠가 프레임에 모두 들어오도록 자동 맞춤 설정할 수도 있습니다.
- 페이지에서 전달한 카메라(옵션 또는 속성의
center,zoom,pitch,bearing, 또는 iframe URL의camera,pitch,bearing).
페이지가 제공한 카메라 설정은 화면 너비에 맞춘 뷰나 콘텐츠 자동 프레이밍을 포함한 작성자의 뷰보다 우선합니다. 제공하지 않은 필드는 작성자 값을 유지합니다.
너비별 뷰나 콘텐츠 프레이밍이 설정된 지도는 방문자가 지도를 조작하기 전까지 iframe 크기가 바뀔 때마다 다시 맞춥니다. 페이지에서 카메라를 지정해도 자동 맞춤이 종료됩니다. 로드 시 카메라를 지정하거나 setCamera를 호출한 후에는 크기가 바뀌어도 자동으로 다시 맞추지 않습니다. setCamera는 지정한 필드만 변경하고 나머지는 유지합니다.
center는 경도가 먼저입니다. [-0.1276, 51.5072]는 런던입니다.
크기
- iframe은 마운트 대상 너비의 100%이며 테두리가 없고 모서리가 둥글게 표시됩니다.
- 마운트 시 대상에 높이가 있으면 iframe도 그 높이의 100%이고, 없으면 고정 500픽셀입니다.
- 마운트는 대상의 자식 요소를 교체하고, 인라인 위치가 없으면
position:relative와overflow:hidden을 설정합니다. <kaleidr-map>은 기본적으로display:block이므로height가 적용됩니다. 높이를 지정하세요. Safari 16.4 이전 버전은 요소를 인라인으로 두므로 예제에display:block도 포함합니다.
핸들
Kaleidr.mount는 핸들을 동기적으로 반환합니다. 모든 제품의 동작은 핸들 표를 참조하세요.
| 멤버 | Viewer에서의 동작 |
|---|---|
handle.product | 'viewer' |
handle.setCamera(camera) | 지도를 움직입니다. |
handle.setTheme(theme) | 지원하지 않으며 경고만 표시합니다. |
handle.setStyle(style) | 지원하지 않으며 경고만 표시합니다. |
handle.send(text) | 방문자가 text를 입력한 것처럼 지도의 Kaleidr AI에 질문합니다. 채팅 바에서 텍스트 없이 send()를 호출하면 입력란의 내용을 질문합니다. 답변 중에 보낸 질문은 그 답변이 끝날 때까지 기다리며, 더 새로운 질문은 아직 대기 중인 질문을 대체합니다. |
handle.setFilters(filters) | 장소 레이아웃의 방문자 필터를 설정합니다. map 레이아웃에서는 아무 작업도 하지 않습니다. |
handle.showVehiclesLayer(layer) | 내 차량 레이어를 그리거나 이동합니다. |
handle.clearVehiclesLayer() | 내 차량 레이어를 지웁니다. |
handle.destroy() | iframe을 제거하고 메시지 수신을 중단합니다. |
setCamera(camera)
handle.setCamera({
center: [2.3522, 48.8566], // [longitude, latitude]
zoom: 12,
pitch: 45,
bearing: -20,
duration: 800, // milliseconds
});
| 필드 | 형식 | 설명 |
|---|---|---|
center | [number, number] | 경도, 위도. |
zoom | 숫자 | 줌 수준. 마운트할 때와 달리 zoom은 center 없이도 작동합니다. |
pitch | 숫자 | 기울기(도). |
bearing | 숫자 | 회전(도). |
duration | 숫자 | 애니메이션 길이(밀리초). 생략 또는 0이면 즉시 이동합니다. |
모든 필드는 선택 사항이며 생략한 필드는 기존 값을 유지합니다.
setCamera는 Kaleidr.mount가 반환된 후 언제든지, 바로 다음 줄에서도 호출할 수 있습니다. iframe 안의 지도가 준비되기 전에 호출한 내용은 보관했다가 준비 신호가 오면 순서대로 적용합니다. 최근 256개를 보관합니다. 일정 시간(보통 iframe 로드 후 10초)이 지나도 준비 신호가 없으면 보관된 호출을 그대로 보내고 콘솔 경고를 한 번 표시합니다. kaleidr-embed:ready를 먼저 기다릴 필요는 없습니다. 시작 뷰는 마운트 옵션으로 지정하는 것이 더 직접적이며, 지도는 이동 과정 없이 해당 뷰로 열립니다.
현재 카메라를 읽는 메서드는 없습니다.
setFilters(filters)
handle.setFilters({
q: 'downtown',
category: ['Outlet', 'Flagship'],
price: [250000, null], // [min, max]; null leaves that end open
beds: 2,
baths: 1,
open_now: true,
});
| 필드 | 유형 | 설정 대상 |
|---|---|---|
q | 문자열 | 검색 필드. |
category | 문자열 배열 | 선택한 카테고리. |
price | [number | null, number | null] | 최저 가격과 최고 가격. |
beds | 숫자 | 최소 침실 수. |
baths | 숫자 | 최소 욕실 수. |
open_now | 불리언 | 영업 중 스위치. |
모든 필드는 선택 사항입니다. 방문자에게는 직접 설정한 것처럼 필터가 바뀌어 보이며, 다시 바꿀 수 있습니다. 레이아웃이 표시하지 않는 필터의 필드와 그 밖의 필드는 무시됩니다. setCamera와 마찬가지로 지도가 준비되기 전에 한 호출은 보관했다가 준비되면 적용합니다. 장소 레이아웃보다 오래된 viewer 번들에는 setFilters가 없습니다. 이 경우 호출은 아무 작업도 하지 않고, 마운트가 이를 노출하지 않았다는 콘솔 경고를 기록합니다.
showVehiclesLayer(layer)
자체 배차 시스템의 위치처럼 페이지가 이미 추적하는 차량을 임베드된 지도에 그립니 다. 데이터는 페이지에서 iframe으로만 전달되고 다른 곳으로는 가지 않습니다. Kaleidr 서버를 거치지 않으며, viewer가 이 레이어를 위해 무언가를 가져오지도 않습니다.
handle.showVehiclesLayer({
layer_id: 'shuttles',
vehicles: [
{ id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
{ id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
],
});
// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });
handle.clearVehiclesLayer();
| 필드 | 형식 | 설명 |
|---|---|---|
layer_id | string | 레이어의 이름입니다. 같은 ID로 다시 호출하면 그 자리에서 업데이트합니다. |
vehicles | array, 최대 2,000개 | 그릴 차량. |
vehicles[].id | string | 필수. 호출 간에 차량을 식별합니다. |
vehicles[].lat, vehicles[].lng | number | 필수. 차량의 위치. |
vehicles[].name | string | 차량 옆에 그려지는 레이블. |
vehicles[].color | CSS 16진수 색상 | 차량의 색. 없으면 회색으로 그립니다. |
vehicles[].bearing | number, 도 | 차량이 향한 방향. |
attribution | string | 데이터의 출처 표기로, 차량을 탭하면 차량 카드에 표시됩니다. |
- 같은
layer_id면 그 자리에서 업데이트합니다. 각 차량은 그려진 위치에서 새 지점까지, 이전 호출 이후 지난 시간(최대 30초) 동안 미끄러지듯 이동합니다. 새 호출에 없는 차량은 사라집니다. - 새
layer_id이거나 지정하지 않으면 레이어를 교체합니다. 지도에는 차량 레이어가 한 번에 하나만 표시됩니다. id가 없거나lat과lng가 유한한 숫자가 아닌 차량은 버려지며, 2,000번째를 넘는 차량도 마찬가지입니다.- 차량을 움직이려면 다시 호출하세요. viewer는 이 레이어의 데이터를 직접 가져오지 않습니다.
setCamera와 마찬가지로 지도가 준비되기 전에 한 호출은 보관했다가 준비되면 적용합니다.
SDK의 LiveLayerData와 LiveVehicle 타입이 레이어의 형태를 선언합니다. showVehiclesLayer와 clearVehiclesLayer는 viewer 메서드로, chat, editor, tile에서는 경고를 기록하고 아무 작업도 하지 않습니다. 이 레이어보다 오래된 viewer 번들에는 둘 다 없습니다. 이 경우 호출은 아무 작업도 하지 않고, 마운트가 이를 노출하지 않았다는 콘솔 경고를 기록합니다.
마운트 후 요소 속성
마운트된 <kaleidr-map product="viewer">에서 center, zoom, pitch, bearing을 변경하면 애니메이션 없이 지도가 이동합니다. share-id 등 다른 속성을 변경해도 반응하지 않습니다. 다른 지도를 보여주려면 요소를 제거하고 새 요소를 삽입하세요.
iframe 메시지
iframe은 임베드한 페이지로 메시지를 보냅니다. 그중 두 가지가 공개된 '로드 완료'와 '실패' 신호입니다.
// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }
// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }
window.addEventListener('message', (event) => {
if (event.origin !== 'https://map-embed.kaleidr.com') return;
if (event.source !== iframe.contentWindow) return; // which embed sent it
const msg = event.data;
if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
if (msg?.type === 'kaleidr-embed:error') onError(msg);
});
SDK를 사용할 때 iframe은 마운트 대상 내부의 첫 번째 <iframe>, 즉 target.querySelector('iframe')입니다.
오류 코드
code | 종료 여부 | 의미 |
|---|---|---|
no_id | 예 | iframe URL에 지도 ID가 없습니다. id는 null입니다. |
not_found | 예 | 해당 ID의 게시된 지도나 공유 링크가 없습니다. 지도가 게시된 적이 없거나 게시 취소되었거나, 공유 링크의 지도가 삭제되었거나 Kaleidr가 링크를 제거했거나, ID 오타일 수 있습니다. |
domain_not_allowed | 예 | 지도에 허용 도메인 제한이 있는데 페이지가 허용되지 않았거나 리퍼러를 보내지 않았습니다. |
map_loads_exhausted | 예 | 소유자 조직이 해당 기간 지도 로드 할당량을 소진했습니다. |
fetch_failed | 예 | 지도를 가져오지 못했습니다. |
maplibre_error | 아니요 | 지도는 시작됐지만 일부 요소를 그리는 데 실패했습니다. ready 전후에 여러 번 도착할 수 있습니다. |
종료 오류가 발생하면 iframe은 지도 대신 짧은 메시지를 표시하며 ready를 보내지 않습니다.
규칙
ready는 지도가 렌더링되고 조회가 집계된 후 로드당 한 번 전송됩니다.- SDK는
loading="lazy"로 iframe을 생성하므로 화면 가까이에 올 때까지 메시지가 오지 않습니다. - iframe은
type이kaleidr-embed:로 시작하는 다른 메시지도 전송합니다. SDK가 Chat을 지도에 연결할 때 사용하지만 공개 계약에는 없으며 변경될 수 있으므로 의존하지 마세요. - iframe은
setCamera등의 카메라 제어 메시지를 직접 자신을 임베드한 페이지에서 받았을 때만 처리합니다. 다른 창이나 프레임이 보낸 메시지는 무시되므로 iframe을 포 함한 페이지에서setCamera를 호출하세요. - SDK와 요소는 DOM 이벤트나
readyPromise를 제공하지 않습니다.
방문자에게 보이는 메시지
다음 문구가 지도 대신 iframe에 나타납니다.
| 문구 | 코드 |
|---|---|
| "Loading map…" | 없음: 지도를 로드하는 중 |
| "Couldn't find a map id in the URL." | no_id |
| "This map isn't available — it may have been unpublished, paused, or the link is incorrect." | not_found |
| "This map isn't allowed to render on this site. Please contact the map owner." | domain_not_allowed |
| "This map has reached its map load limit. It will be available again when the owner's allowance resets." | map_loads_exhausted |
| "Could not load the map. Please try again in a moment." | fetch_failed |
| "Unexpected error loading the map." | 없음: 시작 중 예기치 않은 오류 |
업로드된 데이터
게시된 지도는 작성자가 Studio의 데이터 패널에 추가한 데이터셋과 이미지 오버레이를 그립니다. iframe이 직접 로드하므로 옵션, 속성, 키가 필요 없고 데이터가 임베드 페이지를 거치지 않습니다.
| 동작 | 설명 |
|---|---|
| 표시 내용 | 게시된 지도에 포함된 모든 데이터셋과 이미지 오버레이를 작성자가 디자인한 레이어로 보여줍니다. |
| 읽을 수 있는 사람 | 지도를 열 수 있는 사람은 누구나 읽을 수 있습니다. 허용 도메인은 데이터를 비공개로 만들지 않습니다. |
| 방문자의 브라우저가 받는 내용 | 각 데이터셋 전체와 모든 열을 받습니다. 큰 데이터셋은 로드가 느립니다. |
| 데이터셋 로드 실패 시 | 해당 레이어 없이 나머지 지도가 그려집니다. |
| Studio 데이터 패널에서 데이터셋 삭제 | 데이터셋이 삭제되고 게시된 지도 및 해당 데이터를 표시하는 공유 링크에서 더 이상 제공되지 않습니다. 이미 로드한 브라우저는 데이터를 보유하며 이미 발행된 다운로드 링크는 최대 한 시간 동안 유효할 수 있습니다. |
| 지도 게시 취소 | 게시 ID를 통한 지도와 데이터셋 제공이 중단되고 iframe은 not_found를 표시합니다. 다시 게시하면 같은 ID가 복구됩니다. |
| 공유 링크 | 링크 생성 시점의 지도 디자인 스냅샷이며 게시를 취소해도 지도를 계속 보여 주지만, 지도를 다시 게시할 때까지 Kaleidr AI는 제공되지 않습니다. Studio에는 링크를 삭제하거나 일시정지하는 기능이 없습니다. 지도를 삭제하거나 소유자의 요청으로 Kaleidr가 링크를 제거할 때까지 작동합니다. 공유 링크를 참조하세요. |
게시된 지도에 업로드된 데이터에서 자세히 설 명합니다.
허용 도메인
지도 소유자는 Studio의 공유, 임베드, 특정 도메인에서 지도를 표시할 사이트를 제한할 수 있습니다.
- 목록에 있는 도메인은 하위 도메인도 포함합니다.
- 검사는 브라우저가 iframe 요청에 보낸 리퍼러의 호스트 이름을 목록과 비교합니다. 리퍼러가 없으면 검사가 실패합니다.
- 실패하면 '허용되지 않음' 메시지와 함께
domain_not_allowed를 전송합니다. - 이 검사로 거부된 조회는 지도 로드로 집계되지 않습니다.
사용량 측정
- 조회 1회는 지도 소유자 조직에 지도 로드 1회로 집계됩니다.
- 같은 방문자가 24시간 이내에 같은 지도를 다시 보면 추가로 집계되지 않습니다.
- Kaleidr 자체 사이트에서의 조회는 집계하지 않습니다.
- 할당량을 소진하면 재설정될 때까지 iframe에 제한 메시지가 나타납니다. 할당량과 요청 속도 제한을 참조하세요.
콘솔 메시지
| 메시지 | 의미 |
|---|---|
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" | 유효한 product가 없어 요소를 마운트하지 않습니다. |
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$. | ID가 비어 있거나 형식이 잘못됐습니다. |
[kaleidr:viewer] mount target not found: <selector> | Kaleidr.mount가 선택자에 일치하는 요소를 찾지 못했습니다. |
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js | 네트워크 오류, 차단 도구 또는 script-src 정책으로 Viewer 번들을 로드하지 못했습니다. |
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. … | Viewer가 지원하지 않는 핸들 메서드를 호출했습니다. |
지원하지 않는 기능
- 클릭, 카메라 이동, 선택 이벤트(장소 카드와 장소 작업 포함).
- 카메라, 지도 레이어 또는 데이터 읽기.
- 임베드된 지도에 자체 마커나 레이어 추가(차량 레이어 제외).
- 임베드에서 바탕지도 또는 테마 변경.