지도 편집기 SDK는 사용자를 별도의 빌더로 이동시키지 않고 SaaS 제품 안에 지도 제작 또는 편집 기능을 추가합니다. 호스트 애플리케이션은 ID, 권한, 프로젝트, 결제, 데이터 소유권, 게시 정책을 계속 관리하고, SDK는 페이지 내부의 캔버스와 도구를 제공합니다. Kaleidr Editor는 자체 MapLibre 지도를 마운트하고, 오리진 제한이 적용된 게시 가능 키로 인증하며, 호스트가 영속성 방식을 정의할 때까지 편집 내용을 메모리에 유지합니다.
아래에서는 제품 책임 경계, 아키텍처, 마운트, 영속성, 보안, UX, 흔한 실수를 다룹니다. 실행 중인 렌더러에 대화 기능을 연결하려면 지도에 AI 채팅을 추가하는 방법을 참고하세요. 더 넓은 SDK 범주는 AI 지도 SDK란 무엇인가?를 참고하세요.
지도 편집기 SDK 핵심 사항
- 편집 화면과 제품의 역할: 편집기는 편집 캔버스를 담당하고, 호스트는 사용자, 프로젝트, 권한, 영속성, 출시를 담당합니다.
- 기본값은 메모리 저장: 독립형 Kaleidr Editor는 편집 내용을 영속화하지 않습니다. 출시 전에 저장과 게시를 설계하세요.
- 게시 가능 키 +
design:design스코프를 가진 오리진 제한 브라우저 키를 사용하고, 서버 키는 절대 노출하지 마세요.- 한 번 마운트하고 한 번 제거: 수명 주기를 SPA 라우트와 테넌트 전환에 연결하세요.
- 게시 권한 분리: 초안을 편집하는 권한과 공개 지도를 출시하는 권한은 같지 않습니다.
SaaS 제품에 지도 편집기 SDK를 어떻게 추가하나요?
이 가이드는 기존 SaaS 워크플로 안에 지도 제작 작업 공간을 배치합니다. 사용자는 프로젝트를 열고, MapLibre 캔버스에서 편집하고, 베이스맵 스타일을 선택하고, 사용 가능한 지도 도구를 이용한 뒤 SDK 상태를 남기지 않고 화면을 떠날 수 있습니다. 영속성 통합이 구현된 뒤에도 저장, 게시, 전달은 호스트가 제어합니다. 예제는 공유 로더를 통해 페이지 내부 Editor 제품을 문서화한 Kaleidr Editor를 사용합니다. 다른 서드파티 지도 편집기 SDK를 평가할 때도 동일한 소유권 모델을 적용할 수 있습니다.
지도 편집기 SDK는 Studio, Viewer, GIS와 어떻게 다른가요?
지도 편집기 SDK는 탐색, 선택, 그리기, 스타일 지정 및 관련 컨트롤과 같은 제작 도구를 다른 애플리케이션에 추가하는 재사용 가능한 구성 요소입니다. 호스트의 계정 시스템, 데이터베이스, 사용 권한, 감사 로그 또는 프로젝트 워크플로를 대체해서는 안 됩니다. 신뢰할 수 있는 경계는 편집기가 편집 화면을 담당하고, 호스트 제품이 사용자, 프로젝트, 권한, 영속성, 출시 결정을 담당하는 구조입니다.
| 제품 유형 | 주요 목적 | 가장 적합한 용도 |
|---|---|---|
| 지도 편집기 SDK | 제품 내 제작 또는 편집 | 사용자를 앱 안에 유지해야 하는 SaaS 워크플로 |
| 독립형 지도 빌더 | 전용 제작 애플리케이션 | 호스트 제품을 벗어나 작업할 수 있는 팀 |
| 게시 지도 Viewer | 읽기 전용 제공 | 고객 또는 대중의 지도 열람 |
| 지도 렌더러 | 카메라 및 레이어 API | 개발자가 완전히 맞춤 제작하는 지도 제품 |
| GIS | 공인 공간 작업 | 조직 소유의 분석 및 거버넌스 |
Kaleidr Studio는 Prompt → Process → Refine → Deploy 흐름으로 구성된 프롬프트 중심의 완전한 제작 제품입니다. Kaleidr Editor는 내장 가능한 편집 화면이고, Kaleidr Viewer는 게시된 지도를 표시합니다. 이 경로들은 렌더링과 스타일 개념을 공유하지만 서로 대체 가능한 제품 화면은 아닙니다.
SaaS 아키텍처에서는 편집기 상태를 어떻게 소유해야 하나요?
프로덕션 지도 편집 워크플로에는 제품 셸, 편집기, 자격 증명, 백엔드 정책, 데이터 시스템, 제공 단계에 걸친 명확한 책임 분리가 필요합니다. 호스트 SaaS는 ID, 테넌트, 탐색, 프로젝트, 결제, 권한, 워크플로를 담당합니다. Kaleidr Editor는 페이지 내부 편집 화면, MapLibre 지도, 수명 주기, 사용 가능한 클라이언트 도구를 담당합니다. 게시 가능 키는 브라우저에 Editor 제품과 design 기능에 대한 접근을 허용합니다. 호스트 백엔드는 권한 부여, 영속성, 버전 관리, 감사, 가져오기, 내보내기, 게시 정책을 담당합니다. 권위 있는 데이터 시스템은 데이터세트와 비즈니스 규칙을 소유합니다. Viewer 또는 다른 대상은 승인된 읽기 전용 결과를 제공합니다.
호스트 백엔드는 브라우저가 전달한 프로젝트 ID, 테넌트 ID, 데이터세트 ID 또는 게시 대상을 재승인 없이 신뢰하면 안 됩니다. 편집기를 마운트하면 지도 제작이 제품에 자연스럽게 통합되지만 브라우저는 여전히 신뢰할 수 없는 환경입니다. 공개 문서는 product: "editor"가 Editor 번들을 선택하고, 기본 진입 방식은 iframe이 아닌 attach/in-process이며, styleId는 카탈로그 베이스맵 ID 또는 전체 스타일 URL을 받고, 기본 베이스맵은 kaleidr-morning이며, 핸들은 항상 destroy()를 제공하고, 지원되는 경우 카메라와 테마 업데이트를 사용할 수 있다고 명시합니다. 독립형 임베드는 편집 내용을 영속화하지 않으며, 추가 백엔드 구성 없이는 전체 AI 기반 Studio 화면, Control Tower, 독립형 3D 애셋 라이브러리를 포함하지 않습니다.
Kaleidr Editor를 안전하게 마운트하려면 어떻게 해야 하나요?
API 키와 임베드를 위한 Pro 또는 Enterprise 접근 권한, design 스코프로 Editor 사용이 허용된 게시 가능 키, 개발·스테이징·프로덕션의 정확한 허용 오리진, 명시적 높이가 설정된 대상 요소, 시작 스타일, 호스트 프로젝트 및 권한 모델, 영속성 전략, SPA 정리 절차를 확인하세요. 버전이 지정된 로더를 https://cdn.kaleidr.com/embed/v1/kaleidr.js에서 한 번만 불러옵니다. 로더는 기본적으로 비활성 상태이므로 로드 전에 임베드를 활성화하거나 마운트마다 enabled 옵션을 전달하세요. 최소 마운트 예시는 다음과 같습니다.
const editor = Kaleidr.mount("#editor", {
product: "editor",
publishableKey: "kld_pk_live_REPLACE_ME",
styleId: "kaleidr-morning",
enabled: true
});
window.addEventListener("pagehide", () => {
editor.destroy();
});
예시 키를 실제 게시 가능 키로 교체하고, 편집 도구를 위한 충분한 캔버스 높이를 확보하며, 로드 또는 실패 상태를 지도 밖에서 알리세요. 이 예제는 현재의 Editor attach 참조, Editor 통합 가이드, kaleidr.js 로더 참조를 따릅니다. 공개 핸들 참조에 영속성 메서드가 문서화되지 않았으므로 에디터를 마운트할 뿐, 메모리 내 사양을 저장하지는 않습니다. 선언형 마크업만으로 충분하면 <kaleidr-map> 요소에서 product="editor", publishable-key, style-id를 지정할 수 있습니다. 호스트에 명시적 핸들이나 프레임워크가 관리하는 수명 주기가 필요하면 명령형 API를 사용하세요. React 또는 다른 SPA에서는 effect 안에서 한 번 마운트하고 정리할 때 destroy()를 호출하세요. 폼 필드가 바뀔 때마다 다시 마운트하지 마세요.
영속성, 보안, UX는 어떻게 계획하나요?
독립형 임베드는 편집 내용을 메모리에 유지합니다. 팀은 일반적으로 세 가지 경로 중 하나를 선택합니다. Editor를 프로토타입용 임시 화면으로 사용하거나, 사용자가 SaaS 셸을 벗어날 수 있다면 전체 제작을 Kaleidr Studio에서 수행하거나, 프로젝트 로드, 검증, 초안 저장, 버전 관리, 충돌 처리, 승인, 게시, 롤백, 감사를 포함한 호스트 통합 워크플로를 구축합니다. 공개 Editor SDK 참조에는 문서화되지 않은 저장 메서드나 변경 리스너처럼 추측해서는 안 되는 API가 없습니다. 고객 대상 저장 기능을 약속하기 전에 지원되는 상태 전송 접점을 Kaleidr에 확인하세요. 데이터세트 분석, 지도 사양 부분 적용, 스타일 또는 테마 카탈로그와 같은 플랫폼의 design 경로는 서버 키를 사용하는 호스트 백엔드에 배치해야 합니다. 브라우저의 Editor는 계속 SDK를 통해 게시 가능 키를 사용합니다.
게시 가능 키를 정확한 오리진으로 제한하고, 로컬 개발 외에는 HTTPS를 요구하며, 키를 design과 필요한 제품으로만 제한하고, 계정 또는 테넌트가 바뀔 때 편집기를 제거하세요. 백엔드에서는 모든 프로젝트와 데이터세트를 사용자와 테넌트별로 승인하고, 브라우저 상태와 별개로 소유권을 검증하고, 저장 또는 게시 전에 지도 사양을 검증하며, 초안·검토·게시 권한을 분리하세요. OWASP API Security Top 10은 객체 수준 권한 부여 실패를 주요 위험으로 봅니다. 브라우저가 제공한 프로젝트 ID만으로는 절대 충분한 승인이 되지 않습니다. 사용자가 편집 중인 프로젝트를 알 수 있도록 제품 셸을 계속 표시하고, 메모리 내 변경만으로 잘못된 “저장됨” 상태를 만들지 말고 저장과 게시 기능을 호스트 UI에 배치하세요. Viewer보다 더 많은 세로 공간도 확보해야 합니다. 편집기 영역에 접근 가능한 이름을 부여하고, 주변 작업에 대한 키보드 접근을 유지하고, 포커스 트랩을 피하고, 저장 및 오류 상태를 알리고, WCAG 2.2에 따라 가능한 경우 드래그 이외의 대안을 제공하세요.
| 실수 | 발생하는 문제 | 권장 수정 |
|---|---|---|
| 독립형 Editor가 작업을 영속화한다고 가정 | 세션 종료 시 사용자가 변경 내용을 잃음 | 영속성을 명시적으로 설계하고 통합 접점을 확인 |
| 문서화되지 않은 핸들 메서드를 추측 | 존재하지 않는 API에 프로덕션이 의존 | 문서화된 메서드만 사용 |
| 서버 키를 브라우저 코드에 노출 | 백엔드 bearer가 공개됨 | 오리진 제한 게시 가능 키 사용 |
| SDK를 활성화하지 않고 마운트 | 로더가 비활성 상태로 유지됨 | 임베드를 활성화하거나 enabled: true 전달 |
| 컨테이너 높이 생략 | 편집기가 축소되거나 사용할 수 없게 됨 | 충분한 반응형 높이 확보 |
| Editor와 Studio를 동일하게 취급 | 기대치가 독립형 임베드의 범위를 초과 | 내장 편집과 Studio의 전체 제작을 분리 |
| 브라우저의 테넌트 ID를 신뢰 | 테넌트 간 접근이 가능해짐 | 백엔드에서 모든 프로젝트를 재승인 |
| SPA 정리를 무시 | 중복 편집기와 리스너가 누적됨 | 핸들을 유지하고 destroy() 호출 |
최종 결론
지도 편집기 SDK를 사용하면 편집 캔버스, 렌더러 통합, 브라우저 인증 모델 전체를 처음부터 다시 구축하지 않고도 SaaS 제품에 지도 제작 기능을 추가할 수 있습니다. Kaleidr Editor는 현재 MapLibre 기반의 페이지 내 내장 화면을 제공하며, design 스코프가 있는 게시 가능 키로 인증합니다. 독립형 임베드는 편집 내용을 메모리에 유지하므로 에디터 마운트만으로 완전한 영속 제작 시스템이 제공되는 것은 아닙니다. 제품에 통합 편집 화면이 필요하고 호스트 팀이 프로젝트, 권한, 영속성, 게시, 감사 가능성을 담당할 경우 Editor SDK를 선택하세요. 별도의 완전한 제작 워크플로를 허용할 수 있다면 Kaleidr Studio를 선택하세요. 고객 대상 저장 기능을 약속하기 전에 상태 전송과 AI 지원 접점을 확인해야 합니다.
SaaS 제품에 지도 편집 기능 추가하기
버전이 지정된 JavaScript 로더, 오리진 제한 게시 가능 키, design 스코프로 Kaleidr Editor를 마운트하세요. 연결 옵션과 수명 주기는 **Editor 통합 가이드 읽기**를 참고하세요. 인증, design 엔드포인트, 호스트 통합 워크플로는 **개발자 문서**와 Enterprise 요구 사항을 검토하세요.
자주 묻는 질문
지도 편집기 SDK란 무엇인가요?
다른 애플리케이션에 지도 제작 또는 편집 도구를 추가하는 재사용 가능한 구성 요소입니다. 일반적으로 호스트 제품이 사용자, 프로젝트, 권한, 영속성, 게시를 관리합니다.
Kaleidr Editor를 SaaS 제품에 내장할 수 있나요?
예. 현재 SDK는 대상 요소 안에 마운트할 때 product: "editor"를 사용하도록 문서화합니다. Editor는 페이지에 자체 MapLibre 지도를 생성합니다.
독립형 Editor가 사용자의 지도를 저장하나요?
아니요. 공개 문서에 따르면 편집 내용은 메모리 내 사양에 존재하며 독립형 임베드가 영속화하지 않습니다. 출시 전에 호스트 영속성을 계획하세요.
Editor는 어떤 자격 증명을 사용하나요?
승인된 오리진으로 제한되고 design 스코프가 있는 브라우저 게시 가능 키를 SDK를 통해 사용하세요. 서버 키를 브라우저 코드에 넣지 마세요.
Kaleidr Editor와 Kaleidr Studio는 같은 제품인가요?
아니요. Studio는 프롬프트 중심의 완전한 제작 및 게시 제품입니다. Editor는 다른 애플리케이션 안에서 사용하는 내장형 편집 화면입니다.
References
- Kaleidr. Attach the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/guides/attach-the-editor
- Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
- Kaleidr. CORS & Allowed Origins. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
- Kaleidr. Editor — Mount the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/editor-attach
- Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/endpoints
- Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
- Kaleidr. Pricing & Plans. kaleidr.com. Accessed 3 August 2026. https://kaleidr.com/pricing
- MapLibre. Map — MapLibre GL JS. Accessed 3 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
- OWASP. OWASP Top 10 API Security Risks — 2023. Accessed 3 August 2026. https://owasp.org/API-Security/editions/2023/en/0x11-t10/
- World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 3 August 2026. https://www.w3.org/TR/WCAG22/
@misc{kaleidr_editor_attach,
title = {Editor -- Mount the Map Editor},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 3 August 2026},
url = {https://docs.kaleidr.com/sdk/editor-attach}
}
@misc{kaleidr_editor_guide,
title = {Attach the Map Editor},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 3 August 2026},
url = {https://docs.kaleidr.com/guides/attach-the-editor}
}
@misc{kaleidr_loader,
title = {kaleidr.js -- the Loader},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 3 August 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{kaleidr_auth_scopes,
title = {Auth and Scopes},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 3 August 2026},
url = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}
@misc{owasp_api_security,
title = {OWASP Top 10 API Security Risks -- 2023},
author = {{OWASP}},
note = {Accessed 3 August 2026},
url = {https://owasp.org/API-Security/editions/2023/en/0x11-t10/}
}
@misc{wcag22,
title = {Web Content Accessibility Guidelines 2.2},
author = {{World Wide Web Consortium}},
note = {Accessed 3 August 2026},
url = {https://www.w3.org/TR/WCAG22/}
}