Konfigurowanie projektu na Androida Studio

Na tej stronie opisujemy, jak skonfigurować projekt Android Studio, aby używać Maps SDK na Androida bez korzystania z szablonu Map Google, który jest opisany w krótkim przewodniku.

Szablon Map Google automatycznie konfiguruje i dodaje podstawową mapę do nowego projektu Android Studio. Możesz jednak dodać mapę do projektu aplikacji 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 Androida do obsługi Gradle w wersji 8.2.

Uwaga: Jeśli Twoje środowisko programistyczne korzysta z innej wersji Androida Studio lub Gradle, być może będziesz musiał(-a) zmodyfikować te kroki. Więcej informacji o wersjach Androida Studio i Gradle znajdziesz w artykule Zgodność wtyczki Androida do obsługi Gradle i Androida Studio.

Krok 2. Konfigurowanie pakietu SDK

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

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

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

2. W pliku settings.gradle.kts najwyższego poziomu dodaj repozytorium Google Maven 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 dla Maps SDK na Androida.

   Kotlin

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

   Groovy

   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 compileSdk i minSdk na te wartości:
   Uwaga: upewnij się, że compileSdk jest ustawiony na 34 lub wyższy, a minSdk jest ustawiony na 23 lub wyższy.

   Kotlin

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

   Groovy

   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żyć do uzyskiwania dostępu do wartości metadanych zdefiniowanych w dalszej części tej procedury:

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

   Groovy

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

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

   [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 opisujemy, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy dodawać klucza interfejsu API do systemu 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 Pliki właściwości Gradle.

Aby uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych dla 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
   }

   Groovy

   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")
   }

   Groovy

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

3. Jeśli używasz Androida Studio, zsynchronizuj projekt z Gradle.
4. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Pamiętaj, aby dodać secrets.properties do swojego .gitignore pliku (lub w inny sposób wykluczyć go z systemu kontroli wersji), aby nie dodawać klucza interfejsu API do 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, w tym samym folderze co plik secrets.properties, a następnie dodaj ten kod.

   Uwaga: wpisz kod tak, jak pokazano. Nie zastępuj DEFAULT_API_KEY swoim kluczem interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik ma na celu zapewnienie lokalizacji kopii zapasowej klucza interfejsu API jeśli plik secrets.properties nie zostanie znaleziony, aby kompilacje się nie powiodły. Może się to zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji , który pomija 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 Android, w tym w Maps SDK na Androida. Aby zachować zgodność wsteczną, interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta starsza nazwa umożliwia uwierzytelnianie tylko w interfejsie Android Maps API w wersji 2. Aplikacja może określić tylko jedną z nazw metadanych klucza interfejsu API. Jeśli zostaną określone obie, 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", ustaw defaultPropertiesFileName na "local.defaults.properties", i 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"
   }

   Groovy

   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 opisujemy ustawienia, które należy dodać do pliku AndroidManifest.xml.

Numer wersji usług Google Play

Dodaj tę deklarację w elemencie application. Spowoduje to osadzenie wersji usług Google Play, z którą skompilowano aplikację.

<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 uprawnienia dostępu do lokalizacji w pliku AndroidManifest.xml. Dostępne opcje to ACCESS_FINE_LOCATION, która zapewnia dokładną lokalizację urządzenia, oraz ACCESS_COARSE_LOCATION, która jest mniej dokładna. Więcej informacji znajdziesz w przewodniku po danych o lokalizacji.

Uwaga: w krótkim przewodniku włączono ACCESS_FINE_LOCATION enabled.

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 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 starsze wersje pakietu SDK usług Google Play, musisz poprosić o WRITE_EXTERNAL_STORAGE uprawnienie w elemencie manifest.

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

Starsza biblioteka Apache HTTP

Jeśli używasz com.google.android.gms:play-services-maps:16.0.0 lub starszej wersji, a Twoja aplikacja jest przeznaczona na poziom interfejsu API 28 (Android 9.0) lub nowszy, musisz dodać 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ę korzystającą z Maps SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida, który jest oparty na Androidzie 6.0 lub nowszym i zawiera interfejsy API Google.

• Aby używać urządzenia z Androidem, postępuj zgodnie z instrukcjami w artykule Uruchamianie aplikacji na urządzeniu fizycznym.
• 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żywać emulatora Androida, wybierz profil urządzenia z ikoną Play,, wyświetlaną w kolumnie Sklep Play. Ta ikona oznacza że te profile są w pełni CTS i mogą używać obrazów systemu, które zawierają aplikację Sklep Play.

Krok 6. Opcjonalnie sprawdź obsługę usług Google Play

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 aplikacji, aby to sprawdzić. Więcej informacji znajdziesz w artykule Sprawdzanie, czy usługi Google Play są zainstalowane.

Dalsze kroki

Gdy projekt zostanie skonfigurowany, możesz dodać mapę.