전체 인터페이스를 구축하지 않고도 사이트에 모빌리티 지도를 통합하려면 ROOTE iframe을 사용하세요. 이 임베드는 페이지에 맞는 도시 검색과 필터를 받을 수 있습니다: 자전거 가이드용 자전거, 화장실 가이드용 화장실, 교통편용 버스 및 트램 필터가 있습니다.
이 가이드의 예시는 임베드 도메인 embed.roote.ai를 사용하며, 이는 ROOTE 가이드에 통합된 도메인입니다. 일반 문서에는 map.roote.ai 통합도 설명되어 있고 카메라 매개변수와 전체 검색 매개변수를 구분합니다.
반응형 iframe 추가하기
이 블록은 줌 15로 보르도에서 자전거 검색을 엽니다. URL은 코드 내에서 생성되며, iframe의 제목은 화면 낭독기 사용자용으로 내용을 설명합니다. 페이지 언어에 맞게 이 제목을 조정하세요.
<iframe
title="Carte ROOTE — vélos à Bordeaux"
src="https://embed.roote.ai/?q=Bordeaux&modes=bicycle&zoom=15"
width="100%"
height="480"
loading="lazy"
allow="geolocation"
style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>HTML 속성에서 구분자 '&'는 '&'로 작성해야 합니다. 너비 100%는 컨테이너 너비를 따릅니다. 모바일에서 사용할 수 있는 높이를 유지하고 필수 컨트롤이 화면 밖에 나오지 않도록 하세요.
페이지에 맞는 모드 선택하기
| 필요 | 임베드 매개변수 |
|---|---|
| 자전거 | modes=bicycle |
| 화장실 | modes=toilets |
| 버스 | modes=bus |
| 트램 | modes=tram |
| 버스 및 트램 | modes=bus,tram |
| 자전거 및 화장실 | modes=bicycle,toilets |
이 값들은 '모빌리티', '서비스', '환승' 분류에 연결된 ROOTE 임베드 경로의 값들입니다. 이는 REST 매개변수를 대체하지 않으며, 서비스는 'types'를, 환승은 'modes'를 사용합니다. 도시 중심 지도가 모든 분류에 결과를 보장하지는 않습니다.
카메라와 검색 출처 구분하기
lat와 lon은 카메라 위치를 지정합니다. 그러나 문서화된 지도 계약상 인근 검색을 만들기엔 충분하지 않습니다. 알려진 검색을 복원하려면 search_lat, search_lon, search_label, 모드와 줌을 사용하세요.
https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram위 좌표는 사용자 위치가 아니라 보르도의 기준점입니다. 카메라 매개변수를 추가하면 거리 계산에 사용된 지점을 유지하면서 다른 영역을 표시할 수 있습니다. 분리된 사용 의도가 있을 때만 이렇게 하세요.
특수 문자를 잃지 않고 URL 생성하기
수동 연결 대신 URL과 URLSearchParams를 사용하세요. 이는 공백, 악센트, 구분자를 인코딩합니다. 이 코드는 브라우저용이며 입력된 위치로 iframe 주소를 생성합니다.
const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();전체 지도와 컨텍스트 유지하기
map.roote.ai에 대한 링크는 알려진 경우 현재 검색 상태를 반영해야 합니다. 매개변수 없는 URL 재생성은 도시, 모드, 줌을 잃게 됩니다. 페이지에서 업데이트할 때 공통 URL 객체를 유지하세요.
const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';이 코드는 상위 페이지에서 알려진 매개변수를 유지합니다. iframe 내 사용자가 검색을 변경하더라도 상위 도메인에서 iframe URL을 직접 읽을 수 없습니다. 상태를 얻으려면 출처 검증이 포함된 postMessage 교환 같은 명시적 구현과 문서화된 메커니즘이 필요합니다. 임베드가 제공하지 않는 이벤트 이름을 임의로 만들지 마세요.
위치 및 모바일 상호작용 관리하기
allow="geolocation"은 iframe에 위치 요청 권한을 부여합니다. 이는 사이트의 동의 및 권한 정책이 허용하는 경우에 한합니다. 거부해도 도시 검색은 계속 사용 가능해야 합니다. 사용자가 명시적으로 선택하지 않은 경우 페이지 도착 시 위치를 요구하지 마세요.
기사 내에서 지도를 수동으로 활성화하면 읽기 중 스크롤이나 줌이 제스처를 방해하지 않게 할 수 있습니다. 컨트롤은 키보드 접근이 가능하고 명확히 명명되어야 합니다. 방향 전환과 좁은 화면도 확인하고, 데스크톱 버전에만 국한하지 마세요.
결과 및 오류 상태 확인하기
각 필터, 알려진 도시, 데이터가 적은 영역, 잘못된 검색, 이용 불가능한 분류를 테스트하세요. 마커 없는 지도는 단독으로 검색 결과 없음과 오류를 구분하지 못합니다. 임베드 메시지와 전체 지도 접근을 유지하세요.
자주 묻는 질문
iframe에 API 키를 넣어야 하나요?
여기에 표시된 공개 URL에는 포함되지 않습니다. 시크릿 값은 임베드 URL이나 클라이언트 코드에 두지 마세요.
zoom=15가 검색 반경을 늘리나요?
줌은 보기 영역을 조절합니다. API 요청 반경과 동일하게 여기지 말고 사용하는 인터페이스의 검색 매개변수를 확인하세요.
상위 페이지가 iframe 내 변경을 알까요?
전달하는 매개변수는 알지만 내부 변경은 문서화된 도메인 간 교환 메커니즘이 필요합니다.