Questa pagina è stata tradotta dall'API Cloud Translation.

Guida rapida di Maps SDK for Android

Creare un'app Android che mostra una mappa utilizzando il modello di Google Maps per Android Studio. Se hai un progetto Android Studio esistente che vuoi configurare, consulta l'articolo Configurazione del progetto.

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

Configurare l'ambiente di sviluppo

È necessario Android Studio Arctic Fox o versioni successive. Se non l'hai ancora fatto, scaricala e installala.
Assicurati di utilizzare il plug-in Android per Gradle versione 7.0 o 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 un emulatore Android basato su Android 4.0 o versioni successive e con le API di Google.

Per usare un dispositivo Android, segui le istruzioni su come eseguire le app su un dispositivo hardware.
Per utilizzare un emulatore Android, puoi creare un dispositivo virtuale e installarlo 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 Riproduci, , visualizzata nella colonna Play Store. Questa icona indica che questi profili sono completamente conformi alla tecnologia CTS e potrebbero usare immagini di sistema che includono l'app Play Store:

Creare un progetto di Google Maps in Android Studio

Apri Android Studio e fai clic su Crea nuovo progetto nella finestra Ti diamo il benvenuto in Android Studio.
Nella finestra Nuovo progetto, nella categoria Telefono e tablet, seleziona Attività su Google Maps, poi fai clic su Avanti.
Compila il modulo Attività di 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 il valore 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 di Maps per Android versione 18.0.x, che attualmente è l'API Android di livello 19 (Android 4.4, KitKat). Consulta le Note di rilascio per informazioni aggiornate sui requisiti delle versioni dell'SDK.
  
  Nota: se non sai con certezza quale versione dell'SDK scegliere, seleziona il link Aiutami a scegliere per visualizzare le informazioni sulla distribuzione per gli SDK Android supportati. Ad esempio, se scegli API 19: Android 4.4 (KitKat), l'app verrà eseguita su oltre il 99% dei dispositivi Android.
Fai clic su Fine.

Android Studio avvia Gradle e crea il progetto. Questa operazione potrebbe richiedere del tempo.
Al termine della build, Android Studio apre i file AndroidManifest.xml e MapsActivity. L'attività potrebbe avere un nome diverso, ma sarà quello che hai configurato durante la configurazione.
Il file AndroidManifest.xml contiene istruzioni su come 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 di Cloud Console richiesti facendo clic sulle seguenti schede:

Passaggio 1

Console

Nella pagina del selettore dei progetti, fai clic su Crea progetto nella console Google Cloud, per iniziare a creare un nuovo progetto Cloud.

Vai alla pagina del selettore dei progetti
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 alla fine di 90 giorni o dopo che l'account ha maturato addebiti per un importo di 300 $, a seconda dell'evento che si verifica per primo. Puoi annullare l'abbonamento in qualsiasi momento. Google Maps Platform offre un credito mensile ricorrente di 200 $. Per saperne di più, consulta Crediti all'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

Passaggio 2

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

Console

Attiva 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:

Passaggio 3

Questo passaggio riguarda solo la procedura di creazione della chiave API. Se utilizzi la chiave API in produzione, ti consigliamo vivamente di limitarla. Per ulteriori informazioni, consulta la pagina specifica Utilizzo delle chiavi API in relazione al 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 progetto.

Per creare una chiave API:

Console

Vai alla pagina Google Maps Platform > Credenziali.

Vai alla pagina Credenziali
Nella pagina Credenziali, fai clic su Crea credenziali > Chiave API.
Nella finestra di dialogo Chiave API creata viene mostrata la chiave API appena creata.
Fai clic su Chiudi.
La nuova chiave API è elencata nella pagina Credenziali in 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 possa essere fatto riferimento in modo sicuro dall'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à 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:

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
}
```
Apri il file build.gradle a livello di modulo e aggiungi il codice seguente all'elemento plugins.
```
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    
```
Salva il file e sincronizza il progetto con Gradle.
Apri local.properties nella directory a livello di progetto e aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la chiave API.
```
MAPS_API_KEY=YOUR_API_KEY
    
```
Salva il file.

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 consigliato dei metadati 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, tra cui l'SDK di 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 solo nella versione 2 dell'API Android Maps. Un'applicazione può specificare solo uno dei nomi dei metadati della chiave API. Se entrambi sono specificati, l'API genera un'eccezione.

Guarda il codice

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

File attività di Maps

Il file dell'attività della mappa è l'attività principale dell'app e contiene il codice per gestire e visualizzare la mappa. Per impostazione predefinita, il nome del file che definisce l'attività è MapsActivity.java oppure, 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 l'accesso ai dati e alla visualizzazione della mappa. Questa è la classe principale dell'SDK di Maps per Android. La guida Mappa oggetti descrive gli oggetti SupportMapFragment e GoogleMap in modo più dettagliato.
La funzione moveCamera centra la mappa alle coordinate LatLng di Sydney, in Australia. Le prime impostazioni da configurare quando aggiungi una mappa sono in genere la posizione della mappa e le impostazioni della fotocamera, ad esempio l'angolo di visualizzazione, l'orientamento della mappa e il livello di zoom. Consulta la guida Videocamera e vista per i dettagli.
La funzione addMarker aggiunge un indicatore alle coordinate per Sydney. Per informazioni dettagliate, consulta la guida Markers.

Il file di attività delle mappe 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 di mappa, richieste dall'SDK di Maps per 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'interfaccia utente dell'app. Il file si trova nella directory res/layout. Nel file activity_maps.xml viene dichiarato un frammento che include i seguenti elementi:

tools:context imposta l'attività predefinita del frammento su MapsActivity, definita nel file Attività della 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

Screenshot con mappa e indicatore centrato su Syndney Australia.

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

Per il deployment e l'esecuzione dell'app:

In Android Studio, fai clic sull'opzione di menu Esegui (o sull'icona del pulsante di riproduzione) per eseguire l'app.
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.
Fai clic su OK. Android Studio avvia Gradle per creare la tua app, quindi mostra i risultati sul dispositivo o sull'emulatore. Potrebbero essere necessari diversi minuti prima che l'app venga avviata.

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 guiderà in un'app che illustra alcune funzionalità aggiuntive dell'SDK Maps per Android.
Utilizza la libreria KTX di Maps per Android: questa libreria di estensioni Kotlin (KTX) ti consente di sfruttare diverse funzionalità dei linguaggi Kotlin durante l'utilizzo dell'SDK Maps per Android.