Na tej stronie opisaliśmy, jak skonfigurować projekt w Android Studio, aby używać Maps SDK for Android bez korzystania z szablonu Map Google, który jest szczegółowo omówiony 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 następnie 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 Maven firmy Google 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 umieść repozytorium Google Maven i centralne repozytorium Maven w ramach 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ług Google Play do pakietu SDK Map 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 ustawcompileSdk
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 usprawnić 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: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ź, czytargetSdk
icompileSdk
mają wartość 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. Zapisz klucz w tym pliku, ponieważsecrets.properties
nie jest sprawdzany w systemie kontroli wersji.MAPS_API_KEY=YOUR_API_KEY
- Zapisz plik.
-
Utwórz plik
local.defaults.properties
w katalogu najwyższego poziomu, 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 sklonujesz aplikację z systemu kontroli wersji, który pomija atrybutsecrets.properties
, i nie masz jeszcze lokalnego plikusecrets.properties
umożliwiającego przekazanie klucza interfejsu API. - Zapisz plik.
-
W pliku
AndroidManifest.xml
przejdź do sekcjicom.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 pakiecie SDK Map na Androida. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwęcom.google.android.maps.v2.API_KEY
. Ta starsza nazwa umożliwia uwierzytelnianie tylko dla interfejsu Android Maps API w wersji 2. Aplikacja może określać tylko jedną z nazw 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ć
propertiesFileName
nasecrets.properties
,defaultPropertiesFileName
nalocal.defaults.properties
i wszystkie 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 musi mieć dostęp do lokalizacji użytkownika, musisz poprosić o dostęp do lokalizacji w pliku AndroidManifest.xml
. Dostępne opcje to ACCESS_FINE_LOCATION
, która podaje dokładną lokalizację urządzenia, i ACCESS_COARSE_LOCATION
(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" />
Starsza biblioteka Apache HTTP
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
Aby korzystać z Maps SDK na Androida, musisz mieć na urządzeniu, na którym wdrażasz aplikację, zainstalowane Usługi Google Play. Google udostępnia metodę, którą można wywołać w 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ę.