Guida rapida all'SDK Maps per Android

Crea un'app Android che mostri una mappa utilizzando il modello di Google Maps per Android Studio. Se hai già un progetto Android Studio che vuoi configurare, consulta Configurazione progetto.

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

Configura l'ambiente di sviluppo

1. È richiesto Android Studio Arctic Fox o versioni successive. Se non l'hai ancora fatto, scaricala e installala.
2. Assicurati di utilizzare il plug-in Android per Gradle versione 7.0 o successiva in Android Studio.

• 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 Android (AVD) fornito in Android Studio.

Creare un progetto Google Maps in Android Studio

La procedura per creare un progetto Google Maps in Android Studio è stata modificata in Flamingo e nelle versioni successive di Android Studio. Assicurati di seguire i passaggi riportati di seguito per la tua versione specifica di 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 l'Attività vuota e fai clic su Avanti.

3. Compila il modulo Attività sulle mappe Google Maps:

   • Imposta Language su Java o Kotlin. Entrambe le lingue sono completamente supportate da Maps SDK for Android. Per scoprire di più su Kotlin, consulta la pagina 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 da Maps SDK per Android versione 18.0.x, ovvero il livello API Android 19 (Android 4.4, Lollipop) o versioni successive. Consulta le Note di rilascio per le informazioni più recenti sui requisiti di versione dell'SDK.

4. Fai clic su Fine.

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

5. Al termine della build, Android Studio apre i file AndroidManifest.xml e MapsActivity. L'attività potrebbe avere un nome diverso, ma è quello che hai configurato durante la configurazione.

6. Aggiungi l'attività di Google Maps Views:

   1. Fai clic con il pulsante destro del mouse sul pacchetto in cui vuoi aggiungere l'attività di visualizzazione di Google Maps.
   2. Seleziona Nuovo > Google > Attività di Google Maps Views.

   

   Per saperne di più, consulta Aggiungere codice da un modello

7. Il file AndroidManifest.xml contiene le istruzioni per ottenere una chiave API di Google Maps e aggiungerla 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.

Configura il tuo progetto Google Cloud

Completa i passaggi di configurazione richiesti per la console Cloud facendo clic sulle seguenti schede:

gcloud projects create "PROJECT"

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

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

Aggiungi la chiave API alla tua app

Questa sezione descrive come memorizzare la chiave API in modo che la tua app possa fare riferimento in modo sicuro alla chiave. Non devi controllare la chiave API nel sistema di controllo della versione, pertanto ti consigliamo di memorizzarla nel file local.properties, che si trova nella directory principale del progetto. Per ulteriori informazioni sul file local.properties, consulta la sezione File delle proprietà Gradle.

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

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

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

2. Successivamente, 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 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 dei metadati consigliato per la chiave API. Una chiave con questo nome può essere utilizzata per l'autenticazione a più API basate su Google Maps sulla piattaforma Android, incluso Maps SDK for 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 solo nell'API Android Maps v2. Un'applicazione può specificare solo uno dei nomi dei metadati della chiave API. Se vengono specificati entrambi, l'API genera un'eccezione.

Controlla il codice

Esamina il codice fornito dal modello. Esamina in particolare i seguenti file nel tuo progetto Android Studio.

File delle attività sulle mappe

Il file delle attività sulle mappe rappresenta l'attività principale dell'app e contiene il codice per la gestione e la visualizzazione della mappa. Per impostazione predefinita, il file che definisce l'attività è denominato MapsActivity.java o, se imposti Kotlin come lingua dell'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'UI dell'app.

• L'oggetto GoogleMap fornisce l'accesso ai dati e alla visualizzazione della mappa. Questa è la classe principale di Maps SDK per Android. La guida Mappa oggetti descrive in maggiore dettaglio gli oggetti SupportMapFragment e GoogleMap.

• La funzione moveCamera centra la mappa in base alle coordinate di LatLng per Sydney Australia. Le prime impostazioni da configurare quando aggiungi una mappa sono in genere la posizione sulla mappa e le impostazioni della fotocamera, come l'angolo di visualizzazione, l'orientamento della mappa e il livello di zoom. Per i dettagli, consulta la guida Fotocamera e visualizzazione.

• La funzione addMarker aggiunge un indicatore alle coordinate di Sydney. Per informazioni dettagliate, consulta la guida relativa agli indicatori.

Il file delle attività sulle mappe contiene il seguente codice:

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

      

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 dei moduli

Il file del modulo build.gradle include la seguente dipendenza per le mappe, richiesta da Maps SDK for Android.

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

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

File di layout XML

Il file activity_maps.xml è il file di layout XML che definisce la struttura dell'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 l'attività predefinita del frammento su MapsActivity, definita nel file dell'attività delle mappe.
• android:name imposta il nome della classe del frammento su SupportMapFragment, che è il tipo di frammento utilizzato nel file delle attività delle mappe.

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

Esegui il deployment dell'app

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

Per eseguire il deployment dell'app ed eseguirla:

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 avvierà Gradle per creare la tua app, quindi mostrerà i risultati sul tuo dispositivo o emulatore. L'avvio dell'app potrebbe richiedere diversi minuti.

Passaggi successivi

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

• Aggiunta di una mappa alla tua app per Android (Kotlin): questo codelab ti guida nella procedura di un'app che illustra alcune funzionalità aggiuntive dell'SDK Maps per Android.

• Utilizza la libreria KTX per Android di Maps: questa libreria di estensioni Kotlin (KTX) ti consente di sfruttare diverse funzionalità della lingua di Kotlin mentre utilizzi l'SDK Maps per Android.