Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

장소 UI 키트가 포함된 매장 찾기

목표

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

기본 요건

다음에 익숙한 것이 좋습니다.

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

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

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

초기 설정

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

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

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

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

매장 위치 로드 및 표시

이 섹션에서는 지도에 매장 데이터를 로드하고 표시합니다. 이 가이드에서는 가져올 기존 매장에 대한 정보 저장소가 있다고 가정합니다. 매장 데이터는 데이터베이스와 같은 다양한 소스에서 가져올 수 있습니다. 이 예시에서는 각 매장 위치를 나타내는 매장 객체 배열이 있는 로컬 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 Platform의 더 많은 기능을 사용하여 일반적인 사용자 요구를 직접 해결하는 더 포괄적이고 편리한 매장 검색 기능을 빌드할 수 있습니다.

결론

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

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

참여자

헨릭 발브 | DevX 엔지니어

장소 UI 키트가 포함된 매장 찾기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

목표