← 블로그 Guides

실내 지도 API 및 SDK: 개발자를 위한 길 안내 통합 가이드

실내 지도 SDK를 평가하는 개발자들은 독점 API, 폐쇄형 생태계, 무거운 통합 방식이 뒤섞인 파편화된 시장에 직면합니다. 이 가이드에서는 임베드 방식부터 분석 웹훅까지 무엇이 중요한지 분석하여, 여러분의 기술 스택에 맞는 실내 내비게이션 기술을 선택할 수 있도록 도와드립니다.

실내 지도 통합 현황

실내 지도 시장은 빠르게 성숙해지고 있습니다. MarketsandMarkets에 따르면, 실내 위치 시장은 2027년까지 170억 달러에 도달하며 연평균 22.4% 성장할 것으로 예상됩니다. 하지만 벤더마다 개발자 경험은 천차만별입니다.

일부 플랫폼은 웹훅이 포함된 완전한 REST API, JavaScript SDK, iframe 임베드를 제공합니다. 다른 플랫폼은 자사의 네이티브 앱 생태계에 종속시키는 독점 모바일 SDK만 제공합니다. 벤더를 선택하기 전에 이러한 통합 수준의 차이를 이해하는 것이 필수적입니다.

길 안내 소프트웨어 비교에서는 기능 수준의 차이를 다룹니다. 이 가이드는 개발자 및 통합 관점에 특화되어 있으며, 기존 시스템에 실내 지도를 구축하기 위해 알아야 할 사항을 설명합니다.

임베드 기반 통합: 가장 간단한 방법

웹사이트, 인트라넷, 키오스크에 실내 지도를 추가하는 가장 빠른 방법은 iframe 또는 웹 컴포넌트 임베드입니다. QRCodeMaps는 모든 HTML 환경에서 작동하는 임베드 가능한 맵 URL을 제공합니다 — SDK 설치, 빌드 단계, 의존성 관리가 필요 없습니다.

임베드 기반 통합이 적합한 경우:

맞춤 개발 없이 건물 디렉토리가 필요한 사내 인트라넷. 웹 브라우저를 실행하는 방문자용 키오스크. 네이티브 바이너리를 배포하지 않고 지도를 원하는 모바일 웹 앱. 시설 레이아웃을 보여주고 싶은 마케팅 사이트.

단점은 커스터마이징입니다. 임베드 기반 지도는 플랫폼의 UI와 동작을 그대로 따릅니다. 지도 렌더링, 검색 동작, 상호작용 모델을 픽셀 단위로 제어해야 한다면 더 깊은 통합이 필요합니다.

JavaScript SDK 및 클라이언트 사이드 통합

JavaScript SDK는 임베드보다 더 많은 제어권을 제공하면서도 브라우저에서 실행됩니다. 우수한 실내 지도 JS SDK는 다음을 제공해야 합니다:

커스텀 컨테이너 요소를 사용한 프로그래밍 방식의 맵 초기화. 사용자 상호작용(마커 클릭, 검색 쿼리, 줌 변경)에 대한 이벤트 리스너. 특정 마커 강조, 초기 줌 레벨 설정, 표시 레이어 필터링을 위한 메서드. 색상, 폰트, UI 크롬에 대한 테마 옵션.

JS SDK 평가 시 번들 크기(맵 위젯 기준 gzip 압축 후 500KB 이상이면 과다), 트리 쉐이킹 지원, 프레임워크 호환성을 확인하세요. React 래퍼가 일반적이지만, React를 사용하지 않는 팀을 위해 바닐라 JS 지원도 중요합니다.

QRCodeMaps는 웹 퍼스트 접근 방식을 취하여 지도가 브라우저 네이티브이므로, 어떤 웹 환경에서든 통합에 최소한의 JavaScript만 필요합니다 — 종종 URL과 iframe, 그리고 초기 상태를 제어하는 쿼리 매개변수만으로 충분합니다.

REST API 및 서버 사이드 통합

서버 사이드 API를 통해 지도, 마커, 사이트를 프로그래밍 방식으로 관리할 수 있습니다. 일반적인 사용 사례는 다음과 같습니다:

직장 관리 시스템(IWMS)의 회의실 이름을 맵 마커에 자동으로 동기화. 병원 부서가 이전할 때 마커를 생성하거나 업데이트. CSV 또는 ERP 시스템에서 위치를 대량 가져오기. 비즈니스 인텔리전스 대시보드로 분석 데이터 가져오기.

잘 설계된 실내 지도 REST API는 사이트, 맵, 마커에 대한 CRUD 작업을 지원해야 합니다. 인증은 세션 쿠키가 아닌 API 키 또는 OAuth 토큰을 사용해야 합니다. 속도 제한은 문서화되어 있고 합리적이어야 합니다(관리 작업 기준 분당 100회 이상의 요청).

웹훅 지원도 마찬가지로 중요합니다. 변경 사항을 폴링하는 대신, 마커가 업데이트되거나 새 맵이 업로드되거나 스캔 활동이 임계값을 초과할 때 웹훅이 시스템에 알림을 보낼 수 있습니다. 이를 통해 지속적인 API 폴링 없이 실시간 통합이 가능합니다.

분석 및 웹훅 통합

길 안내 분석은 의사 결정이 이루어지는 시스템에 도달해야만 가치가 있습니다. 길 안내 성공을 위한 KPI는 별도의 사일로가 아닌 기존 대시보드에 반영되어야 합니다.

분석 API 엔드포인트는 일반적으로 다음을 제공합니다:

마커, 맵, 기간별 스캔 횟수. 결과 수가 포함된 검색 쿼리 로그. 결과 없음 검색 집계. 피크 사용 시간 및 히트맵 데이터.

웹훅 기반 분석은 실시간으로 데이터를 시스템에 푸시합니다. 모든 스캔 이벤트에 웹훅이 발동되도록 설정하면, 맞춤 알림을 구축할 수 있습니다(예: QR 코드가 30일간 스캔되지 않았을 때 시설팀에 알림 — 제거되었거나 손상되었을 수 있음).

Power BI, Tableau, Looker와 같은 도구를 사용하는 조직의 경우, JSON 응답이 포함된 REST 분석 API를 통해 직접적인 데이터 파이프라인 통합이 가능합니다. QRCodeMaps는 대시보드에서 검토하거나 외부 분석을 위해 내보낼 수 있는 스캔 및 검색 분석을 제공합니다.

인증, 멀티테넌시, 접근 제어

엔터프라이즈 통합에는 접근 제어에 대한 세심한 주의가 필요합니다. 실내 지도 API에 대해 확인해야 할 핵심 질문은 다음과 같습니다:

API가 조직 수준의 접근 제어를 지원하여 12개 건물을 운영하는 병원 시스템이 각 시설에 서로 다른 API 키를 부여할 수 있는가? 분석 소비자에게는 읽기 전용 접근을 허용하고 관리자 통합에는 쓰기 접근을 제한하도록 API 키 범위를 설정할 수 있는가? API 작업에 대한 감사 로깅이 있는가?

멀티테넌시는 관리형 서비스 제공업체, 부동산 관리 회사, 여러 시설을 운영하는 의료 시스템에 중요합니다. API는 데이터의 교차 오염 없이 단일 계정에서 여러 사이트를 생성하고 관리할 수 있어야 합니다.

QRCodeMaps는 사이트별 사용자 할당이 포함된 다중 사이트 관리를 지원하여, 중앙 감독을 유지하면서 개별 건물 관리자에게 맵 관리를 위임하기가 간편합니다.

적절한 통합 깊이 선택하기

모든 프로젝트에 전체 API 통합이 필요한 것은 아닙니다. 실제 요구 사항에 맞춰 통합 깊이를 결정하세요:

임베드만: 개발 노력 없이 웹사이트나 키오스크에 실내 지도를 원하는 경우. 구현 시간: 1시간 이내.

임베드 + 분석: 방문자를 위한 지도와 팀을 위한 스캔 데이터를 원하는 경우. 분석에는 플랫폼 대시보드를 사용합니다. 구현 시간: 오후 반나절.

API 기반 관리: 다른 시스템에서 위치 데이터를 동기화하고 마커 업데이트를 자동화하려는 경우. 구현 시간: 개발자 기준 수일.

전체 웹훅 통합: 실시간 분석을 BI 스택에 연결하고 길 안내 이벤트에 자동 대응하려는 경우. 구현 시간: 1~2주.

필요에 맞는 가장 간단한 통합부터 시작하세요. QRCodeMaps는 기본 임베드로 시작하여 요구 사항이 증가함에 따라 API 통합을 점진적으로 추가할 수 있도록 설계되었습니다 — 초기 설정을 재구성할 필요가 없습니다.