이 페이지에서는 빠른 시작에 자세히 설명되어 있는 Google 지도 템플릿을 사용하지 않고 Android용 Maps SDK를 사용하도록 Android 스튜디오 프로젝트를 구성하는 방법을 설명합니다.
Google 지도 템플릿은 자동으로 기본 지도를 구성하고 새 Android 스튜디오 프로젝트에 추가합니다. 하지만 다른 Android 스튜디오 템플릿을 사용하는 Android 프로젝트에 지도를 추가할 수도 있습니다. 이렇게 하려면 프로젝트를 수동으로 구성한 다음 지도를 추가해야 합니다.
1단계: Android 스튜디오 설정
이 문서에서는 Android 스튜디오 Hedgehog 및 Android Gradle 플러그인 버전 8.2를 사용하는 개발 환경을 설명합니다.
2단계: SDK 설정
Android용 Maps SDK 라이브러리는 Google의 Maven 저장소를 통해 사용할 수 있습니다. 앱에 SDK를 추가하려면 다음 지침을 따르세요.
- 최상위 수준
settings.gradle.kts
파일의pluginManagement
블록 아래에 Gradle 플러그인 포털, Google Maven 저장소, Maven 중앙 저장소를 포함합니다.pluginManagement
블록은 스크립트의 모든 문 앞에 표시되어야 합니다.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- 최상위 수준
settings.gradle.kts
파일의dependencyResolutionManagement
블록 아래에 Google Maven 저장소, Maven 중앙 저장소를 포함합니다.dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- 모듈 수준
build.gradle.kts
또는build.gradle
파일에 Google Play 서비스 종속 항목 바로 Android용 Maps SDK입니다.Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
Groovy
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- 모듈 수준
build.gradle.kts
또는build.gradle
파일에서compileSdk
및minSdk
를 다음 값으로 설정합니다.Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
Groovy
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- 모듈 수준
build.gradle.kts
의buildFeatures
섹션 또는build.gradle
파일을 추가하려면BuildConfig
클래스를 추가합니다. 이 클래스를 사용하면 이 절차의 후반부에서 정의된 메타데이터 값에 액세스합니다.Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
Groovy
android { // ... buildFeatures { buildConfig true // ... } }
3단계: 프로젝트에 API 키 추가
이 섹션에서는 API 키를 앱이 더욱 안전하게 참조할 수 있도록 저장하는 방법을 설명합니다. API 키는 버전 제어 시스템에 체크인하면 안 되기 때문에 프로젝트의 루트 디렉터리에 있는 secrets.properties
파일에 저장할 것을 권장합니다. secrets.properties
파일에 관한 자세한 내용은
Gradle 속성 파일을 참고하세요.
이 작업을 간소화하려면 Android용 Secrets Gradle 플러그인을 사용하는 것이 좋습니다.
Google 지도 프로젝트에 Android용 Secrets Gradle 플러그인을 설치하려면 다음 단계를 따르세요.
-
Android 스튜디오에서 최상위 수준
build.gradle.kts
또는build.gradle
파일을 열고 다음 코드를buildscript
아래dependencies
요소에 추가합니다.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
모듈 수준
build.gradle.kts
또는build.gradle
파일을 열고 다음 코드를plugins
요소에 추가합니다.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- 모듈 수준
build.gradle.kts
또는build.gradle
파일에서 다음을 확인합니다.targetSdk
및compileSdk
가 설정되어 있음 34로 설정합니다. - 파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
-
최상위 수준 디렉터리에서
secrets.properties
파일을 연 후 다음 코드를 추가합니다.YOUR_API_KEY
를 직접 생성한 API 키로 변경합니다.secrets.properties
가 버전 제어 시스템에 체크인되는 데서 제외되었으므로 키를 이 파일에 저장합니다.MAPS_API_KEY=YOUR_API_KEY
- 파일을 저장합니다.
-
최상위 수준 디렉터리에서
secrets.properties
파일과 동일한 폴더에local.defaults.properties
파일을 만든 후 다음 코드를 추가합니다.MAPS_API_KEY=DEFAULT_API_KEY
이 파일의 목적은
secrets.properties
파일이 없는 경우 빌드에 실패하지 않도록 API 키의 백업 위치를 제공하는 것입니다. 이는 버전 제어 시스템에서secrets.properties
가 빠진 앱을 복제하거나 API 키를 제공하는secrets.properties
파일을 아직 로컬에서 생성하지 않은 경우 발생할 수 있습니다. - 파일을 저장합니다.
-
AndroidManifest.xml
파일에서com.google.android.geo.API_KEY
로 이동한 후android:value attribute
를 업데이트합니다.<meta-data>
태그가 존재하지 않으면<application>
태그의 하위 요소로 태그를 만듭니다.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle.kts
orbuild.gradle
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Kotlin
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Groovy
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
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를 사용하는 앱을 실행하려면 Android 기기 또는 Android에 Android용 Maps SDK를 배포해야 합니다. Android 5.0 이상을 기반으로 하며 살펴보겠습니다
- Android 기기를 사용하려면 하드웨어 기기에서 앱 실행의 안내를 따르세요.
- Android Emulator를 사용하려면 Android 스튜디오와 함께 제공되는 Android Virtual Device(AVD) Manager를 이용해 가상 기기를 만들고 에뮬레이터를 설치하면 됩니다.
6단계: Play 서비스 지원 확인(선택사항)
Android용 Maps SDK를 사용하려면 앱을 배포하는 기기에 Google Play 서비스가 설치되어 있어야 합니다. Google은 개발자가 앱에서 호출해 확인할 수 있는 방법을 제공합니다. 자세한 내용은 Google Play 서비스가 설치되었는지 여부 확인을 참고하세요.
다음 단계
프로젝트가 구성되면 지도를 추가할 수 있습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2024-10-16(UTC)
[null,null,["최종 업데이트: 2024-10-16(UTC)"],[],[]]