웹사이트에는 직접 iframe, 재사용 가능한 웹 컴포넌트 또는 실시간 지도에 연결되는 JavaScript SDK를 사용해 인터랙티브 지도 경험을 삽입할 수 있습니다. 독립적으로 게시된 지도에는 iframe을, 관리되는 구현을 간단한 HTML로 사용할 때는 웹 컴포넌트를, 호스트가 카메라·수명 주기·제품 동작을 제어해야 할 때는 SDK를 선택하세요. 프로덕션 임베드에는 명시적 크기, 도메인 제어, 접근성, 검색 가능한 텍스트, 동작 분석도 필요합니다.
아래에서는 방식 선택, Kaleidr Viewer 설정, 반응형 컨테이너, 보안, 접근성, SEO, 일반적인 실수를 다룹니다. 실시간 렌더러에 대화 기능을 연결하는 방법은 지도에 AI 채팅을 추가하는 방법을 참조하세요. SDK 제품군 자체에 대한 설명은 AI 지도 SDK란 무엇인가?를 참조하세요.
지도 삽입 핵심 사항
- 방식을 먼저 선택: 코드 예제의 길이가 아니라 호스트 페이지에 필요한 제어 수준에 따라 iframe, 웹 컴포넌트, SDK 또는 네이티브 지도 라이브러리를 선택합니다.
- 높이 확보: 로드 전에 지도 컨테이너 높이를 명시해 영역 붕괴와 레이아웃 이동을 방지합니다.
- 게시된 Viewer: Kaleidr Viewer는
product="viewer"와 공유 ID를 사용하며, 공유 링크와 게시자가 허용한 도메인으로 접근을 제어합니다.- 캔버스 밖의 텍스트: 제목, 요약, 장소 목록을 제공해 키보드 사용자, 보조 기술, 검색 시스템에도 유용한 페이지를 만듭니다.
- 과업 측정: 지도 노출만이 아니라 로드, 선택, 길찾기, 전환을 추적합니다.
인터랙티브 지도 경험을 어떻게 삽입하나요?
이 가이드는 마케팅 사이트, 여행지 안내, 부동산 페이지, 매장 찾기, 기사 또는 소프트웨어 제품에 사용할 반응형 지도 섹션을 만듭니다. 완성된 환경에는 게시된 인터랙티브 지도, 데스크톱과 모바일에서 작동하는 컨테이너, 지도 밖의 명확한 제목과 텍스트 요약, 호스트 페이지의 선택적 카메라 제어, 도메인 또는 자격 증명 제한, 로드·실패 상태, 지도에만 표시된 정보를 대신할 접근 가능한 콘텐츠, 참여도를 측정하는 이벤트가 포함됩니다. 예제는 하나의 로더와 하나의 사용자 지정 요소로 게시 지도를 삽입하는 Kaleidr Viewer를 사용합니다. 같은 판단 기준은 공급자 iframe, 지도 웹 컴포넌트, Mapbox·Google Maps·MapLibre·Leaflet을 사용한 사용자 지정 구현에도 적용됩니다.
적합한 삽입 방식을 어떻게 선택하나요?
첫 번째 결정은 호스트 웹 사이트가 얼마나 많은 통제가 필요한지입니다.콘텐츠 페이지에 게시된 맵은 일반적으로 SaaS 워크플로 내에서 지도와 동일한 아키텍처가 필요하지 않으므로 기본적으로 가장 복잡한 메서드를 선택하지 마십시오.
| 방법 | 최고의 착용감 | 호스트 페이지 제어 | 주요 tradeoff |
|---|---|---|---|
| 직접 iframe | 자급자족 지도 또는 공급자 포함 | 낮은 | 가장 빠른 설정, 제한된 통합 |
| 웹 컴포넌트 | 간단한 HTML로 재사용 가능한 게시 된지도 | 미디엄 | 깨끗한 마크업; 동작은 구성 요소 계약에 따라 다릅니다. |
| 자바스크립트 SDK | 카메라, 라이프사이클, 이벤트 또는 AI와의 제품 통합 | 높음 | 더 많은 구현 책임 |
| 네이티브 지도 라이브러리 | 완전 사용자 정의 지도 응용 프로그램 | 가장 높은 | 최대 제어, 가장 큰 엔지니어링 표면 |
지도가 독립적으로 작동하고 호스트 페이지는 표시만 하면 되며 개발 작업을 최소화해야 할 때는 직접 iframe을 사용합니다. HTML iframe 요소는 별도의 임베디드 브라우징 컨텍스트를 만듭니다. 격리에는 유용하지만 자체 리소스와 접근성 고려 사항이 있는 별도의 문서 환경입니다. 선언형 HTML 요소를 원하고 지도 ID나 카메라 같은 속성으로 충분하며 공급자가 내부 구현을 유지할 때는 웹 컴포넌트를 사용합니다. 사용자 지정 요소는 안정적인 공개 계약 뒤에 로드와 메시징을 숨길 수 있습니다. 카메라나 테마 변경, 경로 전환 시 지도 제거, 실시간 렌더러 연결, 브라우저 인증, 이벤트 또는 AI 워크플로 조정이 필요하면 JavaScript SDK를 사용합니다.
Kaleidr Viewer 삽입은 어떻게 작동하나요?
Kaleidr Viewer는 공유 ID로 게시된 Kaleidr 지도를 삽입합니다. Viewer는 자체 지도를 관리하며 <kaleidr-map> 컴포넌트 내부의 iframe 경계에서 실행됩니다. 호스트 페이지는 SDK 핸들과 문서화된 메시징 인터페이스를 통해 지원되는 동작을 제어할 수 있습니다. 현재 계약에는 네 가지 핵심 특성이 있습니다. product="viewer"는 게시 지도 Viewer를 선택하고, share-id는 게시 지도를 식별하며, Viewer 접근은 공유 링크로 제한되어 API 키가 필요하지 않고, 게시자가 지정한 허용 도메인도 계속 적용됩니다. Viewer는 자체 지도를 관리하는 반면 Kaleidr Chat은 호스트 애플리케이션에서 이미 실행 중인 Mapbox, Google Maps, MapLibre 또는 Leaflet 인스턴스에 연결할 수 있습니다.
제품을 마운트하기 전에 버전이 지정된 로더를 https://cdn.kaleidr.com/embed/v1/kaleidr.js에서 한 번만 불러옵니다. 로더는 <kaleidr-map>을 정의하고 window.Kaleidr를 설치한 뒤 선택한 제품 번들을 필요할 때 로드합니다. 게시 지도를 최소 구성으로 삽입할 때는 사용자 지정 요소에 명시적인 높이를 지정합니다.
<kaleidr-map
product="viewer"
share-id="abcd1234"
style="display:block; height:520px;">
</kaleidr-map>
이 예제는 현재 빠른 시작, <kaleidr-map> 참조, Viewer 삽입 문서를 따릅니다. abcd1234를 게시된 지도의 공유 ID로 바꾸세요. 지도는 게시되어 있어야 하며 호스트 도메인에서 렌더링하도록 허용되어야 합니다. 공개 계약에 포함되지 않은 내부 Viewer URL을 직접 구성하지 말고 문서화된 컴포넌트를 사용하세요.
반응형·접근성 지도 페이지를 어떻게 만드나요?
내장된 맵은 노골적인 높이가 필요합니다.컨테이너가 없으면 컨테이너가 붕괴되거나 불안정한 레이아웃을 생성하거나 공급자별 기본값으로 돌아갈 수 있습니다.맵 로드 전에 공간을 예약하는 셸에 요소를 감싸십시오. 전체 너비, 최소 높이 및 종종 좁은 휴대폰에서 더 높은 고정 최소값으로 데스크톱의 16:9 종횡비입니다.공간을 예약하면 예기치 않은 레이아웃 이동이 줄어 듭니다. 정의 된 치수가없는 임베드는 누적 레이아웃 이동의 일반적인 원인입니다 (web.dev CLS 안내).종횡비에만 의존하지 않고 실제 맵을 테스트하십시오. 얕은 와이드 스크린 맵은 종종 데스크톱에서 작동하지만 휴대 전화에서 사용하기가 어려워집니다.
Viewer 요소는 지원되는 경우 center, zoom, pitch, bearing, theme을 관찰하며, center는 경도, 위도 순서를 사용합니다. 주요 지역, 개발과 대중교통, 명확한 검색 또는 필터가 있는 전국 보기처럼 지도의 목적이 분명해지는 초기 카메라를 선택하세요. 호스트 페이지에 핸들이 필요하면 로더가 준비된 뒤 명령형 API로 마운트합니다.
const viewer = Kaleidr.mount("#featured-map", {
product: "viewer",
shareId: "abcd1234",
center: [-0.12, 51.5],
zoom: 11
});
// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
viewer.destroy();
});
Kaleidr.mount()는 제품 번들이 로드되는 동안에도 동기적으로 핸들을 반환하며, 번들이 준비되기 전에 호출한 작업은 대기열에 들어갑니다. 핸들은 항상 destroy()를 제공하고 선택한 제품이 지원하면 setCamera() 또는 setTheme()도 제공할 수 있습니다. 단일 페이지 애플리케이션은 제거 작업을 경로 수명 주기에 연결해 반복 탐색으로 임베드가 중복 생성되지 않도록 해야 합니다.
대화형 지도가 필수 정보에 접근할 수 있는 유일한 방법이 될 수는 없습니다. WCAG 2.2는 액세스 가능한 웹 콘텐츠의 프레임 워크를 제공합니다.지도에 의미있는 제목과 레이블이 지정된 영역을 제공하고, 이름, 주소, 범주 및 작업과 동등한 위치 목록을 게시하고, 키보드 사용자가 함정없이지도에 도달하고 떠날 수 있음을 확인하고, 색상 전용 마커를 피하십시오.원시 iframe의 경우 "map"과 같은 일반 레이블이 아닌 설명 title 속성을 포함하십시오.
도메인, 성능, SEO를 어떻게 관리해야 하나요?
공유 ID는 제한 없는 공개 권한을 뜻하지 않습니다. Kaleidr Viewer는 공유 링크로 접근을 제한하며 게시자가 지정한 허용 도메인도 계속 적용됩니다. 승인된 사이트로 제한된 지도는 공유 ID를 안다는 이유만으로 다른 사이트에서 렌더링되지 않습니다. 프로덕션, 필요할 경우 www 변형, 스테이징, 지원되는 로컬 개발 환경을 도메인 목록에 포함하세요. Kaleidr의 현재 요금제에서는 Pro와 Enterprise가 임베드를 지원합니다. Viewer 자체에는 API 키가 필요하지 않지만 프로덕션 전에는 요금제, 지도 로드 한도, 게시 제어를 확인해야 합니다(요금).
지도를 의미 있는 응용 표면으로 취급합니다.로딩하기 전에 치수를 예약합니다.Lazy-load or defer below-the-fold maps when they are natess to the initial viewport—native (초기 뷰포트에 필수가 아닐 때 겹나치거나 겹치기 지도 아래를 연기 loading="lazy" 원시 iframe에 적용되는 반면 사용자 지정 구성 요소는 호스트 측 교차점 관찰자 또는 클릭-투-로드 외관이 필요할 수 있습니다.페이지의 기본 위-더-접힌 경험인 지도를 지연시키지 마십시오.한 페이지에 중복 맵 스택을 로드하지 말고 실제 장치에서 대화형, 타일 전송 및 모바일 메모리까지 로더 시간, 시간을 측정합니다.
호스트 페이지는 여전히 크롤링 가능한 설명 텍스트가 필요합니다.지도가 상단 근처에 포함 된 내용을 기록하고, 중요한 장소 또는 결론을 HTML로 게시하고, 설명 제목을 사용하고, 눈에 보이는 콘텐츠와 일치하는 경우에만 구조화 된 데이터를 추가합니다.JavaScript 렌더링이 검색 시스템에 대한 추가 단계를 도입하는 Google 문서 (JavaScript SEO 기본).맵 센터마다 다른 많은 거의 동일한 URL이 아닌 안정적인 정경 페이지 안에 임베드를 놓습니다.embed 단계가 적용되기 전에 지도 생성 및 게시 AI 인터랙티브 맵 빌더.
| 실수 | 무슨 일이 일어나는지 | 추천 수정 |
|---|---|---|
| 명시적 지도 높이 없음 | 지도가 무너지거나 레이아웃을 이동 | 로딩 전에 반응형 치수 예약 |
| 원시 내부 뷰어 URL 사용 | 호스트는 문서화되지 않은 세부 사항에 따라 다릅니다 | 사용 <kaleidr-map> 또는 Kaleidr.mount() |
| 도메인이 허용되지 않습니다. | 하나의 환경에서 작동, 생산 실패 | 정확한 승인된 배포 도메인 추가 |
| 모든 지도 즉시 로드 | 불필요한 JavaScript, 타일 및 데이터 | 아래 맵을 연기하거나 클릭 투로드 사용 |
| 지도 전용 콘텐츠 | 사용자와 검색 시스템은 필수 사실을 그리워 | 텍스트 요약 및 이와 동등한 위치 목록 추가 |
| SPA에서 분해 없음 | 중복 인스턴스 및 청취자 축적 | 핸들 유지 및 호출 destroy() |
| 지도 보기만 추적 | 노출은 작업 완료로 오인됩니다. | 선택, 방향, 세부 정보 및 전환 추적 |
| 개인 운영 데이터 포함 | 공유 가능한 표면이 잘못된 레코드를 노출합니다. | 승인된 애플리케이션 워크플로 사용 |
최종 결론
독립적인 공급자 지도로 충분하면 직접 iframe을 사용합니다. 관리되는 공개 계약에 기반한 간결한 선언형 삽입에는 웹 컴포넌트를 사용합니다. 호스트 애플리케이션에 카메라 제어, 수명 주기 관리, AI 상호 작용, 인증 또는 더 깊은 제품 통합이 필요하면 JavaScript SDK를 선택합니다. Kaleidr Viewer는 브라우저 API 키 없이 여러 웹사이트에서 일관되게 표시해야 하는 게시 지도용입니다. 호스트 페이지가 kaleidr.js를 로드하고 공유 ID를 전달하며 반응형 컨테이너를 확보하고 허용 도메인을 준수합니다. 올바른 임베드는 안정적으로 로드되고 목적을 설명하며 모바일과 키보드에서 사용할 수 있고, 필수 정보를 지도 밖에도 제공하며, 방문자가 측정 가능한 작업을 완료하도록 도와야 합니다.
게시된 Kaleidr 지도 삽입하기
Kaleidr Studio에서 지도를 게시하고 공유 ID를 복사한 다음, 버전이 지정된 JavaScript 로더로 Viewer를 추가하세요. 컴포넌트와 메시징 계약은 **Viewer 삽입 문서**에서 확인할 수 있습니다. 지도를 더 큰 제품 워크플로에 통합해야 한다면 **개발자 문서**에서 Chat, Editor, Tiles, 인증, Platform API를 검토하세요.
자주 묻는 질문
웹사이트에 인터랙티브 지도를 어떻게 삽입하나요?
게시된 지도 또는 공급자를 선택하고 지원되는 iframe, 웹 구성 요소 또는 JavaScript SDK를 페이지에 추가하고 응답 컨테이너를 예약하고 액세스를 구성하고 맵 외부에서 액세스할 수 있는 텍스트를 제공합니다.
iframe이 지도를 삽입하는 가장 쉬운 방법인가요?
보통은.iframe은 맵이 자급자족하고 페이지가 제어가 거의 필요하지 않은 경우 적합합니다.호스트가 안정적인 제품 계약, 카메라 업데이트, 수명 주기 제어, 이벤트 또는 AI 상호 작용이 필요한 경우 웹 구성 요소 또는 SDK가 더 좋습니다.
Kaleidr Viewer에 API 키가 필요한가요?
아니.현재 Viewer는 share-link gated이며 게시된 지도의 share ID를 사용합니다.Publisher-defined 허용 도메인 제한은 여전히 적용됩니다.
삽입된 지도를 반응형으로 만들려면 어떻게 하나요?
래퍼와 맵 노골적인 치수를 부여하고 전체 너비를 사용하고 최소 높이를 예약하고 좁은 화면의 높이 또는 레이아웃을 조정합니다.모바일에서 실제 제어 및 정보 패널을 테스트합니다.
JavaScript에서 삽입된 Kaleidr 지도를 제어할 수 있나요?
네.필수 뷰어 통합은 카메라 업데이트를 지원하고 항상 제공하는 핸들을 반환합니다. destroy() 분해를 위해.
참고 문헌
- Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
- Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
- Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
- Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
- Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
- Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
- Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
- MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
- MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
- World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
- web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls
@misc{kaleidr_viewer_embed,
title = {Viewer -- Embed a Published Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 2 August 2026},
url = {https://docs.kaleidr.com/sdk/viewer-embed}
}
@misc{kaleidr_loader,
title = {kaleidr.js -- the Loader},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 2 August 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{mdn_iframe,
title = {iframe: The Inline Frame Element},
author = {{MDN Web Docs}},
note = {Accessed 2 August 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}
@misc{w3c_wcag22,
title = {Web Content Accessibility Guidelines 2.2},
author = {{World Wide Web Consortium}},
note = {Accessed 2 August 2026},
url = {https://www.w3.org/TR/WCAG22/}
}
@misc{google_javascript_seo,
title = {Understand JavaScript SEO Basics},
author = {{Google}},
note = {Google Search Central; accessed 2 August 2026},
url = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}