본문으로 건너뛰기

Viewer

Viewer를 사용하면 Kaleidr Studio에서 게시한 지도를 자신의 페이지에 배치할 수 있습니다. 지도는 Kaleidr가 호스팅하는 iframe 안에서 렌더링되므로 페이지에 지도 라이브러리를 불러오거나 API 키를 사용할 필요가 없습니다. 게시된 지도 ID만 있으면 됩니다.

Studio에 지도가 이미 있고 방문자에게 보여주려면 Viewer를 사용하세요. 매장 찾기, 캠퍼스 지도, 행사 경로, 기사 속 데이터 지도 등에 적합합니다.

한눈에 보기​

질문답변
무엇이 필요한가요?게시된 지도 ID. API 키나 세션이 필요하지 않습니다.
어떤 요금제인가요?Free를 포함한 모든 요금제. 게시하려면 Kaleidr 계정이 필요합니다.
어떻게 표시되나요?https://map-embed.kaleidr.com에서 제공하는 iframe 안에 표시됩니다.
무엇이 표시되나요?작성자가 게시한 지도: 마커, 경로, 스타일을 적용한 레이어, Studio 데이터 패널에서 업로드한 데이터셋과 이미지 오버레이.
어떻게 임베드하나요?일반 <iframe> 또는 SDK의 <kaleidr-map product="viewer"> 요소를 사용합니다.
비용은 얼마인가요?조회 1회마다 지도 소유 조직에 지도 로드 1회가 계산됩니다.
페이지에서 지도를 제어할 수 있나요?카메라 설정과 이동, 로드·오류 메시지 수신만 가능합니다.

최소 임베드​

<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>

YOUR_MAP_ID를 게시 후 Studio의 임베드 코드에 표시되는 ID로 바꾸세요. 요소는 기본적으로 display:block이므로 height가 적용됩니다. 예제에서 display:block을 명시한 이유는 Safari 16.4 이전 버전에서는 요소가 인라인으로 남아 height를 무시하기 때문입니다.

페이지에 스크립트를 추가할 수 없다면(웹사이트 빌더, CMS, HTML을 허용하는 뉴스레터 도구 등) Studio에서 생성한 iframe을 대신 사용하세요.

<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>

두 방식 모두 같은 지도를 표시합니다. 게시 지도 임베드에서 각각의 선택 기준을 설명합니다.

작동 방식​

  1. Studio에서 지도를 게시하면 ID와 임베드 코드가 발급됩니다.
  2. 페이지가 코드를 불러옵니다. SDK 요소 또는 일반 iframe은 https://map-embed.kaleidr.com/embed/YOUR_MAP_ID를 가리킵니다.
  3. iframe 내부 페이지가 게시 지도를 가져와 작성자가 업로드한 데이터셋 및 이미지 오버레이와 함께 그립니다. 허용 도메인 목록이 있으면 먼저 페이지 도메인이 포함되는지 확인합니다.
  4. 지도가 그려지면 iframe에서 페이지로 kaleidr-embed:ready 메시지를 보냅니다. 그릴 수 없는 경우 kaleidr-embed:error를 보내고 지도 대신 짧은 설명을 표시합니다.

페이지는 지도 데이터를 받지 않으며 iframe 내부에 접근할 수도 없습니다. 지도 라이브러리, 스타일, 네트워크 요청이 모두 iframe 안에 있으므로 콘텐츠 보안 정책에서 프레임만 허용하면 됩니다.

방문자가 할 수 있는 일​

  • 지도를 이동·회전·기울이고, 지도 위 확대/축소 버튼이나 두 손가락 동작, 스크롤 휠로 확대할 수 있습니다. 포인터가 지도 위에 있을 때 스크롤하면 Studio에서처럼 지도가 확대/축소됩니다. 포인터가 지도 밖에 있으면 스크롤은 페이지를 이동합니다.
  • 브라우저가 권한을 요청한 뒤 위치 버튼으로 현재 위치를 표시할 수 있습니다.
  • 작성자가 Studio에서 활성화했다면 지도를 클릭해 장소 팝업을 열 수 있습니다.
  • 지도 범례와 하단의 출처 표시를 읽을 수 있습니다.
  • 작성자가 Studio의 Kaleidr AI 타일에서 Control Tower를 켜면 Ask Kaleidr 패널에서, Popup Window를 켜면 팝업에서 지도에 관해 Kaleidr AI에 질문할 수 있습니다. 게시된 지도의 Kaleidr AI를 참고하세요.

임베드된 지도는 읽기 전용입니다. 방문자는 편집할 수 없고 방문자의 작업도 저장되지 않습니다.

페이지에서 할 수 있는 일​

  • 초기 카메라 설정: center, zoom, pitch, bearing를 사용합니다. 기본값은 작성자가 저장한 보기입니다. 페이지에서 전달하는 카메라 필드가 각각 우선합니다.
  • 나중에 카메라 이동: handle.setCamera(...)를 사용하거나 요소의 카메라 속성을 변경합니다.
  • 지도 로드 또는 실패 확인: iframe이 보내는 두 메시지를 수신합니다.
  • 지도 제거: handle.destroy()를 호출하거나 요소를 제거합니다.

지도 소유자를 위한 제어 기능​

이 설정은 임베드 코드가 아닌 Studio에서 사용할 수 있습니다.

  • 게시 및 게시 취소. 게시된 지도는 Studio에 현재 저장된 상태를 보여줍니다. 저장한 수정은 다시 게시하지 않아도 다음 임베드 로드부터 공개됩니다. 다시 게시는 동일한 링크를 유지하면서 새 게시 버전을 기록합니다. 비공개로 수정하려면 먼저 게시를 취소하고 작업이 끝나면 다시 게시하세요. 게시 취소는 지도의 모든 임베드를 중단하며, 다시 게시하면 같은 URL이 복원됩니다. 지도 게시 취소를 참고하세요.
  • 업로드한 데이터. 게시 지도에 그리는 데이터셋과 이미지 오버레이는 방문자에게 표시됩니다. 데이터 제공을 중단하려면 데이터 패널에서 데이터셋을 삭제하거나 지도의 게시를 취소하세요. 공유 링크는 게시 취소 후에도 작동하지만 데이터셋을 삭제하면 공유 링크에서도 제거됩니다. 게시 지도는 공개되어 있으므로 누구나 읽어도 되는 데이터만 게시하세요. 게시 지도에 업로드한 데이터를 참고하세요.
  • 허용 도메인. 지도를 표시할 수 있는 사이트를 제한합니다. 페이지에서 보내는 리퍼러를 확인하므로 리퍼러를 보내지 않는 페이지에는 도메인 제한 지도를 표시할 수 없습니다.
  • Kaleidr AI. 지도의 Kaleidr AI 타일에서 Ask Kaleidr 패널(Control Tower)과 팝업의 AI 채팅(Popup Window)을 켭니다.

제한 사항​

  • 키가 없으므로 허용된 출처 같은 키 기반 제한은 적용되지 않습니다. 지도에 허용 도메인을 설정하세요.
  • 페이지에서 지도 레이어를 읽거나 마커를 추가하거나 클릭 이벤트를 받을 수 없습니다.
  • 임베드는 높이를 자동 조정하지 않습니다. 요소나 iframe에 높이를 지정하세요.
  • 소유 조직이 기간의 지도 로드 한도를 소진하면 한도가 초기화될 때까지 지도 대신 안내 메시지가 나타납니다.
  • 방문자는 지도가 표시하는 각 데이터셋 전체를 다운로드하므로 큰 테이블을 사용한 지도는 느리게 표시됩니다.

다음 단계​