Konfigurowanie projektu na Androida Studio

Z tego artykułu dowiesz się, jak skonfigurować projekt Android Studio tak, aby używał pakietu SDK Map Google na Androida bez korzystania z szablonu Map Google opisanego w krótkim wprowadzeniu.

Szablon Map Google automatycznie konfiguruje mapę podstawową i dodaje ją do nowego projektu 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 do Androida do obsługi Gradle w wersji 8.2.

Krok 2. Skonfiguruj pakiet SDK

Biblioteka pakietu 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 najwyższego poziomu umieść w bloku pluginManagement portal wtyczki Gradle, repozytorium Google Maven i centralne repozytorium Maven. Blok pluginManagement musi znajdować się przed innymi instrukcjami w skrypcie.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. W pliku settings.gradle najwyższego poziomu umieść w bloku dependencyResolutionManagement repozytorium Google Maven i centralne repozytorium Maven:
    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 Map Google na Androida.

    Zakręcony

    dependencies {
    
        // Maps SDK for Android
        implementation 'com.google.android.gms:play-services-maps:18.2.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:

    Zakręcony

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

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 19
            // ...
        }
    }
  5. W sekcji buildFeatures pliku build.gradle na poziomie modułu dodaj klasę BuildConfig, której możesz użyć, by uzyskać dostęp do wartości metadanych zdefiniowanych później w tej procedurze:

    Zakręcony

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

    Kotlin

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

Krok 3. Dodaj do projektu klucz interfejsu API

W tej sekcji opisujemy, jak zapisać klucz interfejsu API, aby aplikacja mogła bezpiecznie się do niego odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, dlatego 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 uprościć to zadanie, zalecamy korzystanie z wtyczki Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę Secrets Gradle na Androida w projekcie Map Google:

  1. W Android Studio otwórz plik build.gradle lub build.gradle.kts najwyższego poziomu i dodaj ten 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 do elementu plugins poniższy kod.

    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 i dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Zapisz klucz w tym pliku, ponieważ adres secrets.properties nie jest rejestrowany w systemie kontroli wersji.
    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.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy do podania lokalizacji kopii zapasowej klucza interfejsu API na wypadek, gdyby nie udało się znaleźć pliku secrets.properties, co pozwoli uniknąć błędów kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija element secrets.properties, i nie utworzyłeś jeszcze lokalnie pliku secrets.properties zawierającego Twój klucz interfejsu API.

  8. Zapisz plik.
  9. W pliku AndroidManifest.xml przejdź do 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 opisujemy ustawienia, które należy dodać do pliku AndroidManifest.xml.

Numer wersji Usług Google Play

Dodaj poniższą deklarację w elemencie application. Zawiera 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 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 (mniej precyzyjna). Więcej informacji znajdziesz w przewodniku po danych o lokalizacji.

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

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

Uprawnienia do pamięci zewnętrznej

Jeśli kierujesz reklamy na pakiet SDK Usług Google Play w wersji 8.3 lub nowszej, nie musisz mieć uprawnienia WRITE_EXTERNAL_STORAGE. Jeśli kierujesz reklamy 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" />

Starsza biblioteka HTTP Apache

Jeśli używasz pakietu com.google.android.gms:play-services-maps:16.0.0 lub niższego, a Twoja aplikacja jest kierowana na interfejs API na poziomie 28 (Android 9.0) lub nowszym, w elemencie <application> elementu AndroidManifest.xml musisz umieścić 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 SDK Map Google na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub w emulatorze Androida w wersji 4.0 lub nowszej, która zawiera interfejsy API Google.

  • Aby używać urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu sprzętowym.
  • Jeśli chcesz użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować go za pomocą Menedżera urządzeń wirtualnych (AVD) Android dołączonego do Android Studio.

Krok 6. Opcjonalnie sprawdź dostępność obsługi Usługi Play

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

Dalsze kroki

Po skonfigurowaniu projektu możesz dodać mapę.