Configurazione

Questa pagina descrive cosa devi fare per iniziare a creare con l'SDK Maps 3D per Android. La procedura di configurazione prevede la configurazione di un progetto Google Cloud e di un'API da utilizzare con l'SDK, seguita dalla configurazione di un progetto Android Studio. Completa questi passaggi prima di aggiungere la tua prima mappa 3D alla tua app.

Prerequisiti

Per utilizzare Maps 3D SDK for Android, il progetto e i dispositivi di destinazione devono soddisfare i seguenti requisiti:

  • Livello API minimo: livello API Android 24 (Android 7.0) o versioni successive. La tua app deve avere come target un minSdk di 24 o versioni successive.
  • Google Play Services: Maps 3D SDK for Android dipende da Google Play Services. Sui dispositivi di destinazione (e sugli emulatori con API di Google) deve essere installato Google Play Services.

Configura un progetto Google Cloud e una chiave API

Prima di poter iniziare a creare con l'SDK Maps 3D per Android, devi configurare un progetto Google Cloud e una chiave API da utilizzare con l'SDK Maps 3D per Android completando i seguenti passaggi:

Passaggio 1

Console

  1. Nella console Google Cloud, nella pagina di selezione del progetto, fai clic su Crea progetto per iniziare a creare un nuovo progetto Cloud.

    Vai alla pagina del selettore dei progetti

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

    Google Cloud offre una prova senza costi. La prova scade al termine dei 90 giorni o dopo che l'account ha accumulato addebiti per un valore di 300 $, a seconda dell'evento che si verifica per primo. Annulla quando vuoi. Per ulteriori informazioni, consulta Crediti dell'account di fatturazione e Fatturazione.

Cloud SDK

gcloud projects create "PROJECT"

Scopri di più su Google Cloud SDK , installazione di Cloud SDK e i seguenti comandi:

Passaggio 2

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

Tieni presente che alcune integrazioni richiedono l'abilitazione di più API/SDK. Se non sai con certezza quali API o SDK abilitare, prova a utilizzare Capabilities Explorer o consulta la documentazione relativa all'API o all'SDK che vuoi utilizzare.

Per abilitare una o più API o SDK:

Console

  1. Per visualizzare le API e gli SDK di Google Maps Platform che puoi abilitare, vai alla pagina della libreria delle API di Google Maps nella console Cloud:

    Vai alla pagina della libreria API di Google Maps

  2. Fai clic sull'API o sull'SDK che vuoi abilitare.
    • Se il pulsante indica ABILITA, fai clic per abilitare l'API o l'SDK.
    • Se il pulsante indica GESTISCI, l'API o l'SDK è già abilitato e non devi fare altro.
    • Se fai clic su uno dei pulsanti, viene visualizzata la dashboard per l'API o l'SDK. (Fai clic sul pulsante DISABILITA per rimuovere l'API o l'SDK da questo progetto.)

Cloud SDK

Il seguente comando abilita tutte le API di Maps, Routes e Places:

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

Scopri di più su Google Cloud SDK , installazione di Cloud SDK e i seguenti comandi:

Utilizza questo comando per abilitare le API Environment:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

Passaggio 3

Questo passaggio illustra solo la procedura di creazione della chiave API. Se utilizzi la chiave API in produzione, ti consigliamo vivamente di limitarla. Puoi trovare ulteriori informazioni nella pagina Utilizzo delle chiavi API specifica per il prodotto.

La chiave API è un identificatore univoco che autentica le richieste associate al progetto a fini di utilizzo e 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 appena creata.
  3. 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 services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Scopri di più su Google Cloud SDK , installazione di Cloud SDK e i seguenti comandi:

Per attivare l'SDK, consulta la pagina Maps 3D SDK for Android nella console Google Cloud. Per saperne di più su come completare questi passaggi, consulta Inizia a utilizzare Google Maps Platform.

Configura un progetto Android Studio

Questa sezione spiega come creare e configurare un progetto Android Studio da utilizzare con Maps 3D SDK for Android.

Parte 1: configura il progetto e la configurazione di Gradle

  1. Crea un nuovo progetto Android Studio utilizzando il modello Empty Views Activity. Nella configurazione del progetto, imposta SDK minimo su API 24 o versioni successive.

  2. Se utilizzi Git per il controllo del codice sorgente, modifica il file di progetto .gitignore per impedire che il file dei secret venga sottoposto a commit nel controllo della versione:

    • Nella directory root del progetto, apri il file .gitignore.
    • Aggiungi la seguente riga:
    secrets.properties

  3. Aggiorna il file build.gradle.kts a livello di progetto:

    • Nella directory root del progetto, apri il file build.gradle.kts.
    • Nel blocco plugins, aggiungi il plug-in Secrets Gradle:
    plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.android) apply false
  alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
}

  4. Aggiorna il file gradle/libs.versions.toml:

    • Apri il file gradle/libs.versions.toml, che in genere si trova nella directory gradle all'interno della directory root del progetto.
    • Nella sezione [versions], aggiungi le versioni per l'SDK e il plug-in Secrets Gradle:
    # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
maps3dSdk = "16.0.1"
# See https://github.com/google/secrets-gradle-plugin/releases for available releases
secretsGradlePlugin = "2.0.1"
    • Nella sezione [library], aggiungi la libreria dell'SDK:
    play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
    • Nella sezione [plugins], aggiungi il plug-in Secrets Gradle:
    secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }

  5. Aggiorna il file app/build.gradle.kts a livello di modulo:

    • Apri il file build.gradle.kts a livello di modulo, che di solito si trova nella directory app.
    • All'inizio del file, aggiungi il plug-in Secrets Gradle al blocco plugins:
    plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.secrets.gradle.plugin) // Add this line
}
    • Nel blocco dependencies, aggiungi la dipendenza di Google Play Services per Maps 3D SDK for Android:
    dependencies {
    // ... other dependencies
    implementation(libs.play.services.maps3d) // Add this line
}
    • Alla fine del file, al di fuori dei blocchi android e dependencies, aggiungi la configurazione dei secret:
    secrets {
    // Optionally specify a different filename 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"
}

Parte 2: aggiungi la chiave API al progetto

  1. Crea un file secrets.properties:

    • Nella directory root del modulo dell'app (di solito la directory app), crea un nuovo file denominato secrets.properties.
    • Aggiungi la chiave API al file:
    MAPS3D_API_KEY=YOUR_API_KEY_HERE

  2. Crea un file local.defaults.properties: - Nella directory root del modulo dell'app, crea un nuovo file denominato local.defaults.properties. - Aggiungi una chiave API predefinita o segnaposto al file. Questo file può essere inserito nel controllo della versione:

    MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER

Parte 3: aggiorna il file AndroidManifest.xml

  1. Apri il file app/src/main/AndroidManifest.xml.

  2. All'interno del tag <application>, prima del tag <activity>, aggiungi il seguente elemento <meta-data> per dichiarare la chiave API:

    <application
    ...>

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

    <activity
        ...>
    </activity>
</application>

    Durante il processo di build, il plug-in Secrets Gradle sostituirà il segnaposto ${MAPS3D_API_KEY} con la chiave del file secrets.properties.

Inizializzazione della visualizzazione programmatica (facoltativa)

Se preferisci inizializzare la visualizzazione mappa in modo programmatico anziché nei layout XML, utilizza Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

Passaggi successivi

Ora che hai un progetto Google Cloud, una chiave API e un progetto Android Studio configurato per l'utilizzo con Maps SDK 3D per Android, puoi aggiungere una mappa 3D alla tua app.