Configurare un progetto Android Studio

AVVISO: La versione 2.0.0 e le versioni successive di Places SDK per Android dipendono da AndroidX. A partire da questa versione, la libreria di supporto precedente non sarà più supportata. Per mantenere la compatibilità, devi eseguire la migrazione dei progetti per utilizzare AndroidX.

Per configurare l'app per l'utilizzo di Places SDK per Android, segui questi passaggi. Sono obbligatori per tutte le app che utilizzano Places SDK per Android.

Passaggio 1: configura Android Studio

Questo documento descrive un ambiente di sviluppo che utilizza Android Studio Hedgehog e il plug-in Android Gradle 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 la pagina relativa al plug-in di Android per Gradle e alla compatibilità di Android Studio.

Passaggio 2. Configurare l'SDK

La libreria Places SDK per Android è disponibile tramite il Repository Maven di Google. Per aggiungere l'SDK alla tua app, procedi nel seguente modo:

1. Nel file settings.gradle di primo livello, includi il portale del plug-in Gradle, il Repository Maven di Google e il repository centrale Maven nel blocco pluginManagement. Il blocco pluginManagement deve apparire prima di qualsiasi altra istruzione nello script.

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

2. Nel file settings.gradle 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 a livello di modulo, aggiungi una dipendenza a Places SDK per Android:

   Nota: l'SDK Places per Android 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 transitive.

   Trendy

   dependencies {
       // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
       implementation 'com.google.android.libraries.places:places:3.3.0'
   }

   Kotlin

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

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

   Trendy

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

   Kotlin

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

5. Nella sezione buildFeatures del file build.gradle a livello di modulo, aggiungi la classe BuildConfig che utilizzerai 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 l'app possa farvi riferimento in modo sicuro. Non dovresti verificare la chiave API nel tuo sistema di controllo della versione, quindi ti consigliamo di memorizzarla nel file secrets.properties, che si trova nella directory radice del tuo progetto. Per ulteriori informazioni sul file secrets.properties, consulta File delle proprietà di 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 i requisiti di sistema più recenti e le istruzioni di installazione.

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

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

   Trendy

   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. Apri il file build.gradle a livello di modulo e aggiungi il seguente codice all'elemento plugins.

   Trendy

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

   Kotlin

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

3. Nel file build.gradle a livello di modulo, assicurati che targetSdk e compileSdk siano impostati su 34.
4. Salva il file e sincronizza il progetto con Gradle.
5. Apri il file secrets.properties nella directory di primo livello, quindi aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API. Archivia la chiave in questo file perché secrets.properties è escluso dall'archiviazione in un sistema di controllo della versione.
   Nota: se il file secrets.properties non esiste, crealo nella stessa cartella del file local.properties.

   PLACES_API_KEY=YOUR_API_KEY

6. Salva il file.

7. Crea il file local.defaults.properties nella directory di primo livello, la 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 un percorso di backup per la chiave API se non viene trovato il file secrets.properties, in modo da evitare errori di build. Questo può accadere se cloni l'app da un sistema di controllo della versione che omette secrets.properties e non hai ancora creato in locale un file secrets.properties per fornire la tua chiave API.

8. Salva il file.

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

   Modifica le proprietà del plug-in impostando propertiesFileName su secrets.properties, imposta defaultPropertiesFileName su local.defaults.properties e imposta eventuali altre proprietà.

   Trendy

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

Passaggio 4. Inizializzare il client API Places

Inizializza Places SDK per Android all'interno di un'attività o di un frammento. Devi prima decidere quale versione dell'SDK utilizzare: Places SDK for Android o Places SDK for Android (nuova). Per maggiori informazioni sulle versioni del prodotto, 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 durante la chiamata a 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 durante la chiamata a 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, consigliamo di utilizzare un meccanismo sicuro per gestire le chiavi API.

Ora puoi iniziare a utilizzare Places SDK per Android.

Passaggio 5: configura un dispositivo Android

Per eseguire un'app che utilizza Places SDK per Android, devi eseguirne il deployment su un dispositivo Android o in un emulatore Android basato su Android 5.0 o versioni successive che includa le API di 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 installarlo utilizzando lo strumento Gestione dispositivi virtuali (AVD) Android (Android Virtual Device, Gestione AVD) fornito in Android Studio.
  Nota: se scegli di utilizzare un emulatore Android, assicurati di scegliere un dispositivo con l'icona Riproduci, , visualizzata nella colonna Play Store. Questa icona indica che questi profili sono completamente conformi alla CTS e potrebbero utilizzare immagini di sistema che includono l'app Play Store:

  

Passaggi successivi

Dopo aver configurato il progetto, puoi esplorare le app di esempio.