Na tej stronie znajdziesz instrukcje konfigurowania projektu w Android Studio, aby używać pakietu Maps SDK na Androida bez korzystania z szablonu Map Google, który jest szczegółowo opisany w artykule Szybki start.
Szablon Map Google automatycznie konfiguruje i dodaje podstawową mapę do nowego projektu w Android Studio. Możesz też dodać mapę do projektu na Androida, który korzysta z innego szablonu Android Studio. Aby to zrobić, musisz ręcznie skonfigurować projekt, a potem dodać mapę.
Krok 1. Skonfiguruj Android Studio
Ten dokument opisuje środowisko programistyczne korzystające z Android Studio Hedgehog i wtyczki Gradle dla Androida w wersji 8.2.
Krok 2. Konfigurowanie pakietu SDK
Biblioteka Maps SDK na Androida jest dostępna w repozytorium Maven firmy Google. Aby dodać pakiet SDK do aplikacji:
- W pliku najwyższego poziomu
settings.gradle.kts
dodaj portal wtyczek Gradle, repozytorium Google Maven i centralne repozytorium Maven w blokupluginManagement
. BlokpluginManagement
musi pojawić się przed innymi instrukcjami w skrypcie.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- W pliku
settings.gradle.kts
najwyższego poziomu dodaj repozytorium Maven firmy Google i centralne repozytorium Maven w blokudependencyResolutionManagement
:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- W pliku
build.gradle.kts
lubbuild.gradle
na poziomie modułu dodaj zależność Usługi Google Play do pakietu SDK Map Google na Androida.Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
Zakręcony
dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:19.0.0" }
- W pliku
build.gradle.kts
lubbuild.gradle
na poziomie modułu ustaw wartościcompileSdk
iminSdk
na te wartości:Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
Zakręcony
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
- W sekcji
buildFeatures
w plikubuild.gradle.kts
lubbuild.gradle
na poziomie modułu dodaj klasęBuildConfig
, której możesz używać do uzyskiwania dostępu do wartości metadanych zdefiniowanych w dalszej części tej procedury:Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
Zakręcony
android { // ... buildFeatures { buildConfig true // ... } }
Krok 3. Dodaj klucz interfejsu API do projektu
W tej sekcji opisujemy, jak przechowywać klucz interfejsu API, aby Twoja aplikacja mogła bezpiecznie się do niego odwoływać. Nie należy go dodawać do systemu kontroli wersji, dlatego zalecamy przechowywanie go w pliku secrets.properties
, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties
znajdziesz w artykule Pliki właściwości Gradle.
Aby uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.
Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida w projekcie Mapy Google:
-
W Android Studio otwórz najwyższy poziom pliku
build.gradle.kts
lubbuild.gradle
i dodaj pod elementembuildscript
kod:dependencies
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Zakręcony
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
Otwórz plik
build.gradle.kts
lubbuild.gradle
na poziomie modułu i dodaj do elementuplugins
ten kod:Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Zakręcony
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- W pliku
build.gradle.kts
lubbuild.gradle
na poziomie modułu sprawdź, czy wartościtargetSdk
icompileSdk
są ustawione na 34. - Zapisz plik i zsynchronizuj projekt z Gradle.
-
Otwórz plik
secrets.properties
w katalogu najwyższego poziomu, a potem dodaj ten kod. ZastąpYOUR_API_KEY
swoim kluczem API. Przechowuj klucz w tym pliku, ponieważsecrets.properties
nie jest uwzględniany w systemie kontroli wersji.MAPS_API_KEY=YOUR_API_KEY
- Zapisz plik.
-
Utwórz plik
local.defaults.properties
w katalogu najwyższego poziomu, czyli w tym samym folderze co pliksecrets.properties
, a potem dodaj podany niżej kod.MAPS_API_KEY=DEFAULT_API_KEY
Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć pliku
secrets.properties
, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli klonujesz aplikację z systemu kontroli wersji, który pomija pliksecrets.properties
, a na komputerze lokalnym nie masz jeszcze utworzonego plikusecrets.properties
, aby podać klucz interfejsu API. - Zapisz plik.
-
W pliku
AndroidManifest.xml
otwórzcom.google.android.geo.API_KEY
i zaktualizujandroid:value attribute
. Jeśli tag<meta-data>
nie istnieje, utwórz go jako element podrzędny tagu<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Uwaga:
com.google.android.geo.API_KEY
to zalecane nazwa metadanych klucza interfejsu API. Klucza o tej nazwie można używać do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w Maps SDK na Androida. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwęcom.google.android.maps.v2.API_KEY
. Ten starszy identyfikator umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną z nazwy metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek. -
W Android Studio otwórz plik
build.gradle.kts
lubbuild.gradle
na poziomie modułu i edytuj właściwośćsecrets
. Jeśli właściwośćsecrets
nie istnieje, dodaj ją.Zmień właściwości wtyczki, aby ustawić wartość
propertiesFileName
nasecrets.properties
, wartośćdefaultPropertiesFileName
nalocal.defaults.properties
i ustawić inne właściwości.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.*" }
Zakręcony
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.*" }
Krok 4. Zaktualizuj plik manifestu aplikacji
W tej sekcji opisaliśmy ustawienia, które należy dodać do pliku AndroidManifest.xml
.
Numer wersji Usług Google Play
Dodaj tę deklarację w elemencie application
. Zawiera ona wersję Usług Google Play, z których korzysta aplikacja.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
Dostęp do lokalizacji
Jeśli Twoja aplikacja potrzebuje dostępu do lokalizacji użytkownika, musisz poprosić o dostęp do lokalizacji w pliku AndroidManifest.xml
. Dostępne są opcje ACCESS_FINE_LOCATION
, która zapewnia dokładną lokalizację urządzenia, oraz ACCESS_COARSE_LOCATION
, która jest mniej dokładna. Szczegółowe informacje znajdziesz w przewodniku dotyczącym danych o lokalizacji.
Aby poprosić o uprawnienie ACCESS_FINE_LOCATION
, dodaj do elementu manifest
ten kod:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
Uprawnienia dostępu do pamięci zewnętrznej
Jeśli kierujesz aplikację na wersję 8.3 lub nowszą pakietu SDK Usług Google Play, nie potrzebujesz uprawnienia WRITE_EXTERNAL_STORAGE
. Jeśli kierujesz aplikację na wcześniejsze wersje pakietu SDK usług Google Play, musisz w elemencie manifest
poprosić o uprawnienie WRITE_EXTERNAL_STORAGE.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Biblioteka Apache HTTP w starszej wersji
Jeśli używasz wersji com.google.android.gms:play-services-maps:16.0.0
lub niższej, a Twoja aplikacja jest kierowana na interfejs API na poziomie 28 (Android 9.0) lub wyższym, musisz umieścić w elemencie <application>
w pliku AndroidManifest.xml
następującą deklarację. W przeciwnym razie pomiń tę deklarację.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
Krok 5. Skonfiguruj urządzenie z Androidem
Aby uruchomić aplikację korzystającą z pakietu SDK Map Google na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub na emulatorze Androida opartym na Androidzie 5.0 lub nowszym, który zawiera interfejsy API Google.
- Aby korzystać z urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu z Androidem.
- Aby korzystać z emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą menedżera urządzenia wirtualnego z Androidem (AVD), który jest częścią Android Studio.
Krok 6. Opcjonalnie sprawdź, czy Usługi Google Play są obsługiwane
Pakiet SDK Map na Androida wymaga, aby na urządzeniu, na którym wdrażasz aplikację, były zainstalowane Usługi Google Play. Google udostępnia metodę, którą możesz wywołać z aplikacji, aby to sprawdzić. Więcej informacji znajdziesz w artykule Sprawdzanie, czy usługi Google Play są zainstalowane.
Dalsze kroki
Po skonfigurowaniu projektu możesz dodać mapę.