Guida rapida di Maps SDK for Android

Creare un'app Android che mostri una mappa utilizzando il modello di Google Maps per Android Studio. Se hai un progetto Android Studio esistente che vuoi impostare, consulta la sezione Configurazione del progetto.

Questa guida rapida è rivolta agli sviluppatori che hanno familiarità con lo sviluppo Android di base con Java o Kotlin.

Configura l'ambiente di sviluppo

1. È necessario Android Studio Arctic Fox o versioni successive. Se non lo hai già fatto, scaricalo e installalo.
2. Assicurati di utilizzare il plug-in Android per Gradle 7.0 o versioni successive in Android Studio.

Configurare un dispositivo Android

Per eseguire un'app che utilizza l'SDK Maps per Android, devi eseguirne il deployment su un dispositivo Android o nell'emulatore Android basato su Android 4.0 o versioni successive e che include le API di Google.

• Per utilizzare un dispositivo Android, segui le istruzioni su come eseguire app su un dispositivo hardware.
• Per utilizzare un emulatore Android, puoi creare un dispositivo virtuale e installare l'emulatore utilizzando Android Virtual Device (AVD) Manager fornito con Android Studio.
  Nota: se scegli di utilizzare un emulatore Android, assicurati di scegliere un dispositivo con l'icona Google Play, , visualizzata nella colonna Play Store. Questa icona indica che questi profili sono completamente conformi al CTS e possono utilizzare immagini di sistema che includono l'app Play Store:

  

Creare un progetto in Google Maps in Android Studio

1. Apri Android Studio e fai clic su Crea nuovo progetto nella finestra Ti diamo il benvenuto in Android Studio.

2. Nella finestra Nuovo progetto, nella categoria Telefono e tablet, seleziona Attività su Google Maps e poi fai clic su Avanti.

3. Compila il modulo Attività su Google Maps:

   • Imposta Linguaggio su Java o Kotlin. Entrambe le lingue sono pienamente supportate dall'SDK Maps per Android. Per scoprire di più su Kotlin, consulta Sviluppare app Android con Kotlin.

   • Imposta l'SDK minimo su una versione dell'SDK compatibile con il tuo dispositivo di test. Devi selezionare una versione superiore a quella minima richiesta dall'SDK Maps per Android 18.0.x, che al momento è il Livello API Android 19 (Android 4.4, KitKat) o versioni successive. Consulta le Note di rilascio per informazioni più recenti sui requisiti della versione dell'SDK.

     Nota: se hai dubbi su quale versione dell'SDK scegliere, seleziona il link Aiutami a scegliere per visualizzare le informazioni sulla distribuzione degli SDK Android supportati. Ad esempio, se scegli API 19: Android 4.4 (KitKat), la tua app dovrebbe essere eseguita su più del 99% dei dispositivi Android.

4. Fai clic su Fine.

   Android Studio avvia Gradle e crea il progetto. Questa operazione potrebbe richiedere del tempo.

5. Quando la build è completata, Android Studio apre i file AndroidManifest.xml e MapsActivity. L'attività potrebbe avere un nome diverso, ma sarà uguale a quello che hai configurato durante la configurazione.

6. Il file AndroidManifest.xml contiene istruzioni su come ottenere una chiave API di Google Maps e poi l'aggiungi al file local.properties. Non aggiungere la chiave API al file AndroidManifest.xml. In questo modo, la chiave API viene archiviata in modo meno sicuro. Segui invece le istruzioni nelle sezioni successive per creare un progetto Cloud e configurare una chiave API.

Configurare il progetto Google Cloud

Completa i passaggi di configurazione di Cloud Console richiesti facendo clic sulle seguenti schede:

Passaggio 1

Console

1. Nella pagina del selettore di progetti in Google Cloud Console, fai clic su Crea progetto per iniziare a creare un nuovo progetto Cloud.

   Vai alla pagina del selettore progetti

2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Verifica che la fatturazione sia attivata per il tuo progetto.

   Google Cloud offre una prova di addebito di 0,00 $. La prova scade al termine di 90 giorni o dopo che l'account ha maturato addebiti per 300 $, a seconda dell'evento che si verifica per primo. Puoi annullare in qualsiasi momento. Google Maps Platform prevede un credito mensile di 200 $. Per maggiori informazioni, consulta Crediti account di fatturazione e Fatturazione.

Cloud SDK

gcloud projects create "PROJECT"

Scopri di più su Google Cloud SDK, Installazione di Cloud SDK e sui seguenti comandi:

• gcloud projects create

Nota: se non prevedi di conservare le risorse che crei in un esercizio di apprendimento, crea un progetto invece di selezionarne uno esistente. Al termine dell'esercizio, puoi eliminare il progetto e rimuovere tutte le risorse associate.

Passaggio 2

Per utilizzare Google Maps Platform, devi abilitare le API o gli SDK che prevedi di utilizzare con il tuo progetto.

Console

Attivare l'SDK Maps per Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Scopri di più su Google Cloud SDK, Installazione di Cloud SDK e sui seguenti comandi:

• gcloud services enable
• gcloud services disable

Passaggio 3

Questo passaggio riguarda solo il processo di creazione della chiave API. Se utilizzi la chiave API in produzione, ti consigliamo vivamente di limitare la chiave API. Puoi trovare ulteriori informazioni nella pagina Utilizzo di chiavi API specifica del prodotto.

La chiave API è un identificatore univoco che autentica le richieste associate al tuo progetto ai fini dell'utilizzo e della fatturazione. Devi avere almeno una chiave API associata al tuo progetto.

Per creare una chiave API:

Console

1. Vai alla pagina Google Maps Platform > Credenziali.

   Vai alla pagina Credenziali

2. Nella pagina Credenziali, fai clic su Crea credenziali > Chiave API.
   La finestra di dialogo Chiave API creata mostra la chiave API appena creata.
3. Fai clic su Chiudi.
   La nuova chiave API è indicata nella pagina Credenziali nella sezione Chiavi API.
   (Ricorda di limitare la chiave API prima di utilizzarla in produzione.)

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Scopri di più su Google Cloud SDK, Installazione di Cloud SDK e sui seguenti comandi:

• gcloud alpha services api-keys create

Aggiungi la chiave API alla tua app

Questa sezione descrive come archiviare la chiave API in modo che sia possibile farvi riferimento in modo sicuro dalla tua app. Non dovresti controllare la chiave API nel sistema di controllo della versione, quindi ti consigliamo di archiviarla nel file local.properties, che si trova nella directory principale del progetto. Per ulteriori informazioni sul file local.properties, consulta File delle proprietà di Gradle.

Per semplificare questa attività, ti consigliamo di utilizzare il plug-in Secrets Gradle per Android. Per installare il plug-in e archiviare la chiave API:

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

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

2. Quindi, apri il file build.gradle a livello di modulo e aggiungi il seguente codice all'elemento plugins.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. Salva il file e sincronizza il tuo progetto con Gradle.
4. Apri local.properties nella directory a livello di progetto e aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API.

   MAPS_API_KEY=YOUR_API_KEY
       

5. Salva il file.
6. Nel file AndroidManifest.xml, vai a com.google.android.geo.API_KEY e aggiorna android:value attribute come segue:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

Nota: come mostrato sopra, com.google.android.geo.API_KEY è il nome di metadati consigliato per la chiave API. Una chiave con questo nome può essere utilizzata per eseguire l'autenticazione su più API basate su Google Maps sulla piattaforma Android, incluso l'SDK Maps per Android. Per la compatibilità con le versioni precedenti, l'API supporta anche il nome com.google.android.maps.v2.API_KEY. Questo nome legacy consente l'autenticazione soltanto nella versione 2 dell'API Android Maps. Un'applicazione può specificare solo uno dei nomi di metadati della chiave API. Se entrambi sono specificati, l'API genera un'eccezione.

Guarda il codice

Esamina il codice fornito dal modello. In particolare, dai un'occhiata ai file che seguono nel tuo progetto Android Studio.

File di attività su Maps

Il file delle attività di Maps è l'attività principale dell'app e contiene il codice per gestire e visualizzare la mappa. Per impostazione predefinita, il file che definisce l'attività è denominato MapsActivity.java o se imposti Kotlin come lingua della tua app, MapsActivity.kt.

Gli elementi principali dell'attività sulle mappe:

• L'oggetto SupportMapFragment gestisce il ciclo di vita della mappa ed è l'elemento principale dell'interfaccia utente dell'app.

• L'oggetto GoogleMap fornisce accesso ai dati e alla visualizzazione della mappa. Questa è la classe principale dell'SDK di Maps per Android. La guida Map Objects descrive in modo più dettagliato gli oggetti SupportMapFragment e GoogleMap.

• La funzione moveCamera centra la mappa sulle coordinate di LatLng per Sydney Australia. Le prime impostazioni da configurare quando si aggiunge una mappa di solito sono la posizione della mappa e le impostazioni della fotocamera, ad esempio l'angolo di visualizzazione, l'orientamento della mappa e il livello di zoom. Per maggiori dettagli, consulta la guida Fotocamera e vista.

• La funzione addMarker aggiunge un indicatore alle coordinate per Sydney. Per informazioni dettagliate, consulta la guida Indicatori.

Il file dell'attività sulla mappa contiene il seguente codice:

Java

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

File Gradle del modulo

Il file Modulo build.gradle include le seguenti dipendenze mappa, richieste dall'SDK di Maps per Android.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}

Nota: la versione esatta può cambiare in base alla versione attuale di Maps SDK per Android.

Per scoprire di più sulla gestione della dipendenza per Maps, consulta Controllo delle versioni.

File di layout XML

Il file activity_maps.xml è il file di layout XML che definisce la struttura della UI dell'app. Il file si trova nella directory res/layout. Il file activity_maps.xml dichiara un frammento che include i seguenti elementi:

• tools:context imposta su MapsActivity l'attività predefinita del frammento, che è definita nel file dell'attività sulla mappa.
• android:name imposta il nome della classe del frammento su SupportMapFragment, che è il tipo di frammento utilizzato nel file attività della mappa.

Il file di layout XML contiene il seguente codice:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Eseguire il deployment dell'app ed eseguirla

Se esegui correttamente l'app, viene visualizzata una mappa centrata su Sydney Australia con un indicatore sulla città come mostrato nello screenshot seguente.

Per implementare ed eseguire l'app:

1. In Android Studio, fai clic sull'opzione di menu Esegui (o sull'icona del pulsante di riproduzione) per eseguire l'app.
2. Quando ti viene chiesto di scegliere un dispositivo, scegli una delle seguenti opzioni:
   • Seleziona il dispositivo Android collegato al computer.
   • In alternativa, seleziona il pulsante di opzione Avvia emulatore e scegli il dispositivo virtuale che hai configurato.
3. Fai clic su OK. Android Studio avvia Gradle per creare la tua app, quindi mostra i risultati sul tuo dispositivo o emulatore. Potrebbero essere necessari diversi minuti prima del lancio dell'app.

Passaggi successivi

• Configurare una mappa: questo argomento descrive come configurare le impostazioni iniziali e di runtime della mappa, ad esempio la posizione della fotocamera, il tipo di mappa, i componenti dell'interfaccia utente e i gesti.

• Aggiungi una mappa alla tua app Android (Kotlin): questo codelab ti spiega un'app che illustra alcune funzionalità aggiuntive dell'SDK Maps per Android.

• Utilizza la libreria KTX di Android per Maps: questa libreria di estensioni Kotlin (KTX) ti consente di sfruttare diverse funzionalità in lingua Kotlin durante l'utilizzo dell'SDK Maps per Android.