게시된 지도 삽입하기

이 가이드를 마치면 Kaleidr Studio에서 만든 지도를 자체 웹페이지에 게시하고, 표시할 사이트를 제한하고, 로드 성공 여부를 확인할 수 있습니다. Free를 포함한 모든 요금제에서 지원합니다. 게시에는 Kaleidr 계정이 필요하지만 API 키는 필요하지 않습니다.

시작하기 전에

공개할 준비가 된 Kaleidr Studio의 지도.
수정할 수 있는 웹페이지. SDK 요소에는 <script> 태그가 필요하고 일반 iframe에는 HTML만 필요합니다.
콘텐츠 보안 정책을 사용한다면 https://map-embed.kaleidr.com 프레임과 SDK를 위한 https://cdn.kaleidr.com 스크립트를 허용하세요. Content Security Policy 참고.
테스트용 HTTP 서버(예: 폴더에서 npx serve . 실행).

1단계: 지도 게시

Studio에서 지도를 열고 Publish를 선택합니다. Publish & embed 페이지가 열립니다.
Project status에 Draft가 표시됩니다. Go Live를 누릅니다.

확인할 결과: 상태가 Live로 바뀌고 버튼은 Re-publish가 됩니다. 옆에 Unpublish가 나타나며, 아래 미리보기가 있는 Embed code 영역이 표시됩니다.

게시된 지도는 Go Live를 눌렀을 당시의 복사본이 아니라 Studio에 현재 저장된 상태를 보여줍니다. Studio는 수정하는 동안 저장하므로 게시 후 추가한 데이터세트를 포함한 모든 변경사항이 다음 삽입 지도를 로드할 때 공개됩니다. 이 경우 Re-publish를 다시 누를 필요가 없습니다. Re-publish는 새 게시 버전을 기록하며 ID, 링크, 삽입 코드를 유지합니다. 방문자가 보는 지도는 전후가 같습니다.

방문자에게 작업 중인 내용을 보여주지 않고 수정하려면 먼저 Unpublish를 누르고 완료 후 다시 게시하거나, 별도의 지도 사본에서 작업하세요. 게시 취소하면 다시 게시할 때까지 모든 삽입 지도가 중지됩니다.

게시에는 업로드한 데이터도 포함됩니다. Data 패널에서 추가한 데이터세트와 이미지 오버레이가 설정한 레이어 스타일로 방문자에게 표시됩니다. 공개하면 안 되는 정보가 포함된 경우 먼저 게시된 지도의 업로드 데이터를 확인하세요.

2단계: 삽입 코드 복사

Embed code 영역에는 두 가지 형식이 있습니다.

Studio 형식	제공 내용	사용할 상황
iFrame	게시된 지도를 가리키는 일반 `<iframe>`.	사이트 빌더, CMS, 위키처럼 자체 스크립트를 실행할 수 없거나 단순히 지도를 표시할 때.
Developer	SDK 로더와 `<kaleidr-map product="viewer">` 요소.	코드를 통해 카메라를 설정·이동하거나, 채팅을 올리거나, SPA에서 지도의 수명 주기를 관리할 때.

형식을 선택하고 Copy를 누르세요.

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>

Developer 형식:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js" async></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
  style="display:block;width:100%;height:480px;"></kaleidr-map>

YOUR_MAP_ID는 Studio가 코드에 넣는 지도 ID입니다. 영문자, 숫자 및 ., _, ~, -를 사용할 수 있으며 최대 100자입니다. 같은 ID가 두 형식 모두에서 작동합니다.

두 형식 모두 지도의 Kaleidr AI를 포함합니다. Control Tower가 켜져 있으면 Ask Kaleidr 패널이, Popup Window가 켜져 있으면 팝업의 AI 채팅이 제공됩니다. 게시된 지도의 Kaleidr AI를 참고하세요.

3단계: 페이지에 삽입하고 크기 조정

지도가 표시될 위치에 코드를 붙여 넣습니다.

확인할 결과: “Loading map…” 표시 후 Studio에 저장한 화면 범위의 지도가 나타납니다.

크기 설정 규칙:

일반 iframe: 다른 iframe처럼 width와 height를 설정합니다.
SDK 요소: 높이를 지정하세요. <kaleidr-map>은 기본적으로 display:block이므로 높이가 적용됩니다. 예제의 style="display:block; height:480px"를 그대로 사용해도 됩니다. Safari 16.4 이전에는 요소가 인라인으로 처리되어 height가 무시될 수 있으므로 특히 필요합니다. 스타일시트에서 두 값을 설정해도 됩니다.
```
kaleidr-map { display: block; height: 480px; }
```
지도는 요소의 전체 너비를 차지합니다. 마운트할 때 높이가 없다면 고정 500픽셀로 설정되며, 이후 높이를 지정해도 바뀌지 않습니다. 숨긴 탭이나 접힌 패널에서는 높이가 없을 수 있으므로 화면에 나타날 때 마운트하거나 명시적인 높이를 지정하세요.
반응형 높이는 height:60vh, aspect-ratio:16/9, flex/grid 셀처럼 실제 높이를 산출할 수 있는 CSS를 사용합니다.

4단계: 초기 카메라 설정(선택 사항)

지도는 작성자가 저장한 화면 범위에서 열립니다. 작성자는 데스크톱·태블릿·휴대폰에 각각 다른 보기를 저장하거나 콘텐츠 자동 맞춤을 설정할 수 있습니다. 후자는 프레임 너비에 따라 보기를 선택하고 크기 변경 시 다시 맞춥니다. 다른 곳에서 열려면 카메라를 지정하세요. center는 경도, 위도 순서입니다.

요소에서:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

일반 iframe에서는 URL에 camera=longitude,latitude,zoom을 추가합니다:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID?camera=-0.1276,51.5072,12&pitch=45&bearing=-20"
  width="100%" height="480" style="border:0;" loading="lazy"
  referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"></iframe>

페이지에서 지정한 카메라가 화면 크기별 설정 및 자동 맞춤을 포함한 작성자의 저장된 보기보다 우선합니다. 지정한 값만 덮어쓰고 나머지는 기존 값을 유지합니다. 카메라를 지정한 이후에는 프레임 크기 변경 시 자동 맞춤이 중단됩니다. 중요한 규칙: center 없이 지정한 zoom은 무시됩니다. pitch와 bearing은 각각 단독으로도 작동합니다.

확인할 결과: 기존 마커, 레이어, 업로드 데이터는 그대로 두고 지정한 카메라에서 열립니다.

지도가 로드된 뒤 카메라를 이동하려면 JavaScript로 마운트하고 핸들을 보관합니다:

<div id="map" style="height:480px"></div>
<button id="paris">Paris</button>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#map', {
    product: 'viewer',
    shareId: 'YOUR_MAP_ID',
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
  });
</script>

setCamera에 대해 알아둘 두 가지:

setCamera는 요소가 아니라 Kaleidr.mount가 반환한 핸들에 있습니다. document.querySelector('kaleidr-map').setCamera는 undefined입니다. 요소로 마운트한 지도에서는 center, zoom, pitch, bearing 속성을 바꾸세요. 애니메이션 없이 즉시 이동합니다.
Kaleidr.mount가 반환된 후 언제든 호출할 수 있습니다. iframe 준비 전에 호출한 명령은 대기했다가 준비 시 적용되므로 6단계의 kaleidr-embed:ready를 기다릴 필요가 없습니다. 초기 화면은 마운트 옵션으로 지정합니다.
나중에 설정한 카메라도 저장된 화면보다 우선하며 크기 변경 시 자동 재조정을 중단합니다. 생략한 필드는 현재 값으로 남습니다.

5단계: 지도를 표시할 사이트 제한(선택 사항)

기본적으로 게시 지도 ID를 가진 모든 사이트에서 표시할 수 있습니다. 제한하려면:

Studio에서 지도를 열고 Share를 선택합니다. 아직 게시하지 않았다면 게시되며, 대화상자를 열 때마다 새 공유 링크가 생성됩니다.
Embed 탭을 엽니다.
접근 설정을 Any domain에서 Specific domains로 바꿉니다.
도메인을 한 줄에 하나씩 입력합니다. 예:
```
example.com
blog.example.org
```
입력란 밖을 클릭합니다. Studio가 목록을 저장하고 Saved를 표시합니다.

확인할 결과: 목록에 있는 사이트에서는 표시됩니다. 다른 사이트에서는 “This map isn't allowed to render on this site. Please contact the map owner.”라는 메시지가 나타납니다.

도메인 일치 방식:

호스트 이름만 입력하세요. 앞의 https://는 무시됩니다. 경로나 포트는 입력하지 마세요.
하나의 도메인은 하위 도메인도 포함합니다. example.com은 example.com, www.example.com, shop.eu.example.com을 허용합니다.
제한을 유지하며 로컬 테스트하려면 localhost를 추가하세요.

검사는 리퍼러에 따라 달라집니다

지도는 iframe을 불러올 때 브라우저가 보낸 리퍼러를 읽어 허용 여부를 판단합니다. 리퍼러가 없으면 도메인 제한 지도를 렌더링하지 않습니다. 다음 상황에서 발생합니다:

페이지가 응답 헤더나 <meta name="referrer">에서 Referrer-Policy: no-referrer 또는 same-origin을 보냅니다.
iframe에 referrerpolicy="no-referrer"가 있습니다.
페이지를 file:// URL로 디스크에서 엽니다.
iframe URL을 브라우저 탭에서 직접 엽니다.

브라우저 기본 정책인 strict-origin-when-cross-origin은 출처를 보내므로 정상 작동합니다. 사이트 정책이 더 엄격하다면 일반 iframe에 referrerpolicy="no-referrer-when-downgrade"를 유지하거나 지도를 담는 페이지의 정책을 완화하세요.

지도 페이지가 다른 프레임 안에 들어 있다면 리퍼러는 바깥 프레임 주소입니다. 그 프레임의 도메인이 허용 목록에 있어야 합니다.

허용 도메인은 지도를 표시할 수 있는 위치만 제어하며, 지도와 데이터세트의 기밀성을 보장하지 않습니다. 게시된 지도의 업로드 데이터를 참고하고 비공개 자료를 게시하지 마세요.

6단계: 로드 및 오류 감지(선택 사항)

SDK에는 ready Promise가 없고 요소도 이벤트를 내보내지 않습니다. iframe은 두 가지 경우 페이지에 메시지를 보냅니다:

메시지	시점	필드
`kaleidr-embed:ready`	지도가 처음 그려졌을 때.	`type`, `id`(지도 ID), `source`(`"publish"` 또는 `"share"`)
`kaleidr-embed:error`	지도 로드나 일부 그리기에 실패했을 때.	`type`, `id`, `code`, `message`

window에서 수신하되 메시지가 어디서 왔는지와 어느 프레임이 보냈는지 모두 확인하세요:

const el = document.getElementById('locations'); // the <kaleidr-map> element

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = el.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    console.log('map loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    console.warn('map problem', msg.code, msg.message);
  }
});

일반 iframe에서는 event.source를 해당 iframe의 contentWindow와 비교합니다.

오류 메시지의 code는 다음 중 하나입니다:

`code`	의미	프레임에 표시되는 내용
`no_id`	iframe URL에 지도 ID가 없음.	“Couldn't find a map id in the URL.”
`not_found`	미게시, 게시 취소 또는 잘못된 ID.	“This map isn't available — it may have been unpublished, paused, or the link is incorrect.”
`domain_not_allowed`	도메인이 허용되지 않았거나 리퍼러 누락.	“This map isn't allowed to render on this site. Please contact the map owner.”
`map_loads_exhausted`	지도 소유 조직의 로드 한도 소진.	“This map has reached its map load limit. It will be available again when the owner's allowance resets.”
`fetch_failed`	네트워크 등으로 지도 가져오기 실패.	“Could not load the map. Please try again in a moment.”
`maplibre_error`	지도는 시작했지만 일부 그리기 실패. `message`에 상세 내용이 있음.	일부 누락된 지도.

시점 관련 참고 사항:

maplibre_error 외의 코드는 지도가 표시되지 않고 ready도 오지 않습니다.
maplibre_error는 ready 전후에 여러 번 도착할 수 있습니다. 지도를 사용할 수 없다는 뜻으로 단정하지 말고 경고로 처리하세요.
SDK는 iframe을 지연 로드합니다. 화면 아래쪽에 있는 지도는 스크롤로 근처에 도달하기 전까지 로드하지 않으므로 메시지도 오지 않습니다. 몇 초 동안 응답이 없다고 실패로 판단하지 마세요.
iframe은 SDK 내부용 kaleidr-embed: 메시지도 보냅니다. 공개 규약으로는 위 두 유형만 처리하고 나머지는 무시하세요.

전체 페이지 예시

index.html로 저장하고 YOUR_MAP_ID를 변경한 후 HTTP로 폴더를 제공하세요.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our locations</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #map { height: 480px; }
  </style>
</head>
<body>
  <h1>Our locations</h1>
  <p id="status">Loading the map…</p>

  <div id="map"></div>
  <p>
    <button id="london">London</button>
    <button id="paris">Paris</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('map');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'viewer',
      shareId: 'YOUR_MAP_ID',
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (!msg || typeof msg.type !== 'string') return;

      if (msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      } else if (msg.type === 'kaleidr-embed:error' && msg.code !== 'maplibre_error') {
        status.textContent = 'The map could not load (' + msg.code + ').';
      }
    });

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 12, duration: 800 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
    });
  </script>
</body>
</html>

동작 방식

항목	동작
초기 보기	작성자가 저장한 보기. 페이지가 카메라를 지정하면 각 필드에서 우선 적용.
스크롤	포인터가 지도 위에 있을 때 스크롤하면 Studio에서처럼 지도를 확대/축소. 포인터가 지도 밖에 있으면 스크롤은 페이지를 이동. 터치에서는 드래그로 지도를 이동하고 손가락을 모으거나 벌려 확대/축소.
업데이트	Studio에 현재 저장된 지도를 표시. 저장한 변경은 다음 로드에 나타나며 재게시 불필요.
업로드 데이터	지정한 레이어로 데이터세트와 이미지 오버레이 표시. 게시된 지도의 업로드 데이터 참고.
게시 취소	지도 사용 불가 메시지 표시. 다시 게시하면 같은 URL이 복구됨. 게시 취소 참고.
팝업	작성자가 활성화했을 때만 지도 클릭으로 장소 팝업 표시.
높이	마운트 시 요소의 높이. 없다면 고정 500픽셀.
로딩	SDK iframe은 화면에 가까워질 때 지연 로드.
키	필요 없음. viewer에 공개 키를 전달하면 불필요한 세션 요청이 생기며, 요청이 거부되면 지도도 표시되지 않음.

게시된 지도의 업로드 데이터

Studio의 Data 패널에 추가한 데이터세트는 게시되는 지도에 포함됩니다. 방문자는 각 데이터세트와 이미지 오버레이를 설정한 레이어로 봅니다. 일반 iframe, SDK 요소, 공유 링크가 모두 같습니다. 따로 켤 옵션은 없고 삽입 페이지에 키도 필요하지 않습니다.

게시 지도는 현재 저장된 상태를 보여주므로 게시 이후 추가한 데이터세트도 저장 즉시 공개됩니다. 다시 게시할 필요가 없습니다.

제공되는 데이터와 대상:

게시된 지도의 데이터만. 데이터세트는 게시 지도나 공유 링크에 포함된 경우에만 방문자에게 제공됩니다. 미게시 지도에만 있는 데이터는 제공하지 않습니다.
데이터세트 단독 조회 불가. 지도 데이터세트를 나열하는 기능이 없고, 해당 지도 없이 ID만으로 접근할 수 없습니다.
지도를 열 수 있는 사람은 데이터를 읽을 수 있습니다. 게시 지도는 공개입니다. 허용 도메인은 표시 위치만 제한하며 기밀성을 보장하지 않습니다.
표시 스타일에 사용하지 않은 열까지 모두 전송합니다. 방문자의 브라우저는 모든 행과 열을 수신합니다. 공개하면 안 되는 열은 파일에서 제거한 뒤 다시 업로드하세요.

데이터세트 제공을 중단하는 방법:

Studio 작업	게시 지도에 대한 영향	공유 링크에 대한 영향
Data 패널에서 데이터세트 삭제	데이터 제공이 중단되고 나머지 지도는 그대로.	해당 데이터 레이어 없이 지도 표시.
지도 게시 취소	데이터세트를 포함한 지도 전체 제공 중단.	영향 없음. 이전 데이터를 그대로 보여줌.

데이터셋을 삭제하려면 데이터 패널에서 해당 행의 휴지통 버튼을 선택하고 확인하세요. 데이터셋 삭제 또는 교체에 절차와 이후 실행하는 실행 취소의 효과가 설명되어 있습니다. 데이터셋을 표시하는 레이어만 삭제하는 것은 데이터셋 삭제와 다릅니다. 데이터셋 자체는 계속 저장되어 지도에 남으므로 방문자에게 계속 제공됩니다.

공유 링크는 지도 디자인의 스냅샷입니다. 링크를 만들 당시의 지도를 보여 줍니다. 이후 지도를 수정하거나 게시를 취소해도 링크에 표시되는 내용은 바뀌지 않습니다. 스냅샷에는 당시의 지도 이름, 허용 도메인 목록, Kaleidr AI 스위치도 포함되므로, 나중에 이를 변경해도 이미 만든 링크가 표시되는 위치나 제공하는 Kaleidr AI 기능은 바뀌지 않습니다. 다만 링크의 Kaleidr AI에는 지도도 필요합니다. 지도가 게시되어 있는 동안에만, 그리고 지도의 현재 허용 도메인에 포함된 페이지에서만 작동하므로 지도 게시를 취소하거나 도메인을 제거하면 중단됩니다. 비용은 지도 소유자가 부담합니다. 게시된 지도의 Kaleidr AI를 참고하세요.

공유 링크는 지도 디자인의 스냅샷입니다. 링크를 만든 시점의 모습을 보여주므로 이후 지도를 수정하거나 게시 취소해도 바뀌지 않습니다. 다만 데이터세트는 예외입니다. 공유 링크는 지도와 동일한 저장 데이터를 읽으므로 데이터세트를 삭제하면 해당 데이터를 표시하던 모든 링크에서도 사라집니다.

Studio에서 Share 대화상자를 열면 지도가 게시되고 매번 새로운 공유 링크가 만들어집니다. 여러 번 공유한 지도에는 생성 당시의 모습을 가진 링크가 여러 개 있습니다.

Studio에는 공유 링크를 삭제하거나 일시 정지하는 기능이 없습니다. 데이터를 삭제하거나 Kaleidr에 링크 제거를 요청할 때까지 작동합니다. 최신 지도를 공유하려면 다시 Share를 열어 새 링크를 사용하세요. 이전 링크는 이전 상태를 계속 표시합니다.

지도 게시 취소

Publish & embed 화면에서 게시 중인 지도에는 Re-publish 옆에 Unpublish가 있습니다. Studio는 게시 취소 시 삽입 지도가 중단되지만 기존 공유 링크는 유지된다는 내용을 확인합니다. 진행하려면 Unpublish, 유지하려면 Cancel을 누르세요.

모든 지도 삽입이 중단됩니다. 프레임에 사용 불가 메시지가 표시되고 not_found를 보냅니다.
지도 ID는 유지됩니다. 다시 Go Live를 누르면 기존 URL과 코드가 변경 없이 복구됩니다.
이미 전달한 공유 링크는 이전 데이터로 계속 작동합니다. 단, 지도를 다시 게시할 때까지 공유 링크의 Kaleidr AI는 중단됩니다.

모든 곳에서 중단되는 시점이 즉각적이지는 않습니다:

브라우저는 이미 로드한 데이터를 보유합니다. 지도를 열어 둔 방문자는 레이어를 계속 볼 수 있고, 브라우저는 최근 몇 분 사이의 데이터를 다시 사용할 수 있습니다.
기존 다운로드 링크는 최대 1시간 유효할 수 있습니다. 큰 데이터세트의 경우 임시 다운로드 URL을 발급합니다. 삭제 또는 게시 취소 이전에 발급된 링크는 만료까지(최대 1시간) 사용할 수 있습니다.

로드 방법:

각 방문자는 데이터세트 전체를 다운로드합니다. 지도를 이동할 때 나누어 불러오지 않습니다. 행과 열이 많으면 특히 느린 연결에서 표시가 오래 걸립니다. 필요한 내용만 게시하세요.
데이터세트를 로드하지 못해도 지도 전체가 중단되지는 않습니다. 해당 레이어 없이 나머지를 표시합니다.

업로드 제한은 데이터세트 제한을 참고하세요.

조회수 집계 방식

방문자가 삽입 지도를 로드할 때마다 삽입한 사이트가 아니라 지도 소유 조직에 지도 로드 1회가 집계됩니다. 같은 방문자가 24시간 안에 같은 지도를 다시 열어도 중복 집계하지 않습니다. Studio 미리보기 등 Kaleidr 자체 페이지의 조회도 집계되지 않습니다.

해당 기간의 지도 로드 한도를 모두 사용하면 초기화될 때까지 제한 메시지를 표시하고 map_loads_exhausted를 보냅니다. 요금제별 한도는 쿼터와 속도 제한을 참고하세요.

정상 작동 확인

페이지: Studio의 Data 패널에서 설정한 마커, 경로, 데이터세트, 이미지가 레이어로 표시되고 확대/축소 버튼이 작동하며 지도 아래에 출처 표시가 나타납니다.
콘솔: [kaleidr가 포함된 오류가 없습니다.
Network 탭: https://map-embed.kaleidr.com/embed/YOUR_MAP_ID의 문서 요청이 200입니다. SDK 사용 시 https://cdn.kaleidr.com의 kaleidr.js, viewer.js도 표시됩니다.
리스너: kaleidr-embed:ready 메시지를 한 번 받습니다.

작동하지 않는 경우

증상	원인	해결
`height`를 바꿔도 항상 500픽셀	마운트 시 높이가 없거나 `display:inline`, Safari 16.4 이전에서 `display:block` 없음.	표시 중에 `display:block`과 높이를 지정하여 마운트.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` 속성이 없거나 잘못됨.	`product="viewer"` 설정.
지도 ID 오류	`share-id` 누락 또는 허용되지 않는 문자.	Studio에서 ID 다시 복사. `[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.`
`[kaleidr:viewer] mount target not found: #map`	요소 생성 전에 실행되었거나 선택자가 틀림.	요소 다음에 실행하고 선택자 확인. `Kaleidr.mount`
`Kaleidr is not defined`	`async`로 로드한 `kaleidr.js`보다 코드가 먼저 실행됨.	`async`를 제거하거나 `load` 이벤트 사용.
지도를 사용할 수 없다는 메시지	게시 전, 게시 취소 또는 ID 오타.	Go Live로 게시하고 ID 확인.
허용되지 않은 도메인	허용 목록에서 빠졌거나 리퍼러 없음.	목록 또는 리퍼러 정책 변경.
지도 로드 한도 메시지	조직의 로드 한도 소진.	초기화를 기다리거나 한도 확대. 쿼터와 속도 제한 참고.
“Could not load the map”	네트워크 문제 등으로 가져오기 실패.	새로고침하고 네트워크 및 iframe URL 확인.
CSP `frame-src` 위반	iframe 차단.	`https://map-embed.kaleidr.com` 허용. `frame-src`
CSP `script-src` 위반	로더 차단.	`https://cdn.kaleidr.com` 허용 또는 일반 iframe 사용. `script-src`
`setCamera`가 작동하지 않음	요소에서 호출했거나 지도가 준비되지 않음.	`Kaleidr.mount` 핸들을 쓰고 `kaleidr-embed:error` 및 콘솔 확인. 지도 준비 완료 알림이 제한된 대기 시간(일반적으로 iframe 로드 후 10초) 내에 오지 않아도 호출은 전송되며 콘솔에 `[kaleidr] the map frame has not reported ready`가 표시됩니다. 오류가 표시되는 프레임에는 이동하거나 변경할 지도가 없습니다.
`el.setCamera is not a function`	요소에서 메서드 호출.	핸들 사용 또는 속성 변경. `setCamera` Kaleidr.mount
페이지 스크롤이 지도에서 멈춤	정상 동작. 포인터가 지도 위에 있으면 스크롤로 지도를 확대/축소.	포인터를 지도 옆에 두고 스크롤. 방문자가 지도를 지나 스크롤할 수 있도록 지도 높이를 화면 높이보다 작게 지정.
수정이 표시되지 않음	저장 전 삽입 지도가 로드됨.	다시 로드. 재게시 불필요.
원치 않는 변경이 공개됨	게시 지도는 현재 저장 상태를 표시함.	실행 취소. 비공개 작업은 게시 취소 또는 복사본 사용. 참조
데이터 레이어 누락	삭제 또는 일시적인 로드 실패.	Data 패널을 확인하고 다시 로드.
큰 데이터가 늦게 표시됨	모든 방문자가 전체 데이터 다운로드.	행과 열 축소. 게시된 지도의 업로드 데이터 참고.

제한 사항

삽입 지도는 읽기 전용입니다. 페이지에서 마커나 레이어를 추가하거나 데이터 및 클릭 이벤트를 받을 수 없습니다.
페이지가 받는 신호는 kaleidr-embed:ready와 kaleidr-embed:error뿐입니다.
삽입 상태에서는 지도의 스타일과 기본 지도를 변경할 수 없습니다. Studio에서 바꾸면 다음 로드에 적용됩니다.
마운트 후 share-id를 바꿔도 반영되지 않습니다. 새 요소를 넣거나 handle.destroy() 후 다시 마운트하세요.
허용 도메인은 브라우저 리퍼러에 의존하며 보안 비밀이 아닙니다.

다음 단계

Viewer 참조: 옵션, 속성, 메시지.
게시된 지도의 Kaleidr AI: 방문자 질문 허용.
지도 데이터세트: 파일, 제한, 열 역할.
프레임워크 통합: React, Next.js, Vue에서 마운트와 해제.
Content Security Policy: 사이트에 보안 정책이 있는 경우.

시작하기 전에​

1단계: 지도 게시​

2단계: 삽입 코드 복사​

3단계: 페이지에 삽입하고 크기 조정​

4단계: 초기 카메라 설정(선택 사항)​

5단계: 지도를 표시할 사이트 제한(선택 사항)​

6단계: 로드 및 오류 감지(선택 사항)​

전체 페이지 예시​

동작 방식​

게시된 지도의 업로드 데이터​

공유 링크​

지도 게시 취소​

조회수 집계 방식​

정상 작동 확인​

작동하지 않는 경우​

제한 사항​

다음 단계​