Konfigurowanie projektu na Androida Studio

UWAGA: pakiet SDK Miejsc na Androida w wersji 2.0.0 i nowszych jest zależny od AndroidX. Począwszy od tej wersji, stara biblioteka pomocy nie będzie już obsługiwana. Aby zachować zgodność, musisz przenieść projekty na AndroidX.

Aby skonfigurować aplikację do korzystania z pakietu Places SDK for Android, wykonaj te czynności. Są one wymagane we wszystkich aplikacjach korzystających z pakietu Places SDK for Android.

Krok 1. Skonfiguruj Android Studio

W tym dokumencie opisano ś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 używa innej wersji Android Studio lub Gradle, być może musisz zmodyfikować kroki w zależności od tych wersji. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule o zgodności wtyczki Androida do obsługi Gradle i Android Studio.

Krok 2. Konfigurowanie pakietu SDK

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

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

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

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.PREFER_SETTINGS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. W sekcji dependencies pliku build.gradle.kts na poziomie modułu dodaj zależność do pakietu SDK Miejsc na Androida:

   Uwaga: pakiet SDK Miejsc na Androida w wersji 3.5.0 wymaga kotlin-bom w wersji 1.8.0 lub nowszej. Więcej informacji o zależności kotlin-bom znajdziesz w artykule Usage of the latest kotlin-stdlib version in transitive dependencies (w języku angielskim).

   Zakręcony

   dependencies {
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
       implementation("com.google.android.libraries.places:places:3.5.0")
   }

   Kotlin

             dependencies {
   
       // Places and Maps SDKs
       implementation("com.google.android.libraries.places:places:6.0.2")
   }

4. W pliku build.gradle.kts na poziomie modułu ustaw compileSdk i minSdk na te wartości:
   Uwaga: upewnij się, że compileSdk jest ustawione na 34 lub więcej, a minSdk na 23 lub więcej.

   Zakręcony

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

   Kotlin

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

5. W sekcji buildFeatures pliku build.gradle na poziomie modułu dodaj klasę BuildConfig, której użyjesz do uzyskania dostępu 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 opisano, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie 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 na ten temat.

Aby uprościć to zadanie, zalecamy użycie wtyczki Secrets Gradle do 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
   }

   Zakręcony

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

   Zakręcony

   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 secrets.properties w katalogu najwyższego poziomu i dodaj podany niżej kod. Zastąp YOUR_API_KEY kluczem interfejsu API. Dodaj secrets.properties do pliku .gitignore (lub w inny sposób wyklucz go z systemu kontroli wersji), aby nie sprawdzać klucza interfejsu API w systemie kontroli wersji.
   Uwaga: jeśli plik secrets.properties nie istnieje, utwórz go w tym samym folderze co plik local.properties.

   PLACES_API_KEY=YOUR_API_KEY

5. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze, w którym znajduje się plik secrets.properties, a następnie dodaj podany niżej kod.

   Uwaga: wpisz kod w wyświetlonej postaci. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   PLACES_API_KEY=DEFAULT_API_KEY

   Ten plik służy do podania zapasowej lokalizacji klucza interfejsu API, jeśli nie można znaleźć pliku secrets.properties, aby kompilacje nie kończyły się niepowodzeniem. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, i nie utworzysz jeszcze lokalnie pliku secrets.properties, aby podać klucz interfejsu API.

6. 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", defaultPropertiesFileName na "local.defaults.properties" i skonfigurować 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"
   }

   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 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. Inicjowanie klienta Places API

Aby zainicjować pakiet Places SDK for Android w aktywności lub fragmencie, przekaż klucz interfejsu API podczas wywoływania metody Places.initializeWithNewPlacesApiEnabled():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

WAŻNE: nigdy nie dodawaj kluczy interfejsu API bezpośrednio do kodu aplikacji. W środowiskach produkcyjnych zalecamy używanie bezpiecznego mechanizmu do zarządzania kluczami interfejsu API.

Możesz już zacząć korzystać z pakietu SDK Miejsc na Androida.

Krok 5. Skonfiguruj urządzenie z Androidem

Aby uruchomić aplikację, która korzysta z pakietu Places SDK for Android, musisz ją wdrożyć na urządzeniu z Androidem lub w emulatorze Androida z systemem Android 6.0 lub nowszym i interfejsami API Google.

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

  

  Okno Dodaj urządzenie w Menedżerze urządzeń Android Studio, w którym widać profile urządzeń wirtualnych z ikoną Google Play w kolumnie Play.

Dalsze kroki

Po skonfigurowaniu projektu możesz zapoznać się z przykładowymi aplikacjami.