Konfigurowanie projektu na Androida Studio

UWAGA: Pakiet SDK Miejsc na Androida w wersji 2.0.0 i nowszych jest zależny od AndroidX. 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 SDK Miejsc na Androida, wykonaj te czynności. Są one wymagane w przypadku wszystkich aplikacji korzystających z pakietu SDK Miejsc na Androida.

Krok 1. Skonfiguruj Android Studio

W tym dokumencie opisujemy środowisko programistyczne korzystające z Androida Studio Hedgehog i wtyczki Androida Gradle w wersji 8.2.

Uwaga: jeśli w środowisku programistycznym używasz innej wersji Androida Studio lub Gradle, może być konieczne zmodyfikowanie tych kroków. 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 pakietu SDK Miejsc na Androida jest dostępna w repozytorium Google Maven. Aby dodać pakiet SDK do aplikacji:

1. W pliku settings.gradle.kts najwyższego poziomu dodaj portal wtyczek Gradle, repozytorium Google Maven i centralne repozytorium Maven w bloku pluginManagement. Blok pluginManagement musi występować przed wszystkimi 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 sekcji dependencies pliku build.gradle.kts na poziomie modułu dodaj zależność od pakietu SDK Miejsc na Androida:

   Uwaga: pakiet SDK Miejsc Google 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 Używanie najnowszej wersji kotlin-stdlib w zależnościach przechodnich.

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

4. W pliku build.gradle.kts na poziomie modułu ustaw compileSdk i minSdk na te wartości:
   Uwaga: upewnij się, że compileSdk ma wartość co najmniej 34, a minSdk co najmniej 23.

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

   Zakręcony

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

   Kotlin

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

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 umieszczać klucza interfejsu API w systemie 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 uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

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

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

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

   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 upewnij się, że wartości targetSdk i compileSdk to 34.
4. 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. Przechowuj 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.

   PLACES_API_KEY=YOUR_API_KEY

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

   Uwaga: wpisz kod w takiej formie, w jakiej się wyświetla. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   PLACES_API_KEY=DEFAULT_API_KEY

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

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

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

Krok 4. Inicjowanie klienta interfejsu Places API

Zainicjuj pakiet SDK Miejsc na Androida w aktywności lub fragmencie. Najpierw musisz zdecydować, której wersji pakietu SDK chcesz używać: Places SDK na Androida czy Places SDK na Androida (nowy). Więcej informacji o wersjach produktów znajdziesz w artykule Wybierz wersję pakietu SDK.

Poniższy przykład pokazuje, jak zainicjować pakiet SDK w przypadku obu wersji.

Pakiet SDK Miejsc na Androida (nowy)

Przekaż klucz interfejsu API podczas wywoływania 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);
    

Pakiet SDK Miejsc na Androida

Przekaż klucz interfejsu API podczas wywoływania 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.initialize(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.initialize(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 Places SDK na Androida.

Krok 5. Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację korzystającą z pakietu Places SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida opartym na Androidzie 5.0 lub nowszym, który zawiera interfejsy API Google.

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

  

Dalsze kroki

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