이 페이지에서는 빠른 시작에 자세히 설명되어 있는 Google 지도 템플릿을 사용하지 않고 Android용 Maps SDK를 사용하도록 Android 스튜디오 프로젝트를 구성하는 방법을 설명합니다.
Google 지도 템플릿은 자동으로 기본 지도를 구성하고 새 Android 스튜디오 프로젝트에 추가합니다. 하지만 다른 Android 스튜디오 템플릿을 사용하는 Android 프로젝트에 지도를 추가할 수도 있습니다. 이렇게 하려면 프로젝트를 수동으로 구성한 다음 지도를 추가해야 합니다.
1단계: Android 스튜디오 설정하기
- Android 스튜디오 Arctic Fox 이상이 필요합니다. 아직 다운로드하지 않은 경우 다운로드하고 설치하세요.
- Android 스튜디오에서 Android Gradle 플러그인 버전 7.0 이상을 사용 중이어야 합니다.
2단계: SDK 설정
Android용 Maps SDK 라이브러리는 Google의 Maven 저장소를 통해 사용할 수 있습니다. 앱에 SDK를 추가하려면 다음 지침을 따르세요.
- 최상위 수준
settings.gradle
파일의pluginManagement
블록 아래 Gradle 플러그인 포털, Google Maven 저장소, Maven 중앙 저장소를 포함합니다.pluginManagement
블록은 스크립트의 모든 문 앞에 표시되어야 합니다.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- 최상위 수준
settings.gradle
파일의dependencyResolutionManagement
블록 아래 Google Maven 저장소, Maven 중앙 저장소를 포함합니다.dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- 모듈 수준
build.gradle
파일에 Android용 Maps SDK용 Google Play 서비스 종속 항목을 추가합니다.dependencies { implementation 'com.google.android.gms:play-services-maps:18.1.0' // ... }
- 모듈 수준
build.gradle
파일에서compileSdk
및minSdk
를 다음 값으로 설정합니다.android { compileSdk 31 defaultConfig { minSdk 19 // ... }
3단계: 프로젝트에 API 키 추가
이 섹션에서는 앱이 더욱 안전하게 참조할 수 있도록 API 키를 저장하는 방법을 설명합니다. API 키는 버전 제어 시스템에 등록하면 안 되며, 프로젝트의 루트 디렉터리에 있는 local.properties
파일에 저장하는 것이 좋습니다. local.properties
파일에 관한 자세한 내용은
Gradle 속성 파일을 참고하세요.
이 작업을 간소화하려면 Android용 Secrets Gradle 플러그인을 사용하는 것이 좋습니다. 플러그인을 설치하여 API 키를 저장하는 방법은 다음과 같습니다.
- Android 스튜디오에서 프로젝트 수준
build.gradle
파일을 열고 다음 코드를buildscript
아래dependencies
요소에 추가합니다.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
- 그런 다음 모듈 수준
build.gradle
파일을 열고plugins
요소에 다음 코드를 추가합니다.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- 파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
- 프로젝트 수준 디렉터리에서
local.properties
를 열고 다음 코드를 추가합니다.YOUR_API_KEY
를 API 키로 변경합니다.MAPS_API_KEY=YOUR_API_KEY
- 파일을 저장합니다.
AndroidManifest.xml
파일에서com.google.android.geo.API_KEY
로 이동한 후android:value attribute
를 다음과 같이 업데이트합니다.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
참고: 위의 내용처럼,
com.google.android.geo.API_KEY
는 API 키의 권장 메타데이터
이름입니다. 이 이름의 키는 Android 플랫폼에서 Android용 Maps SDK 등
여러 Google 지도 기반 API를 인증하는 데
사용할 수 있습니다. 이전 버전과의 호환성을 위해 API에서는
com.google.android.maps.v2.API_KEY
이름도 지원합니다. 이 기존 이름을
사용하면 Android 지도 API v2만 인증할 수 있습니다. 애플리케이션에서는
API 키 메타데이터 이름을 하나만 지정할 수 있습니다. 두 개가 모두 지정되면 API에서
예외가 발생합니다.
4단계: 앱 매니페스트 업데이트
이 섹션에서는 AndroidManifest.xml
파일에 추가할 설정을
설명합니다.
Google Play 서비스 버전 번호
application
요소 내에 다음 선언을 추가합니다. 이렇게 하면 앱이
컴파일된 Google Play 서비스의 버전이 삽입됩니다.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
위치 정보 액세스 권한
앱에서 사용자의 위치에 액세스해야 하는 경우 AndroidManifest.xml
파일에서
위치 정보 액세스 권한을 요청해야 합니다. 정확한 기기 위치를 제공하는 ACCESS_FINE_LOCATION
과 정확도가 떨어지는 ACCESS_COARSE_LOCATION
중에서 선택할 수 있습니다. 자세한 내용은 위치 데이터
가이드를 참고하세요.
ACCESS_FINE_LOCATION
권한을 요청하려면 이 코드를 manifest
요소에
추가하세요.
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
외부 저장소 권한
Google Play 서비스 SDK 버전 8.3 이상을 타겟팅하는 경우에는
WRITE_EXTERNAL_STORAGE
권한이 필요하지 않습니다. 이전 버전의
Google Play 서비스 SDK를 타겟팅하는 경우에는 manifest
요소에서
WRITE_EXTERNAL_STORAGE
권한을 요청해야 합니다.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Apache HTTP Legacy 라이브러리
com.google.android.gms:play-services-maps:16.0.0
이하를 사용 중이고
앱이 API 수준 28(Android 9.0) 이상을 타겟팅하는 경우
AndroidManifest.xml
의 <application>
요소 내에
다음 선언을 포함해야 합니다. 그렇지 않다면 이 선언을 건너뛰세요.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
5단계: Android 기기 설정하기
Android용 Maps SDK를 사용하는 앱을 실행하려면 Google API를 포함하는 Android 4.0 이상의 Android 기기 또는 Emulator에 Android용 Maps SDK를 배포해야 합니다.
- Android 기기를 사용하려면 하드웨어 기기에서 앱 실행의 안내를 따르세요.
- Android Emulator를 사용하려면 Android 스튜디오와 함께 제공되는 Android Virtual Device(AVD) Manager를 이용해 가상 기기를 만들고 에뮬레이터를 설치할 수 있습니다.
다음 단계
프로젝트가 구성되면 지도를 추가할 수 있습니다.