지도 편집기 연결하기

이 가이드를 마치면 Kaleidr 기본 지도 위에 브랜드에 맞춘 지도 편집 도구를 페이지에 표시할 수 있습니다. Free를 포함한 모든 요금제에서 사용할 수 있으며, 새 키에 기본으로 포함되는 design 권한 범위의 게시 가능 키가 필요합니다.

편집 내용은 저장되지 않습니다

임베디드 편집기는 작업 내용을 페이지 메모리에만 보관합니다. 임베드에서 저장, 내보내기, 게시를 할 수 없고 변경 콜백도 제공되지 않습니다. 새로고침 또는 handle.destroy() 호출 시 작업은 사라집니다. 영구적으로 보관할 지도가 필요하다면 Kaleidr Studio에서 만들고 Viewer로 삽입하세요.

시작하기 전에

kaleidr.com/api-keys에서 발급한 게시 가능 키(kld_pk_live_…). API 키 받기를 참고하세요.
테스트할 페이지의 출처(예: http://localhost:3000)가 키의 허용 출처에 포함되어야 합니다. 허용 출처가 지정되지 않은 키는 모든 사이트에서 사용할 수 있습니다.
npx serve . 등 HTTP로 페이지를 제공하는 방법.
사이트가 콘텐츠 보안 정책을 사용한다면 Content Security Policy에 나온 편집기 지시문을 허용하세요. 편집기는 페이지 안에서 실행되므로 iframe 제품과 달리 connect-src, img-src, worker-src, font-src, style-src 설정이 필요합니다.
같은 페이지에 Kaleidr 편집기가 이미 없어야 합니다.

1단계: 크기를 지정한 컨테이너를 만들고 마운트하기

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

예상 결과: 컨테이너에 세계 범위의 Kaleidr 기본 지도(조직에서 다른 기본값을 지정하지 않았다면 kaleidr-morning)가 채워지고 Create 버튼이 표시됩니다. Create를 선택하면 텍스트, 이미지, 마커, 팝업 도구가 있는 편집기 사이드바가 열립니다.

컨테이너에는 높이가 있어야 합니다. 편집기는 컨테이너 너비와 높이의 100%를 사용하며 패널은 컨테이너 안에 유지됩니다.

사용자 지정 요소도 이용할 수 있습니다. 기본값이 display:block이므로 높이가 적용되며, 예제에는 Safari 16.4 이전 버전을 위해 display:block도 명시합니다.

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

2단계: 기본 지도와 시작 카메라 선택하기

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

예상 결과: 런던 중심부 위에 기울고 회전된 어두운 기본 지도가 표시됩니다.

기본 지도 선택 순서:

styleId를 전달했다면 해당 스타일을 사용합니다. kaleidr-morning, kaleidr-afternoon, kaleidr-evening, kaleidr-night, kaleidr-plain, kaleidr-editorial 등이 있습니다. 설명은 Tile 참조를 확인하세요.
그렇지 않으면 조직의 기본 지도가 설정되어 있을 때 이를 사용합니다.
그마저 없으면 kaleidr-morning을 사용합니다.

카메라 기본값은 중심 [0, 0], 줌 2, 기울기 0, 회전 0입니다. Viewer 및 Tile과 달리 편집기는 center 없이 zoom을 허용합니다.

Kaleidr.mount에 전달한 카메라 옵션이 유한한 숫자가 아니면 무시하고 콘솔에 알립니다. 요소의 카메라 속성이 숫자가 아니면 별도 메시지 없이 제외합니다.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

3단계: 패널 테마 설정(선택)

theme를 전달하여 편집기 패널을 제품 디자인에 맞춥니다. 이 객체는 지정된 이름의 키 최대 17개를 지원하며 목록에 없는 키는 무시합니다.

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

예상 결과: 활성 도구, 포커스 표시와 기본 버튼에 브랜드 색상이, 패널에는 지정한 글꼴이 적용됩니다.

모든 17개 키는 편집기 참조에 나와 있습니다.

알아둘 세 가지 사항:

값은 CSS 값입니다. brandColor에는 CSS 색상, cardRadius에는 CSS 길이, fontPrimary에는 font-family 값을 지정할 수 있습니다. 글꼴은 직접 로드하세요.
편집기를 마운트한 동안 테마가 문서 전체에 적용되고 제거 시 원래대로 복원됩니다. 같은 사용자 지정 속성을 쓰지 않는 한 자체 스타일은 변경되지 않습니다.
테마는 마운트 시 한 번만 읽습니다. 편집기는 handle.setTheme를 지원하지 않습니다. 테마를 바꾸려면 편집기를 제거하고 다시 마운트해야 하며 편집한 내용은 사라집니다.

요소에서 theme는 JSON 문자열입니다:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

4단계: 페이지에서 카메라 이동하기(선택)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

예상 결과: 지도가 파리로 이동합니다. 사용자가 지도에 배치한 항목은 원래 위치에 남아 있습니다.

setCamera는 페이지가 편집기의 지도에 작용할 수 있는 유일한 방법입니다. 핸들은 지도 객체를 노출하지 않습니다.

5단계: 제거하기

handle.destroy();

destroy()는 컨테이너에서 편집기, 지도, 패널을 제거하고 테마 값을 복원합니다. 편집 내용은 삭제됩니다.

단일 페이지 앱에서는 편집기를 소유한 경로나 컴포넌트가 사라질 때 destroy()를 호출하세요. 사용자 지정 요소를 사용한다면 문서에서 요소를 제거하는 것도 같습니다. 프레임워크 통합을 참고하세요.

한 페이지에 편집기 하나만 존재할 수 있으므로 새 편집기를 마운트하기 전에 항상 기존 편집기를 제거하세요.

전체 페이지 예제

index.html로 저장하고 키를 입력한 뒤 키가 허용하는 출처에서 HTTP로 폴더를 제공하세요.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

동작 방식

항목	동작
실행 위치	문서 내부. 지도 캔버스와 편집기 패널은 마운트 대상의 요소입니다.
세션	SDK가 편집기 시작 전에 키를 단기 세션으로 교환하며 마운트한 동안 갱신합니다.
편집 내용	메모리에만 남으며 저장, 내보내기, 게시 또는 페이지에 통지되지 않습니다.
기본 지도	페이지에서 `https://tile.kaleidr.com`를 통해 로드하고 마운트 시 고정됩니다.
테마	마운트 시 문서 전체에 적용되며 제거 시 복원됩니다.
카메라	마운트 시 설정하고 `handle.setCamera`로 움직입니다.
사용량	편집기 세션 요청은 지도 로드로 계산하지 않으며 임베디드 편집기에는 AI 크레딧을 사용하는 기능이 없습니다. 키가 포함된 기본 지도 요청은 일괄적으로 지도 로드에 반영되며, 한 시간에 요청 20회마다 지도 로드 1회로 계산됩니다. 지도 로드를 참조하세요.
이벤트	준비, 변경, 오류 콜백을 제공하지 않습니다.

사용자에게 알리기

편집기 자체에는 작업이 임시라는 경고가 없습니다. 사용자가 시간을 들여 편집한다면 위 전체 예제처럼 UI에 이를 표시하여 나중에 지도를 다시 찾을 수 있다고 생각하지 않도록 하세요.

정상 작동 확인

페이지: 기본 지도가 컨테이너를 채우고 Create 버튼으로 사이드바를 열어 텍스트나 마커를 배치할 수 있습니다.
콘솔: [kaleidr가 포함된 오류가 없습니다.
네트워크: https://cdn.kaleidr.com의 kaleidr.js, editor.js, 상태 200의 POST …/sdk/sessions, 그리고 https://tile.kaleidr.com의 스타일 및 지도 타일 요청이 나타납니다.

작동하지 않을 때

SDK는 마운트 실패를 [kaleidr:editor] … 형태로 콘솔에 기록합니다. 세션 거절의 경우 HTTP 상태만 기록하며 이유는 네트워크 탭의 sessions 응답에서 확인합니다. 403은 detail에 코드가, 429는 error에 코드가 있고 설명은 detail에 있습니다.

증상	원인	해결 방법
아무것도 표시되지 않고 `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }` 출력	키를 전달하지 않음.	`publishableKey`를 전달합니다.
`…/sdk/sessions`에 CORS 오류와 `[kaleidr:editor]` 가져오기 오류가 발생함	키가 잘못되거나 취소되었거나 출처가 허용되지 않음.	키를 확인하고 kaleidr.com/api-keys에서 프로토콜, 호스트, 포트를 포함한 정확한 출처를 추가한 후 몇 분 기다립니다.
`[kaleidr:editor] kaleidr session exchange failed (403)`	`design` 권한 없음(`insufficient_scope`), 다른 제품 전용(`product_not_allowed`) 또는 요금제에서 거절(`tier_capability_not_allowed`).	네트워크의 `detail`을 확인하고 기본 권한이 포함된 키를 만듭니다.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	서버 키를 브라우저에 전달함.	게시 가능 키를 사용하고 이전에 공개했다면 서버 키를 교체합니다.
컨테이너가 비어 있고 높이가 없음	마운트 대상의 높이가 없음.	높이를 지정하고 Safari 16.4 이전에는 `display:block`도 추가합니다.
패널만 표시되고 지도가 비어 있으며 `https://tile.kaleidr.com`에서 `"error":"tile_access_restricted"`를 포함한 429를 반환함	기본 지도 호스트가 요청을 거부함.	유효한 게시 가능 키와 허용 출처를 확인하고 변경 후 잠시 기다렸다 다시 로드하세요. 지속되면 지원팀에 연락하세요. `[kaleidr:editor] …`
패널만 표시되고 콘솔에 CSP 위반이 출력됨	정책이 기본 지도, 워커 또는 이미지를 차단함.	Content Security Policy의 편집기 지시문을 추가합니다.
편집기에 스타일이 없음	CSP가 인라인 스타일을 차단함.	`style-src`에 `'unsafe-inline'`을 허용합니다.
두 번째 편집기가 잘못 동작하거나 첫 번째가 멈춤	편집기가 두 개 마운트됨.	첫 번째를 제거합니다.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	테마는 마운트 시에만 적용됨.	마운트 시 `theme`를 전달합니다.
`[kaleidr] theme string must be JSON…`	`theme`가 JSON 객체가 아님.	속성 바깥에는 작은따옴표를, JSON 내부에는 큰따옴표를 사용합니다.
테마 키가 적용되지 않음	잘못되거나 지원되지 않는 키는 경고 없이 무시됨.	목록을 확인합니다.
편집 내용이 사라짐	페이지 새로고침, 편집기 제거 또는 요소 이동/삭제.	예상된 동작입니다. 상단 주의사항을 확인하세요.

제한 사항

임베드에서는 저장, 내보내기, 게시할 수 없습니다.
변경 콜백, 준비 상태 알림, 오류 콜백이 없습니다.
지도 객체에 접근할 수 없어 사용자 지정 레이어나 그린 내용 읽기를 지원하지 않습니다.
데이터 탭, 디자인 카탈로그, AI 패널, 3D 모델 라이브러리, 공유, 프로젝트는 없습니다. 도구 메뉴에는 Text, Image, Marker, Popup, Background, Layer, Design, Legend가 있으며 범위를 참고하세요.
페이지당 편집기 하나만 허용됩니다.
마운트 후 기본 지도와 테마를 변경할 수 없습니다.

다음 단계

편집기 참조: 모든 옵션과 테마 키.
프레임워크 통합: React, Next.js, Vue에서 마운트 및 제거하기.
Content Security Policy: 편집기용 지시문.
게시한 지도 임베드: 영구 지도가 필요할 때.

시작하기 전에​

1단계: 크기를 지정한 컨테이너를 만들고 마운트하기​

2단계: 기본 지도와 시작 카메라 선택하기​

3단계: 패널 테마 설정(선택)​

4단계: 페이지에서 카메라 이동하기(선택)​

5단계: 제거하기​

전체 페이지 예제​

동작 방식​

사용자에게 알리기​

정상 작동 확인​

작동하지 않을 때​

제한 사항​

다음 단계​