Konfigurowanie projektu na Androida Studio

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

Uwaga: jeśli środowisko programistyczne używa innej wersji Android Studio lub Gradle, konieczne może być dostosowanie tych czynności do tych wersji. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule Wtyczka Androida do obsługi Gradle i zgodność z Android Studio.

Krok 2. Konfigurowanie pakietu SDK

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

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

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

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

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

   Kotlin

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

   Zakręcony

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

5. W sekcji buildFeatures w 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
       // ...
     }
   }

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.

Uwaga: aby poznać najnowsze wymagania systemowe i instrukcje instalacji, zapoznaj się z dokumentacją Wtyczka Gradle obiektów tajnych na Androida na GitHubie.

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

1. W Android Studio otwórz najwyższy poziom pliku build.gradle.kts lub build.gradle i dodaj pod elementem buildscript kod:dependencies

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

2. Otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i dodaj do elementu plugins 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'
   }

3. W pliku build.gradle.kts lub build.gradle na poziomie modułu sprawdź, czy wartości targetSdk i compileSdk są ustawione na 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a potem dodaj ten kod: Zastąp YOUR_API_KEY swoim kluczem API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany 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, czyli w tym samym folderze co plik secrets.properties, a potem dodaj podany niżej kod.

   Uwaga: wpisz kod zgodnie z wyświetlanymi instrukcjami. Nie zastępuj DEFAULT_API_KEY swoim kluczem API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć plikusecrets.properties, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli skopiujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, a na komputerze lokalnym nie masz jeszcze utworzonego pliku secrets.properties, aby podać klucz interfejsu API.

8. Zapisz plik.
9. W pliku AndroidManifest.xml otwórz 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}" />

   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. Ten starszy identyfikator umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną z nazwy metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek.

10. 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ą.

    Zmień właściwości wtyczki, aby ustawić wartość propertiesFileName na secrets.properties, wartość defaultPropertiesFileName na local.defaults.properties i ustawić 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. Umożliwia to umieszczenie wersji 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 potrzebuje dostępu do lokalizacji użytkownika, musisz poprosić o dostęp do lokalizacji w pliku AndroidManifest.xml. Do wyboru masz opcje ACCESS_FINE_LOCATION, która zapewnia dokładną lokalizację urządzenia, oraz ACCESS_COARSE_LOCATION, która jest mniej dokładna. Szczegółowe informacje znajdziesz w przewodniku dotyczącym danych o lokalizacji.

Uwaga: w szybkim przewodniku 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 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" />

Biblioteka Apache HTTP w starszej wersji

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.
  Uwaga: jeśli zdecydujesz się użyć emulatora Androida, wybierz urządzenie z ikoną Play () wyświetlaną w kolumnie Sklep Play. Ikona ta wskazuje, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemowych, które obejmują aplikację Sklep Play:

  

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żesz wywołać z 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ę.