Konfigurowanie projektu na Androida Studio

Na tej stronie opisujemy, jak skonfigurować projekt Android Studio pod kątem użycia pakietu SDK Maps na Androida bez użycia szablonu Map Google opisanego w krótkim wprowadzeniu.

Szablon Map Google automatycznie konfiguruje i dodaje podstawową mapę do nowego projektu Android Studio. Można 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

W tym dokumencie opisujemy środowisko programistyczne Android Studio Hedgehog i wtyczkę Android do Gradle w wersji 8.2.

Uwaga: jeśli w Twoim środowisku programistycznym używana jest inna wersja Android Studio lub Gradle, konieczne może być zmodyfikowanie instrukcji w zależności od tych wersji. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule o wtyczce Android do obsługi Gradle i zgodności z Androidem 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 najwyższego poziomu dodaj portal wtyczki Gradle, repozytorium Google Maven i centralne repozytorium Maven w ramach bloku pluginManagement. Blok pluginManagement musi występować przed innymi instrukcjami w skrypcie.

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

2. W pliku settings.gradle najwyższego poziomu umieść repozytorium Google Maven i centralne repozytorium Maven w części dependencyResolutionManagement:

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

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

   Zakręcony

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

   Kotlin

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

4. W pliku build.gradle na poziomie modułu ustaw compileSdk i minSdk na te wartości:
   Uwaga: sprawdź, czy compileSdk ma wartość 34 lub większą, a minSdk ma wartość 21 lub większą.

   Zakręcony

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

   Kotlin

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

5. W sekcji buildFeatures pliku build.gradle na poziomie modułu dodaj klasę BuildConfig, której możesz użyć, aby uzyskać dostęp do wartości metadanych zdefiniowanych w dalszej części tej procedury:

   Zakręcony

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

   Kotlin

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

Krok 3. Dodaj klucz interfejsu API do projektu

W tej sekcji opisujemy, jak zapisać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, więc zalecamy zapisanie go w pliku secrets.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties znajdziesz w artykule o plikach właściwości Gradle.

Aby usprawnić to zadanie, zalecamy korzystanie z wtyczki do Gradle obiektów tajnych na Androida.

Uwaga: najnowsze wymagania systemowe i instrukcje instalacji znajdziesz w dokumentacji wtyczki do Gradle obiektów tajnych do Androida dostępnej na GitHubie.

Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida w projekcie Map Google:

1. W Android Studio otwórz plik build.gradle lub build.gradle.kts najwyższego poziomu i dodaj poniższy kod do elementu dependencies w sekcji buildscript.

   Zakręcony

   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 modułu i dodaj poniższy kod do elementu plugins.

   Zakręcony

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

   Kotlin

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

3. W pliku build.gradle na poziomie modułu sprawdź, czy targetSdk i compileSdk mają wartość 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj poniższy kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Zapisz klucz w tym pliku, ponieważ secrets.properties nie jest sprawdzany 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

6. Zapisz plik.

7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, w tym samym folderze co plik secrets.properties, a następnie dodaj poniższy kod.

   Uwaga: wpisz kod, który wyświetla się poniżej. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik zawiera kopię zapasową klucza interfejsu API na wypadek, gdyby plik secrets.properties nie został znaleziony. Pozwala to uniknąć błędu kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija atrybut secrets.properties, i nie masz jeszcze lokalnego pliku secrets.properties umożliwiającego przekazanie klucza interfejsu API.

8. Zapisz plik.
9. W pliku AndroidManifest.xml przejdź do sekcji com.google.android.geo.API_KEY i zaktualizuj android: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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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 opisano ustawienia, które należy dodać do pliku AndroidManifest.xml.

Numer wersji Usług Google Play

Dodaj poniższą deklarację w elemencie application. Zawiera ona wersję 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 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 po danych o lokalizacji.

Uwaga: w quickstart włączono ACCESS_FINE_LOCATION.

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 pakiet SDK Usług Google Play na wersję 8.3 lub nowszą, nie potrzebujesz uprawnienia WRITE_EXTERNAL_STORAGE. Jeśli kierujesz reklamy na wcześniejsze wersje 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 biblioteka Apache HTTP

Jeśli używasz interfejsu com.google.android.gms:play-services-maps:16.0.0 lub starszego, a Twoja aplikacja jest kierowana na interfejs API na poziomie 28 (Android 9.0) lub wyższym, w elemencie <application> w AndroidManifest.xml musisz zawrzeć tę 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ę, która korzysta z pakietu Maps SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub w emulatorze Androida opartym na Androidzie 5.0 lub nowszym i zawierającym interfejsy API Google.

• Aby używać urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu sprzętowym.
• Aby użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować go za pomocą Menedżera urządzeń wirtualnych Android (AVD) dołączonego do Android Studio.
  Uwaga: jeśli zdecydujesz się użyć emulatora Androida, wybierz urządzenie z ikoną Play widoczną w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemu zawierających aplikację Sklep Play:

  

Krok 6. Opcjonalnie sprawdź, czy masz dostęp do zespołu pomocy Usługi 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żna wywołać w aplikacji, aby to sprawdzić. Więcej informacji znajdziesz w artykule Sprawdzanie, czy są zainstalowane Usługi Google Play.

Dalsze kroki

Po skonfigurowaniu projektu możesz dodać mapę.