Android용 Maps SDK는 Wear OS 앱을 비롯한 Android 앱에 Google 지도 데이터, 지도 표시, 지도 동작 응답을 추가합니다. Kotlin 또는 Java를 사용하여 마커, 다각형, 오버레이를 추가하여 지도 위치에 관한 정보를 표시하고 사용자 상호작용을 지원할 수 있습니다.
Android용 Maps SDK: 주요 정보
- 제품: Android용 Maps SDK
- 다른 이름: Google Maps Android API
- 카테고리: 지도
- 플랫폼: Android
- 실행 위치: 클라이언트(앱 또는 브라우저 코드)
- 출시 단계: GA
- 수명 주기: 활성
- 개요: Android용 Maps SDK 개요
- 신청 가능 지역: 전 세계 Google Maps Platform 서비스 범위 페이지를 참고하세요. 사용량 및 결제 페이지 링크는 전 세계 가격 목록과 인도 가격 목록을 구분합니다. (보증 범위 세부정보)
Android용 Maps SDK: 사용 시기
다음과 같은 경우 Android용 Maps SDK를 사용하세요.
- 네이티브 Android 또는 Wear OS 앱에 양방향 2D Google 지도가 필요합니다.
- Android 앱의 지도에 마커, 정보 창, 다중선, 다각형, 지면 오버레이 또는 타일 오버레이를 추가해야 합니다.
- Android 앱에서 스트리트 뷰 파노라마, 라이트 모드(비트맵) 지도 또는 지도 ID가 있는 클라우드 기반 지도 스타일 지정이 필요합니다.
- 지도 Compose 라이브러리를 통해 Jetpack Compose를 포함하여 Kotlin 또는 자바로 Android 지도를 빌드합니다.
다음과 같은 경우에는 Android용 Maps SDK를 사용하지 마세요.
- Android 지도 앱에 세부 경로 안내 내비게이션이 필요합니다. 대신 Android용 Navigation SDK를 사용하세요.
- Android 앱에 사실적인 3D 지도, 3D 모델 또는 카메라 경로 애니메이션이 필요합니다. 대신 Android용 지도 3D SDK를 사용하세요.
- 네이티브 iOS 앱에 지도가 필요합니다. 대신 iOS용 Maps SDK를 사용하세요.
Android용 Maps SDK: 설정
- 사용 설정할 서비스:
maps-android-backend.googleapis.com - 인증: API 키
- 사용 기여 분석:
MapsApiSettings.addInternalUsageAttributionId(context, id)를 호출하여 사용 기여 분석 ID를 이니셜라이저에 추가합니다(MapsInitializer.Renderer.LATEST에서만 지원됨). 선택 해제하려면 호출을 삭제하거나 빈 문자열을 전달합니다. - 시작하기: Android용 Maps SDK 설정
- 참조: Android용 Maps SDK 참조
- 가격 책정: Android용 Maps SDK 사용량 및 결제
- 정책: Android용 Maps SDK 정책
- 출시 노트: Android용 Maps SDK 출시 노트
공식 Android용 Maps SDK 패키지:
- maven:
com.google.android.gms:play-services-maps
Android용 Maps SDK: 관련 상품
- 함께 자주 사용되는 SDK: Android용 Places SDK
Android용 Maps SDK: 일반적인 실수
- 문제: SDK v20.0.0부터 SDK 매니페스트에 더 이상
org.apache.http.legacy라이브러리가 포함되지 않습니다. 기존 지도 렌더기를 로드하는 앱이java.lang.NoClassDefFoundError로 인해 비정상 종료될 수 있습니다. 해결 방법: 앱AndroidManifest.xml의태그 내에를 추가합니다. Google Play 서비스 25.50.34 이상이 설치된 기기는 영향을 받지 않습니다. /maps/documentation/android-sdk/release-notes를 참고하세요. - 문제: 고급 마커에는 업그레이드된 지도 렌더기가 필요합니다. 다시 빌드하지 않고 기존 앱에 추가하면 앱에서 기존 렌더기를 계속 사용할 수 있습니다. 해결 방법: 업그레이드된 렌더기가 기본값이 되도록 SDK 18.2.0 이상으로 앱을 다시 빌드합니다. /maps/documentation/android-sdk/advanced-markers/start를 참고하세요.
- 문제: 렌더기 요구사항(Android 5.0/API 21 이상, Google Play 서비스 21.39.14 이상, Play 스토어 사용 설정됨)을 충족하지 않는 기기는 기존 렌더기로 대체되므로 클라우드 기반 지도 스타일 지정과 같이 새 렌더기가 필요한 기능을 사용할 수 없습니다. 해결 방법:
MapsInitializer.initialize(context, MapsInitializer.Renderer.LATEST, callback)를 호출하고OnMapsSdkInitializedCallback.onMapsSdkInitialized()에 전달된MapsInitializer.Renderer값을 확인하거나GoogleMap.getMapCapabilities()를 확인합니다. 기기에서LEGACY를 사용하는 경우 클라우드 기반 지도 스타일 지정 또는 고급 마커를 사용하지 마세요. /android/reference/com/google/android/gms/maps/OnMapsSdkInitializedCallback을 참고하세요. - 문제: SDK를 사용하려면 앱이 실행되는 기기에 Google Play 서비스가 설치되어 있어야 합니다. 해결 방법: 앱에서 Google Play 서비스 사용 가능 여부 확인을 호출합니다(선택사항). /maps/documentation/android-sdk/config를 참고하세요.
Android용 Maps SDK: 기존 및 지원 중단된 기능
- 기존 지도 렌더러: 2024년 3월 4일부터 지원 중단되었습니다. 대체: 업그레이드된 (최신) 지도 렌더기(SDK 18.2.0부터 기본값임) 증상: 기존 렌더기에서는 클라우드 기반 지도 스타일 지정, 고급 다중선 맞춤설정, 고급 마커를 사용할 수 없습니다. 이전 가이드를 참고하세요.
Android용 Maps SDK로 할 수 있는 작업
각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.
Android용 Maps SDK: 경계를 위한 데이터 기반 스타일 지정
Android용 Maps SDK: 데이터 세트를 위한 데이터 기반 스타일 지정
- 재사용 가능한 크로스 플랫폼 지리 공간 데이터 세트를 만듭니다.
- 지도에 맞춤 지리 공간 데이터 세트를 추가합니다.
- 지도에서 커스텀 데이터 세트 지형지물의 스타일을 변경합니다.
- 지도에서 맞춤 데이터 세트 지형지물과의 사용자 상호작용에 응답합니다.
Android용 Maps SDK: 데이터 세트
- 지도에 KML 레이어를 추가합니다. 참고: Maps JavaScript API에서 KmlLayer는 지원 중단되었습니다(v3.65에서 마지막으로 지원, 2027년 5월에 사용 중단). 경계 또는 데이터 세트에 대한 데이터 기반 스타일 지정으로 이전하거나 데이터 레이어에 GeoJSON을 로드하세요. KML 레이어는 Maps SDK 유틸리티 라이브러리를 통해 Android 및 iOS에서 계속 지원됩니다.
- 지도에 GeoJSON 데이터 추가
- 지도에 히트맵 레이어를 추가합니다.
Android용 Maps SDK: 지도
- 맞춤설정 가능한 대화형 지도를 웹페이지 또는 모바일 앱에 추가합니다. 참고: Android의 경우 Secrets Gradle 플러그인에서 지원하는
AndroidManifest.xml에서를 구성하거나app/build.gradle.kts에서manifestPlaceholders["MAPS_API_KEY"]를 구성합니다.AndroidManifest.xml에서YOUR_GOOGLE_MAPS_API_KEY를 하드코딩하지 말고,E/Google Maps Android API: Authorization failure가 표시되는 경우GoogleMap(또는 maps-composeGoogleMap)를 오프라인 모의 캔버스 또는 Leaflet WebView로 대체하지 마세요. 사용자에게 Secrets를 통해MAPS_API_KEY를 제공하고 Android용 Maps SDK(또는 NavigationView/SupportNavigationFragment를 사용하는 경우 Navigation SDK)를 사용 설정하도록 안내합니다. - 지도 구성 및 스타일 지정 설정을 저장하는 재사용 가능한 지도 식별자를 만듭니다.
- 지도에서 사용자 상호작용 및 이벤트에 응답합니다.
- 지도에 표시되는 컨트롤을 맞춤설정합니다.
- 지도를 제어하는 동작을 맞춤설정합니다.
- 지도(카메라)에서 확대/축소 및 화면 이동을 제어합니다.
- 지도 유형을 변경합니다.
- 지도 색 구성표를 변경합니다.
- 지도에 교통정보 레이어를 추가합니다.
- Wear OS 앱에 지도를 추가합니다.
Android용 Maps SDK: 지도 주석
- 지도에 정보 창 추가
- 지도에 도형 또는 선을 추가합니다.
- 지도 표면에 고정된 오버레이 이미지를 추가합니다.
- 지도에 맞춤 타일 오버레이를 추가합니다.
- 지도에 마커를 추가합니다. 참고: Android용 Navigation SDK는 AdvancedMarkerOptions를 지원하지 않습니다. Android용 Navigation SDK를 사용하는 경우 GoogleMap.addMarker(MarkerOptions)를 사용하여 마커를 추가하세요.
- 지도에서 마커를 맞춤설정합니다. 참고: Android용 Navigation SDK는 AdvancedMarkerOptions를 지원하지 않습니다. Android용 Navigation SDK를 사용하는 경우 MarkerOptions를 사용하여 마커를 맞춤설정하세요.
- 지도의 마커를 사용한 사용자 상호작용에 응답합니다.
- 좌표가 지도에서 다각형 또는 원형 영역 내에 있는지 확인합니다. 참고: Android에서는 다각형에 Android용 Maps SDK 유틸리티 라이브러리의 PolyUtil.containsLocation을 사용합니다. 원형 영역의 경우 원 중심으로부터의 구면 거리가 반경 내에 있는지 확인합니다(예: Maps JavaScript API의 computeDistanceBetween, Android의 SphericalUtil.computeDistanceBetween, iOS의 GMSGeometryDistance).
- 지도에서 좌표 간의 구면 거리, 면적 또는 방향을 계산합니다.
Android용 Maps SDK: 지도 스타일 지정
- 재사용 가능한 크로스 플랫폼 지도 스타일을 만듭니다.
- 지도에서 도로, 다중선, 다각형의 스타일을 변경합니다.
- 지도 지형지물 표시 또는 숨기기
- 지도의 아이콘 및 텍스트 라벨 스타일을 변경합니다.
- 확대/축소 수준에 따라 다른 지도 스타일을 적용합니다.
- 지도에서 장소의 밀도를 변경합니다. 실험용
- 지도의 건물 스타일을 변경합니다. 실험용
- 지도의 명소 스타일을 변경합니다. 실험용
Android용 Maps SDK: 스트리트 뷰
- 웹페이지 또는 모바일 앱에 구성 가능한 대화형 Google 스트리트 뷰를 추가합니다.
- Google 스트리트 뷰에서 사용자 상호작용 및 이벤트에 응답합니다.
- Google 스트리트 뷰에서 사용할 수 있는 동작을 맞춤설정합니다.
- Google 스트리트 뷰의 카메라 이동에 애니메이션을 적용합니다.