Konfigurowanie projektu na Androida Studio

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

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

W tym dokumencie opisujemy ś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, wykonaj te czynności:

1. W pliku settings.gradle.kts najwyższego poziomu uwzględnij 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 uwzględnij 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ść od Usług Google Play dla pakietu 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.0.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 na 21 lub wyższy.

   Kotlin

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

   Groovy

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

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 uzyskania dostępu do wartości metadanych zdefiniowanych później w tej procedurze:

   Kotlin

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

   Groovy

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

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

   [versions]
   play-services-maps = "20.0.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, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties znajdziesz w Pliki właściwości Gradle.

Aby uprościć to zadanie, zalecamy używanie wtyczki Gradle obiektów tajnych na Androida .

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

1. W Android Studio otwórz plik build.gradle na poziomie głównym i dodaj ten kod do elementu dependencies w sekcji buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. Otwórz plik build.gradle na poziomie aplikacji i dodaj ten kod do elementu plugins.

   Groovy

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

   Kotlin

   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 local.properties w katalogu na poziomie projektu, a następnie dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API.

   MAPS_API_KEY=YOUR_API_KEY

5. 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 pakiecie 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.

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ą została skompilowana 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 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 jest włączona opcja 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 kierujesz reklamy na wersję 8.3 lub nowszą pakietu SDK Usług Google Play, nie potrzebujesz uprawnienia WRITE_EXTERNAL_STORAGE. Jeśli kierujesz reklamy 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 kierowana 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 pakietu Maps SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida , który jest oparty na Androidzie 5.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ć 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.
  Uwaga: jeśli zdecydujesz się używać emulatora Androida, upewnij się, że wybierzesz urządzenie z ikoną Google Play, , która jest wyświetlana w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni CTS zgodne i mogą używać obrazów systemu, które zawierają aplikację Sklep Play:

  

Krok 6. Opcjonalnie sprawdź obsługę Usług Play

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 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ę.