이 페이지는 Cloud Translation API를 통해 번역되었습니다.

장소 UI 키트로 양방향 매장 검색기 빌드

목표

이 문서에서는 Google Maps Platform, 특히 Maps JavaScript API 및 장소 UI 키트: 장소 세부정보 요소를 사용하여 대화형 매장 찾기 애플리케이션을 개발하는 주요 단계를 안내합니다. 매장 위치를 표시하는 지도를 만들고, 표시되는 매장 목록을 동적으로 업데이트하고, 각 매장에 대한 풍부한 장소 정보를 표시하는 방법을 알아봅니다.

기본 요건

다음 사항을 숙지하는 것이 좋습니다.

Maps JavaScript API - 페이지에 지도를 표시하고 Places UI Kit를 가져오는 데 사용됩니다.
고급 마커 - 지도에 마커를 표시하는 데 사용됩니다.
장소 UI 키트 - UI에 매장 정보를 표시하는 데 사용됩니다.

프로젝트에서 Maps JavaScript API 및 Places UI Kit를 사용 설정합니다.

시작하기 전에 Maps JavaScript API를 로드하고 고급 마커 및 장소 UI 키트에 필요한 라이브러리를 가져왔는지 확인합니다. 또한 이 문서에서는 HTML, CSS, JavaScript를 비롯한 웹 개발에 대한 실무 지식이 있다고 가정합니다.

초기 설정

첫 번째 단계는 페이지에 지도를 추가하는 것입니다. 이 지도는 매장 위치와 관련된 핀을 표시하는 데 사용됩니다.

페이지에 지도를 추가하는 방법에는 두 가지가 있습니다.

gmp-map HTML 웹 구성요소 사용
JavaScript 사용

사용 사례에 가장 적합한 방법을 선택하세요. 지도를 구현하는 두 가지 방법 모두 이 가이드에서 작동합니다.

데모

이 데모에서는 매장 찾기 기능이 작동하는 예를 보여주며, 샌프란시스코 베이 지역의 Google 사무실 위치를 표시합니다. 장소 세부정보 요소는 각 위치에 대해 일부 예시 속성과 함께 표시됩니다.

매장 위치 로드 및 표시

이 섹션에서는 매장 데이터를 로드하고 지도에 표시합니다. 이 가이드에서는 기존 매장에 관한 정보 저장소가 있어 여기에서 정보를 가져올 수 있다고 가정합니다. 스토어 데이터는 데이터베이스와 같은 다양한 소스에서 가져올 수 있습니다. 이 예에서는 각 매장 위치를 나타내는 매장 객체 배열이 있는 로컬 JSON 파일 (stores.json)이 있다고 가정합니다. 각 객체에는 name, location(lat 및 lng 포함), place_id이(가) 하나 이상 포함되어야 합니다.

아직 매장 위치의 장소 ID가 없는 경우 다양한 방법으로 검색할 수 있습니다. 자세한 내용은 장소 ID 문서를 참고하세요.

stores.json 파일의 스토어 세부정보 항목은 다음과 같습니다. 이름, 위치 (위도/경도), 장소 ID 필드가 있습니다. 매장 영업시간을 저장하는 객체가 있습니다 (잘림). 매장 위치의 맞춤 기능을 설명하는 데 도움이 되는 불리언 값도 두 개 있습니다.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

JavaScript 코드에서 매장 위치 데이터를 가져와 각 위치에 대해 지도에 핀을 표시합니다.

이 작업을 수행하는 방법의 예는 다음과 같습니다. 이 함수는 매장의 세부정보가 포함된 객체를 가져와 각 매장의 위치를 기반으로 마커를 만듭니다.

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

매장을 로드하고 매장 위치를 나타내는 핀이 지도에 표시되면 HTML과 CSS를 사용하여 개별 매장에 관한 세부정보를 표시하는 사이드바를 만듭니다.

이 단계에서 매장 찾기가 표시되는 방식의 예는 다음과 같습니다.

지도 표시 영역 변경사항 수신 대기

성능과 사용자 환경을 최적화하려면 해당 위치가 표시되는 지도 영역 (표시 영역) 내에 있는 경우에만 마커와 세부정보를 사이드바에 표시하도록 애플리케이션을 업데이트하세요. 여기에는 지도 뷰포트 변경사항을 수신하고, 이러한 이벤트를 디바운스한 다음, 필요한 마커만 다시 그리는 작업이 포함됩니다.

지도 유휴 이벤트에 이벤트 리스너를 연결합니다. 이 이벤트는 이동 또는 확대/축소 작업이 완료된 후에 발생하므로 계산을 위한 안정적인 뷰포트를 제공합니다.

map.addListener('idle', debounce(updateMarkersInView, 300));

위 코드 스니펫은 idle 이벤트를 수신 대기하고 debounce 함수를 호출합니다. 디바운스 함수를 사용하면 사용자가 잠시 동안 지도와의 상호작용을 중지한 후에만 마커 업데이트 로직이 실행되어 성능이 개선됩니다.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

위 코드는 디바운스 함수의 예입니다. 이 함수는 함수와 지연 인수(유휴 리스너에 전달됨)를 사용합니다. 300ms 지연은 UI에 눈에 띄는 지연을 추가하지 않고 지도가 이동을 멈출 때까지 기다리기에 충분합니다. 이 시간 제한이 만료되면 전달된 함수(이 경우 updateMarkersInView)가 호출됩니다.

updateMarkersInView 함수는 다음 작업을 실행해야 합니다.

지도에서 기존 마커를 모두 지웁니다.

스토어의 위치가 현재 지도 경계 내에 있는지 확인합니다. 예를 들면 다음과 같습니다.

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

위의 if 문 내에서 매장 위치가 지도 뷰포트 내에 있는 경우 마커를 표시하고 매장 세부정보를 사이드바에 저장하는 코드를 작성합니다.

장소 세부정보 요소를 사용하여 풍부한 장소 세부정보 표시

이 단계에서 애플리케이션은 모든 매장 위치를 표시하며 사용자는 지도 뷰포트를 기준으로 필터링할 수 있습니다. 이를 개선하기 위해 장소 세부정보 요소를 사용하여 사진, 리뷰, 접근성 정보와 같은 각 매장에 관한 풍부한 세부정보가 추가됩니다. 이 예에서는 특히 장소 세부정보 컴팩트 요소를 활용합니다.

데이터 소스의 각 매장 위치에는 해당하는 장소 ID가 있어야 합니다. 이 ID는 Google 지도의 위치를 고유하게 식별하며 세부정보를 가져오는 데 필요합니다. 일반적으로 이러한 장소 ID는 미리 획득하여 각 매장 기록에 저장합니다.

애플리케이션에 장소 세부정보 소형 요소 통합

매장이 현재 지도 뷰포트 내에 있고 사이드바에 렌더링되는 것으로 확인되면 해당 매장의 장소 세부정보 콤팩트 요소를 동적으로 만들어 삽입할 수 있습니다.

처리 중인 현재 매장의 장소 ID를 데이터에서 가져옵니다. 장소 ID는 요소가 표시될 장소를 제어하는 데 사용됩니다.

JavaScript에서 PlaceDetailsCompactElement 인스턴스를 동적으로 만듭니다. 새 PlaceDetailsPlaceRequestElement도 생성되고 장소 ID가 전달되며 이는 PlaceDetailsCompactElement에 추가됩니다. 마지막으로 PlaceContentConfigElement를 사용하여 요소에 표시할 콘텐츠를 구성합니다.

다음 함수는 필요한 장소 UI 키트 라이브러리가 가져와서 이 함수가 호출되는 범위에서 사용할 수 있고 함수에 전달된 storeData에 place_id이 포함되어 있다고 가정합니다.

이 함수는 요소를 반환하며 호출 코드는 DOM에 요소를 추가해야 합니다.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

위의 예시 코드에서 요소는 장소 사진, 리뷰 평점, 접근성 정보를 표시하도록 구성됩니다. 사용 가능한 다른 콘텐츠 요소를 추가하거나 삭제하여 맞춤설정할 수 있습니다. 사용 가능한 모든 옵션은 PlaceContentConfigElement 문서를 참고하세요.

장소 세부정보 컴팩트 요소는 CSS 맞춤 속성을 통한 스타일 지정을 지원합니다. 이를 통해 애플리케이션의 디자인에 맞게 모양 (색상, 글꼴 등)을 맞춤설정할 수 있습니다. CSS 파일에 이러한 맞춤 속성을 적용합니다. 지원되는 CSS 속성은 PlaceDetailsCompactElement 참고 문서를 확인하세요.

이 단계에서 애플리케이션이 표시되는 방식의 예:

매장 찾기 개선

매장 찾기 애플리케이션을 위한 견고한 기반을 구축했습니다. 이제 기능을 확장하고 더욱 풍부하고 사용자 중심적인 환경을 만드는 몇 가지 방법을 고려해 보세요.

자동 완성 추가

검색 입력을 Place Autocomplete과 통합하여 사용자가 매장을 검색할 지역을 찾는 방법을 개선합니다. 사용자가 주소, 동네 또는 관심 장소를 입력하고 추천을 선택하면 지도가 해당 위치를 자동으로 중심으로 표시되도록 프로그래밍하여 주변 매장이 업데이트되도록 합니다. 입력란을 추가하고 Place Autocomplete 기능을 연결하여 이를 달성합니다. 추천을 선택하면 지도가 해당 지점에 중앙에 배치될 수 있습니다. 결과가 운영 영역으로 편향되거나 제한되도록 구성해야 합니다.

위치 감지

현재 지리적 위치를 감지하는 기능을 구현하여 특히 모바일 사용자에게 즉각적인 관련성을 제공합니다. 위치를 감지할 수 있는 브라우저 권한을 획득한 후 자동으로 지도에서 사용자의 위치를 중앙에 배치하고 가장 가까운 매장을 표시합니다. 사용자는 즉각적인 옵션을 찾을 때 이 내 주변 기능을 매우 중요하게 생각합니다. 위치 정보 액세스를 요청하는 버튼이나 초기 프롬프트를 추가합니다.

거리 및 경로 표시

사용자가 관심 있는 매장을 식별하면 Routes API를 통합하여 사용자 여정을 크게 개선합니다. 나열된 각 매장에 대해 사용자의 현재 위치 또는 검색된 위치와의 거리를 계산하여 표시합니다. 또한 Routes API를 사용하여 사용자의 위치에서 선택한 매장까지의 경로를 생성하는 버튼이나 링크를 제공합니다. 그런 다음 지도에 이 경로를 표시하거나 Google 지도로 연결하여 매장을 찾는 것부터 실제로 매장에 도착하는 것까지 원활하게 전환할 수 있습니다.

이러한 확장 프로그램을 구현하면 Google 지도 플랫폼의 더 많은 기능을 사용하여 일반적인 사용자 요구사항을 직접 해결하는 더 포괄적이고 편리한 매장 찾기를 빌드할 수 있습니다.

결론

이 가이드에서는 대화형 매장 찾기를 빌드하는 핵심 단계를 설명했습니다. Maps JavaScript API를 사용하여 지도에 자체 매장 위치를 표시하고, 뷰포트 변경사항에 따라 표시되는 매장을 동적으로 업데이트하고, Places UI 키트에 따라 자체 매장 데이터를 표시하는 방법을 알아봤습니다. 장소 세부정보 요소를 사용하여 장소 ID를 비롯한 기존 매장 정보를 사용하면 각 매장에 대한 풍부하고 표준화된 세부정보를 표시하여 사용자 친화적인 매장 찾기를 위한 강력한 기반을 만들 수 있습니다.

Maps JavaScript API와 Places UI Kit를 사용하면 정교한 위치 기반 애플리케이션을 빠르게 개발할 수 있는 강력한 구성요소 기반 도구를 제공할 수 있습니다. 이러한 기능을 결합하면 사용자에게 흥미롭고 유익한 환경을 제공할 수 있습니다.

참여자

헨리크 밸브 | DevX 엔지니어

장소 UI 키트로 양방향 매장 검색기 빌드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

목표