본문으로 건너뛰기

Tile

Tile은 Kaleidr 기본 지도를 페이지에 추가합니다. kaleidr-morning 또는 kaleidr-night 같은 스타일을 선택하면 SDK가 Kaleidr에서 호스팅하는 iframe에 표시합니다. 페이지에서 별도의 지도 라이브러리를 불러올 필요가 없습니다.

직접 지도 위에 그릴 필요 없이 보기 좋은 대화형 기본 지도가 필요할 때 Tile을 사용하세요. 위치 배경, '오시는 길' 패널, Kaleidr 채팅의 답변이 표시되는 지도 등에 적합합니다.

이미 Mapbox, MapLibre, Google Maps 또는 Leaflet 지도를 직접 운영하고 있다면 Tile은 필요하지 않습니다. 기존 지도에 Chat을 연결하세요.

한눈에 보기​

질문답변
무엇이 필요한가요?게시용 키(kld_pk_live_…)와 maps 범위가 필요합니다. 새 키에는 기본적으로 포함됩니다.
어떤 요금제인가요?Free를 포함한 모든 요금제입니다.
어떻게 표시되나요?https://map-embed.kaleidr.com에서 제공하는 iframe 안에 표시됩니다.
모양은 어떻게 선택하나요?style-id로 선택합니다. 아래에 범용 스타일 6개가 나와 있습니다.
비용은 얼마인가요?Tile 세션당 지도 로드 1회입니다. 지도 로드 계산 방식을 참조하세요.
페이지에서 지도를 제어할 수 있나요?카메라 위치 설정·이동, 스타일 교체, 로드 및 오류 메시지 수신이 가능합니다.

최소 임베드​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

작동하려면 세 가지가 필요합니다.

  1. 키. kaleidr.com/api-keys에서 게시용 키를 만듭니다. API 키 발급을 참고하세요.
  2. 허용된 출처. 키에 허용된 출처 목록이 있다면 페이지의 출처가 포함되어야 합니다. 파일을 디스크에서 직접 열지 말고 HTTP 또는 HTTPS로 제공하세요.
  3. 높이. 요소의 기본값은 display:block이므로 height가 적용됩니다. 예제에는 Safari 16.4 이전 버전에서 요소가 인라인으로 남는 문제를 위해 display:block도 명시합니다.

스타일​

style-id모양
kaleidr-morning밝은 스타일: 흰색 지면, 청록색 물, 흰색 도로.
kaleidr-afternoon중간 톤의 지면, 녹색 식생, 회색 도로.
kaleidr-evening골든아워: 따뜻한 모래색과 올리브색.
kaleidr-night어두운 남색과 차콜색, 호박색 주요 도로.
kaleidr-plain경계와 장소 이름이 있는 흰색 바탕. 확대 수준 15부터 3D 건물이 나타납니다.
kaleidr-editorial라벨을 끈 오후 색상 구성으로, 작거나 장식적인 지도에 적합합니다.

항상 style-id를 전달하세요. 생략하면 설정되어 있는 조직의 기본 지도를 사용하며, 기본 지도가 없으면 오류가 표시됩니다.

작동 방식​

  1. SDK가 게시용 키를 Kaleidr로 보내 짧은 수명의 Tile 세션을 받습니다. 이 단계에서 키, 범위, 페이지 출처를 확인하고 지도 로드 1회를 계산합니다. 설정된 경우 조직의 기본 지도 정보도 응답에 포함됩니다. Tile 세션의 용도는 여기까지이며, 지도는 세션으로 추가 요청을 보내지 않습니다.
  2. SDK가 요소 내용을 요청한 스타일의 iframe으로 바꿉니다. 프레임 URL에는 스타일 ID와 전달한 카메라 정보만 들어가며 게시용 키나 세션 토큰은 들어가지 않습니다.
  3. 지도는 iframe 내부에서 그려집니다. 페이지의 콘텐츠 보안 정책에는 로더, 세션 요청, 프레임을 허용하면 됩니다.
  4. 지도 렌더링이 끝나면 iframe이 페이지에 kaleidr-embed:ready 메시지를 보냅니다.

방문자가 할 수 있는 일​

지도를 이동하거나 회전·기울일 수 있고, 지도 버튼이나 손가락 확대, 스크롤 휠로 확대할 수 있습니다. 포인터가 지도 위에 있을 때 스크롤하면 지도가 확대/축소되고, 포인터가 지도 밖에 있으면 스크롤은 페이지를 이동합니다.

페이지에서 할 수 있는 일​

  • 초기 카메라 설정: center, zoom, pitch, bearing를 사용합니다.
  • 나중에 카메라 이동: handle.setCamera(...)를 사용합니다.
  • 스타일 전환: handle.setStyle('kaleidr-night')로 새로고침 없이 변경합니다.
  • 채팅 패널 연결: 채팅 마운트를 Tile 요소에 연결하여 답변을 지도 위에 표시할 수 있습니다.
  • 로드 완료 확인: kaleidr-embed:ready 메시지를 수신합니다.

지도 로드 계산 방식​

Tile 사용량은 게시된 지도의 조회에 적용하는 것과 같은 지도 로드 단위로 측정됩니다. SDK가 Tile 세션을 받을 때마다 지도 로드 1회가 계산됩니다.

  • 지도가 마운트될 때 한 번.
  • 마운트가 유지되는 동안 SDK가 세션 만료 직전에 세션을 갱신할 때마다 한 번. 기본 세션 시간은 15분입니다.
  • 마운트를 해제했다가 다시 마운트하거나 요소를 제거했다가 다시 삽입할 때 한 번.

방문자가 몇 분간 페이지를 보면 지도 로드 1회가 사용됩니다. 페이지를 한 시간 열어 두면 약 5회가 사용됩니다. '페이지 조회당 1회'가 아니므로 더 이상 표시하지 않는 Tile 마운트는 해제하세요.

조직이 해당 기간의 지도 로드 허용량을 모두 사용하면 새 Tile 세션은 HTTP 429로 거부됩니다. 새로 마운트한 지도는 표시되지 않습니다. 이미 페이지에 있는 지도는 그대로 유지됩니다. 할당량 및 요청 빈도 제한을 참조하세요.

제한 사항​

  • Tile은 기본 지도입니다. 페이지에서 자체 마커, 레이어, 팝업을 추가하거나 클릭 및 카메라 이벤트를 받을 수 없습니다. 연결된 채팅 패널은 지도에 장소를 표시할 수 있습니다.
  • Kaleidr 기본 지도를 표시하는 지원 방식은 Tile 제품입니다.
  • 마운트된 요소의 style-id를 변경해도 아무 효과가 없습니다. handle.setStyle를 사용하거나 요소를 새로 삽입하세요.
  • Tile 전용 별도 키는 없습니다. 다른 Kaleidr 제품의 게시용 키를 Tile에도 사용합니다.

다음 단계​