Configurare un progetto Android Studio

AVVISO: la versione 2.0.0 e successive di Places SDK for Android dipende da AndroidX. A partire da questa versione, la vecchia libreria di assistenza non sarà più supportata. Per mantenere la compatibilità, devi eseguire la migrazione dei tuoi progetti in modo da utilizzare AndroidX.

Per configurare la tua app in modo che utilizzi l'SDK Places per Android, segui questi passaggi. Sono obbligatori per tutte le app che utilizzano l'SDK Places per Android.

Passaggio 1: configura Android Studio

Questo documento descrive un ambiente di sviluppo che utilizza Android Studio Hedgehog e il plug-in Gradle per Android nella versione 8.2.

Nota: se il tuo ambiente di sviluppo utilizza una versione diversa di Android Studio o Gradle, potresti dover modificare i passaggi in base a queste versioni. Per ulteriori informazioni sulle versioni di Android Studio e Gradle, consulta Compatibilità del plug-in Android Gradle e di Android Studio.

Passaggio 2: Configura l'SDK

La libreria Places SDK for Android è disponibile tramite il repository Maven di Google. Per aggiungere l'SDK alla tua app:

1. Nel file settings.gradle.kts di primo livello, includi il portale dei plug-in Gradle, il repository Maven di Google e il repository Maven central nel blocco pluginManagement. Il blocco pluginManagement deve apparire prima di qualsiasi altro statement nello script.

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

2. Nel file settings.gradle.kts di primo livello, includi il repository Maven di Google e il repository centrale Maven nel blocco dependencyResolutionManagement:

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

3. Nella sezione dependencies del file build.gradle.kts a livello di modulo, aggiungi una dipendenza all'SDK Places per Android:

   Nota: l'SDK Places per Android versione 3.5.0 richiede kotlin-bom 1.8.0 o versioni successive. Per maggiori informazioni sulla dipendenza kotlin-bom, consulta Utilizzo della versione più recente di kotlin-stdlib nelle dipendenze traslative.

   Trendy

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

4. Nel file build.gradle.kts a livello di modulo, imposta compileSdk e minSdk su i seguenti valori:
   Nota: assicurati che compileSdk sia impostato su 34 o superiore e minSdk su 23 o superiore.

   Trendy

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

   Kotlin

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

5. Nella sezione buildFeatures del file build.gradle a livello di modulo, aggiungi la classe BuildConfig, che utilizzi per accedere ai valori dei metadati definiti più avanti in questa procedura:

   Trendy

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

   Kotlin

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

Passaggio 3: aggiungi la chiave API al progetto

Questa sezione descrive come archiviare la chiave API in modo che possa essere richiamata in modo sicuro dalla tua app. Non devi controllare la chiave API nel tuo sistema di controllo delle versioni, quindi ti consigliamo di archiviarla nel file secrets.properties, che si trova nella directory principale del progetto. Per ulteriori informazioni sul file secrets.properties, consulta File di proprietà Gradle.

Per semplificare questa attività, ti consigliamo di utilizzare il plug-in Secrets Gradle per Android.

Nota: consulta la documentazione del plug-in Secrets Gradle per Android su GitHub per conoscere i requisiti di sistema e le istruzioni di installazione più recenti.

Per installare il plug-in Secrets Gradle per Android nel tuo progetto Google Maps:

1. In Android Studio, apri il file build.gradle.kts o build.gradle di primo livello e aggiungi il seguente codice all'elemento dependencies in buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Trendy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. Apri il file build.gradle.kts o build.gradle a livello di modulo e aggiungi il seguente codice all'elemento plugins.

   Kotlin

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

   Trendy

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

3. Nel file build.gradle.kts o build.gradle a livello di modulo, assicurati che targetSdk e compileSdk siano impostati su 34.
4. Sincronizza il progetto con Gradle.
5. Apri il file secrets.properties nella directory di primo livello e aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API. Memorizza la chiave in questo file perché secrets.properties è esclusa dal controllo in un sistema di controllo delle versioni.
   Nota: se il file secrets.properties non esiste, crealo nella stessa cartella del file local.properties.

   PLACES_API_KEY=YOUR_API_KEY

6. Crea il file local.defaults.properties nella directory di primo livello, nella stessa cartella del file secrets.properties, quindi aggiungi il codice seguente.

   Nota: inserisci il codice come mostrato. Non sostituire DEFAULT_API_KEY con la tua chiave API.

   PLACES_API_KEY=DEFAULT_API_KEY

   Lo scopo di questo file è fornire una posizione di backup per la chiave API se il file secrets.properties non viene trovato, in modo che le build non falliscano. Questo può accadere se cloni l'app da un sistema di controllo della versione che omette secrets.properties e non hai ancora creato un file secrets.properties localmente per fornire la tua chiave API.

7. In Android Studio, apri il file build.gradle.kts o build.gradle a livello di modulo e modifica la proprietà secrets. Se la proprietà secrets non esiste, aggiungila.

   Modifica le proprietà del plug-in per impostare propertiesFileName su secrets.properties, defaultPropertiesFileName su local.defaults.properties e altre proprietà.

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

   Trendy

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

Passaggio 4: Inizializzare il client dell'API Places

Inizializza l'SDK Places per Android in un'attività o in un frammento. Devi prima decidere quale versione dell'SDK utilizzare: Places SDK for Android o Places SDK for Android (nuovo). Per ulteriori informazioni sulle versioni dei prodotti, consulta Scegliere la versione dell'SDK.

L'esempio seguente mostra come inizializzare l'SDK per entrambe le versioni.

SDK Places per Android (novità)

Passa la chiave API quando chiami 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);
    

Places SDK for Android

Passa la chiave API quando chiami Places.initialize():

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);
    

IMPORTANTE: non aggiungere mai le chiavi API direttamente al codice dell'applicazione. Negli ambienti di produzione, ti consigliamo di utilizzare un meccanismo sicuro per gestire le chiavi API.

Ora puoi iniziare a utilizzare Places SDK for Android.

Passaggio 5: configura un dispositivo Android

Per eseguire un'app che utilizza l'SDK Places per Android, devi eseguirne il deployment su un dispositivo Android o su un emulatore Android basato su Android 5.0 o versioni successive e che includa le API Google.

• Per utilizzare un dispositivo Android, segui le istruzioni riportate in Eseguire app su un dispositivo hardware.
• Per utilizzare un emulatore Android, puoi creare un dispositivo virtuale e installare l'emulatore utilizzando Gestione AVD fornito in dotazione con Android Studio.
  Nota: se scegli di utilizzare un emulatore Android, assicurati di scegliere un dispositivo con l'icona del Play Store, , visualizzata nella colonna Play Store. Questa icona indica che questi profili sono completamente conformi ai requisiti del CTS e possono utilizzare immagini di sistema che includono l'app Play Store:

  

Passaggi successivi

Una volta configurato il progetto, puoi esplorare le app di esempio.