Konfigurowanie projektu na Androida Studio

Na tej stronie opisano, jak skonfigurować projekt Android Studio do korzystania z Maps SDK na Androida bez użycia szablonu Map Google, który jest szczegółowo opisany w krótkim wprowadzeniu.

Szablon Map Google automatycznie konfiguruje i dodaje podstawową mapę do nowego projektu Android Studio. Możesz też jednak dodać mapę do projektu aplikacji na Androida, który używa innego szablonu Android Studio. Aby to zrobić, musisz ręcznie skonfigurować projekt, a następnie dodać mapę.

Krok 1. Skonfiguruj Android Studio

W tym dokumencie opisano środowisko programistyczne korzystające z Android Studio Hedgehog i wtyczki Androida do obsługi Gradle w wersji 8.2.

Uwaga: jeśli Twoje środowisko programistyczne używa innej wersji Android Studio lub Gradle, być może musisz zmodyfikować kroki w zależności od tych wersji. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule o zgodności wtyczki Androida do obsługi Gradle i Android Studio.

Krok 2. Konfigurowanie pakietu SDK

Biblioteka pakietu Maps SDK na Androida jest dostępna w repozytorium Maven Google. Aby dodać pakiet SDK do aplikacji:

1. W pliku settings.gradle.kts najwyższego poziomu w bloku pluginManagement dodaj portal wtyczek Gradle, repozytorium Google Maven i centralne repozytorium Maven. Blok pluginManagement musi pojawić się przed innymi instrukcjami w skrypcie.

   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   } 

2. W pliku settings.gradle.kts najwyższego poziomu dodaj repozytorium Maven firmy Google i centralne repozytorium Maven w bloku dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. W pliku build.gradle.kts lub build.gradle na poziomie modułu dodaj zależność usług Google Play do pakietu Maps SDK na Androida.

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation(libs.play.services.maps)
   }

   Zakręcony

   dependencies {
   
       // Maps SDK for Android
       implementation "com.google.android.gms:play-services-maps:20.1.0"
   }

4. W pliku build.gradle.kts lub build.gradle na poziomie modułu ustaw te wartości compileSdk i minSdk:
   Uwaga: upewnij się, że wartość compileSdk jest ustawiona na 34 lub wyższą, a wartość minSdk na 23 lub wyższą.

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

   Zakręcony

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 23
           // ...
       }
   }

5. W sekcji buildFeatures pliku build.gradle.kts lub build.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
       // ...
     }
   }

6. W pliku libs.versions.toml dodaj te wiersze:

   [versions]
   play-services-maps = "20.1.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

Krok 3. Dodaj klucz interfejsu API do projektu

W tej sekcji opisano, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy przechowywanie go w pliku secrets.properties w katalogu głównym projektu i wykluczenie tego pliku z kontroli wersji. Więcej informacji o plikach właściwości Gradle znajdziesz w artykule na ten temat.

Aby uprościć to zadanie, zalecamy użycie wtyczki Secrets Gradle do Androida.

Aby zainstalować wtyczkę Gradle obiektów tajnych dla Androida i zapisać klucz interfejsu API:

1. W Android Studio otwórz plik build.gradle.kts lub build.gradle najwyższego poziomu i dodaj ten kod do bloku plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Zakręcony

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. Otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i dodaj ten kod do elementu plugins.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Zakręcony

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. Jeśli używasz Android Studio, zsynchronizuj projekt z Gradle.
4. Otwórz plik secrets.properties w katalogu najwyższego poziomu i dodaj podany niżej kod. Zastąp YOUR_API_KEY kluczem interfejsu API. Dodaj secrets.properties do pliku .gitignore (lub w inny sposób wyklucz go z systemu kontroli wersji), aby nie sprawdzać klucza interfejsu API w systemie kontroli wersji.
   Uwaga: jeśli plik secrets.properties nie istnieje, utwórz go w tym samym folderze co plik local.properties.

   MAPS_API_KEY=YOUR_API_KEY

5. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze, w którym znajduje się plik secrets.properties, a następnie dodaj podany niżej kod.

   Uwaga: wpisz kod w wyświetlonej postaci. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik służy do podania zapasowej lokalizacji klucza interfejsu API, jeśli nie można znaleźć pliku secrets.properties, aby kompilacje nie kończyły się niepowodzeniem. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, i nie utworzysz jeszcze lokalnie pliku secrets.properties, aby podać klucz interfejsu API.

6. W pliku AndroidManifest.xml przejdź do com.google.android.geo.API_KEY i zaktualizuj atrybut android:value w ten sposób:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   Uwaga: com.google.android.geo.API_KEY to zalecana nazwa metadanych klucza interfejsu API. Klucz o tej nazwie może służyć do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w pakiecie Maps SDK 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 w interfejsie API Map Google dla Androida w wersji 2. Aplikacja może określić tylko jedną z nazw metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zgłosi wyjątek.

7. W Android Studio otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i edytuj właściwość secrets. Jeśli właściwość secrets nie istnieje, dodaj ją.

   Edytuj właściwości wtyczki, aby ustawić propertiesFileName na "secrets.properties", defaultPropertiesFileName na "local.defaults.properties" i skonfigurować 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 root directory (the same folder as the root 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"
   }

   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 root directory (the same folder as the root 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"
   }

Krok 4. Zaktualizuj manifest aplikacji

W tej sekcji opisano ustawienia, które należy dodać do pliku AndroidManifest.xml.

Numer wersji Usług Google Play

Dodaj tę deklarację w elemencie application. Spowoduje to umieszczenie wersji Usług Google Play, z którą aplikacja została skompilowana.

<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 opcje to ACCESS_FINE_LOCATION, która podaje dokładną lokalizację urządzenia, i ACCESS_COARSE_LOCATION, która jest mniej dokładna. Więcej informacji znajdziesz w przewodniku po danych o lokalizacji.

Uwaga: w krótkim wprowadzeniu włączono ACCESS_FINE_LOCATION.

Aby poprosić o uprawnienie ACCESS_FINE_LOCATION, dodaj ten kod do elementu manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Uprawnienia dostępu do pamięci zewnętrznej

Jeśli używasz pakietu SDK usług Google Play w wersji 8.3 lub nowszej, nie potrzebujesz uprawnienia WRITE_EXTERNAL_STORAGE. Jeśli używasz wcześniejszych wersji pakietu SDK usług Google Play, musisz poprosić o uprawnienie WRITE_EXTERNAL_STORAGE w elemencie manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Starsza wersja biblioteki Apache HTTP

Jeśli używasz wersji com.google.android.gms:play-services-maps:16.0.0 lub starszej, a Twoja aplikacja jest kierowana na interfejs API na poziomie 28 (Android 9.0) lub wyższym, musisz uwzględnić tę deklarację w elemencie <application> pliku AndroidManifest.xml. 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ę, która korzysta z pakietu Maps SDK na Androida, musisz ją wdrożyć na urządzeniu z Androidem lub w emulatorze Androida z systemem Android 6.0 lub nowszym i interfejsami API Google.

• Aby użyć urządzenia z Androidem, postępuj zgodnie z instrukcjami podanymi w artykule Uruchamianie aplikacji na urządzeniu.
• Aby używać Android Emulator, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą Menedżera urządzeń, który jest częścią Android Studio.
  Uwaga: jeśli zdecydujesz się użyć emulatora Androida, upewnij się, że wybierzesz profil urządzenia z ikoną Google Play  wyświetlaną w kolumnie Play. Ta ikona wskazuje, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemu, które zawierają aplikację Sklep Play:

  

  Okno Dodaj urządzenie w Menedżerze urządzeń Android Studio, w którym widać profile urządzeń wirtualnych z ikoną Google Play w kolumnie Play.

Krok 6. Opcjonalnie sprawdź, czy Usługi Google Play są obsługiwane

Pakiet Maps SDK 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 poziomu 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ę.