Crea una semplice app di navigazione per Android con l'SDK di navigazione Google Maps Platform

Crea una semplice app di navigazione per Android con l'SDK di navigazione Google Maps Platform

Informazioni su questo codelab

Ultimo aggiornamento: ott 10, 2024

Scritto da: Ed Boiling

1. Prima di iniziare

Questo codelab ti insegna a creare una semplice app per Android che utilizza l'SDK di navigazione Google Maps Platform per raggiungere una destinazione preconfigurata.

Questo sarà l'aspetto della tua app al termine dell'operazione.

Prerequisiti

• Conoscenza di base dello sviluppo di app per Android in Kotlin
• Una certa familiarità con i concetti di base di Google Maps SDK, ad esempio mappe, luoghi e coordinate.

Cosa imparerai a fare

• Come creare una semplice app per Android che utilizzi l'SDK di navigazione per raggiungere una destinazione.
• Come integrare l'SDK Navigation dal repository Maven di Google remoto
• Come gestire le autorizzazioni di accesso alla posizione e il contratto con l'utente con i Termini per gli utenti finali dell'SDK Navigation
• Inizializzare l'SDK
• Come impostare una destinazione e avviare le indicazioni stradali.

Che cosa ti serve

• L'ultima versione stabile di Android Studio installata. Questo codelab è stato creato utilizzando Android Studio Jellyfish. Se utilizzi una versione diversa, l'aspetto e il layout dell'interfaccia e dei componenti potrebbero variare.
• Un Account Google e un progetto con la fatturazione abilitata.
• Un dispositivo Android in modalità sviluppatore con il debug USB attivato oppure un emulatore Android. Qualunque sia la tua scelta, deve soddisfare i requisiti minimi per l'SDK di navigazione.

Nota: l'utilizzo dell'SDK di navigazione non è coperto dal credito mensile ricorrente di $200 per Google Maps Platform. Tuttavia, le prime 1000 destinazioni al mese non comportano costi. Per ulteriori informazioni, consulta Utilizzo e fatturazione.

2. Configurazione

Se non hai ancora un account Google Cloud e un progetto con la fatturazione abilitata, configura il tuo progetto Google Cloud seguendo le istruzioni per iniziare a utilizzare Google Maps Platform https://developers.google.com/maps/gmp-get-started

Seleziona il tuo progetto Google Cloud nella console

Nella console Cloud, fai clic sul menu a discesa del progetto e seleziona il progetto che vuoi utilizzare per questo codelab.

Attivare l'SDK di navigazione nel progetto

Abilita le API e gli SDK di Google Maps Platform richiesti per questo codelab nel Google Cloud Marketplace.

Vai ad API e servizi > Libreria nella console Google Cloud e cerca "Navigation SDK".

Dovresti vedere un risultato di ricerca.

Fai clic sul risultato SDK di navigazione per aprire la pagina dei dettagli del prodotto. Fai clic sul pulsante Abilita per attivare l'SDK nel progetto.

Ripeti questa procedura per Google Maps SDK for Android.

Nota: l'SDK di navigazione include una versione dell'SDK Google Maps per Android, quindi non è necessario configurarla separatamente. L'aggiunta dell'SDK Google Maps per Android come dipendenza separata causerà errori di generazione.

Crea una chiave API

Genera una chiave API nella pagina Credenziali della console Cloud. Puoi seguire i passaggi descritti nel passaggio 3 della sezione di inizio rapido in Introduzione a Google Maps Platform. Tutte le richieste a Google Maps Platform richiedono una chiave API.

3. recupera i file di progetto di esempio

Questa sezione descrive come configurare un progetto Android Studio vuoto di base clonando i file dal repository GitHub per questo codelab. Il repository GitHub contiene le versioni precedenti e successive del codice del codelab. Il codelab inizierà con un modello di progetto vuoto e verrà completato. Se non riesci a procedere, puoi utilizzare il progetto completato nel repository come riferimento.

Clona questo repository GitHub per ottenere il codice di questo codelab.

git clone https://github.com/googlemaps-samples/codelab-navigation-101-android-kotlin.git

Se non hai installato Git, fai clic su questo pulsante per ricevere il codice:

Ottieni il codice

Per aiutarti a iniziare il più rapidamente possibile, il repository contiene un codice di avvio nella cartella Starter che ti aiuterà a seguire questo codelab. Il progetto iniziale fornisce una UI di base dell'app e una configurazione di compilazione, ma non include SDK di navigazione. È disponibile anche un progetto Solution completato nel caso tu voglia proseguire o controllare i tuoi progressi in qualsiasi momento.

Apri il repository clonato in Android Studio

Dopo aver clonato il repository in locale, usa Android Studio per aprire la cartella Starter come progetto esistente.

1. Nella finestra di dialogo Benvenuto in Android Studio, fai clic sul pulsante Apri.
2. Vai alla cartella in cui hai salvato il repository clonato e seleziona la cartella Starter all'interno del livello "codelab-navigation-101-android-kotlin" di primo livello .
3. Verifica che il progetto venga creato ed eseguito.

Nota: il progetto per questo codelab è scritto in Kotlin.

Aggiungere un dispositivo virtuale o connettere un dispositivo hardware

Per collegare un dispositivo Android al computer, segui le istruzioni di Android Studio su come eseguire app su un dispositivo hardware. In alternativa, puoi configurare un dispositivo virtuale utilizzando Gestione dispositivi virtuali (AVD) Android. Quando scegli un emulatore, assicurati di scegliere un'immagine che includa le API di Google.

In Android Studio, fai clic sull'opzione di menu Esegui o sull'icona del pulsante di riproduzione. Scegli un dispositivo come richiesto.

4. Aggiungi l'SDK di navigazione all'app

Aggiungi la libreria SDK di navigazione e la chiave API al progetto

Nota: il progetto nel repository utilizza il DSL Kotlin per i file di compilazione, mentre le app di demo dell'SDK Nav utilizzano il DSL Groovy. La migrazione della sintassi è stata eseguita, ma potresti notare alcune piccole differenze nel modo in cui Kotlin specifica gli elementi. Per comprendere le differenze, consulta la guida alla migrazione.

Per aggiungere la libreria SDK Navigation alla tua app, devi modificare il file a livello di app build.gradle.kts per recuperare l'SDK Navigation dal repository Maven di Google e configurare un numero di versione.

Crea una variabile nella configurazione di compilazione per memorizzare il numero di versione dell'SDK Navigation.

Configura una variabile nell'elemento build.gradle.kts a livello di app che contenga il valore della versione dell'SDK di navigazione utilizzata nell'app, in modo che in futuro sia facile passare alla versione più recente.

Consulta le note sulla versione dell'SDK Navigation per conoscere il numero di versione più recente.

val navSdkVersion by extra("6.0.0")

Puoi anche modificare i valori di questa e di altre variabili utilizzando la finestra di dialogo che si trova in File > Struttura del progetto > Variabili:

Aggiungere una dipendenza alla configurazione di compilazione

Ora aggiungi la seguente dipendenza dall'API al blocco delle dipendenze a livello di app. build.gradle.kts.La versione utilizzata sarà il valore di ${navSdkVersion} che hai appena impostato in build.gradle.kts a livello di app:

dependencies {

   // Include the Google Navigation SDK.
   api("com.google.android.libraries.navigation:navigation:${navSdkVersion}")

...

Aggiungi la chiave API

Utilizza il plug-in Secrets Gradle per gestire la chiave API

Ti consigliamo di utilizzare il plug-in Secrets Gradle per gestire in sicurezza la chiave API nella tua app. Il plug-in è stato aggiunto al modello di progetto iniziale come dipendenza nel file build.gradle.kts di primo livello.

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
    //... other plugin definitions here
}

Apri il file secrets.properties nella directory di primo livello, quindi 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.

MAPS_API_KEY=YOUR_API_KEY

Per ulteriori informazioni su questo argomento, consulta Aggiungere la chiave API all'app nella documentazione dell'SDK di navigazione.

Verifica i contenuti di local.defaults.properties

Il progetto vuoto contiene anche un file local.defaults.properties nella directory di primo livello, la stessa cartella del file secrets.properties. Apri il file e osserva il seguente codice.

MAPS_API_KEY=DEFAULT_API_KEY

Questo valore esiste per fornire un valore di riserva per la proprietà MAPS_API_KEY nel caso in cui secrets.properties non venga aggiunto al progetto, in modo che le build non falliscano. Non è necessario modificare questo file. Se la definizione di secrets.properties di MAPS_API_KEY non viene trovata, il valore predefinito interromperà l'esecuzione dell'app in fase di runtime, generando un errore della chiave API.

Verifica che il file manifest Android utilizzi la chiave API specificata

Apri app/src/main/AndroidManifest.xml. Noterai che la proprietà MAPS_API_KEY viene utilizzata per impostare la chiave API per l'applicazione:

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

Apri il file build.gradle.kts a livello di app e trova la proprietà secrets.

L'impostazione propertiesFileName del plug-in deve essere impostata su secrets.properties e defaultPropertiesFileName deve essere local.defaults.properties.

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

Salva tutti i file e sincronizza il progetto con Gradle.

5. Configura le autorizzazioni app e aggiungi una UI di base

Richiedi l'autorizzazione di accesso alla posizione esatta

L'SDK di navigazione dipende dagli indicatori GPS per funzionare, pertanto la tua app dovrà chiedere all'utente di concedere l'accesso ai dati sulla posizione esatta. Aggiungi l'autorizzazione di accesso alla posizione esatta come elemento secondario dell'elemento <manifest> in AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" >
   <uses-permission 
      android:name="android.permission.ACCESS_FINE_LOCATION"
   />
</manifest>

Puoi scoprire di più sulle autorizzazioni di accesso alla posizione di Android nella sezione Richiedi autorizzazioni di accesso alla posizione della documentazione per gli sviluppatori Android.

Per eseguire la tua app su un dispositivo Android 14, richiedi l'autorizzazione di accesso alla posizione in primo piano aggiungendo il seguente tag uses-permission nella stessa posizione dell'autorizzazione di accesso alla posizione esatta:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

Aggiungere un'attività di lancio con una UI di base

Quando viene eseguita, l'app ha bisogno di codice che viene eseguito all'avvio per verificare se l'utente ha concesso l'autorizzazione ad accedere alla sua posizione e per gestire ogni possibile scenario, richiedendo l'autorizzazione se non è stata ancora concessa. Per farlo, aggiungi un'interfaccia utente di base alla tua app. Questo codelab utilizza l'UI che viene creata quando crei una nuova attività di visualizzazione vuota in Android Studio. Lo adatti per eseguire il controllo delle autorizzazioni di accesso alla posizione prima di aggiungere codice all'attività per l'UI di navigazione.

Apri il file MainActivity.kt nell'editor di codice e controlla il codice, che mostra un'interfaccia utente di base.

Richiedere autorizzazioni di accesso alla posizione in fase di runtime

L'app dovrà attivare la richiesta di accesso alla posizione esatta prima dell'inizializzazione dell'SDK Navigation.

Per assicurarti che questo controllo venga eseguito all'avvio dell'app, aggiungi del codice alla classe MainActivity, nel metodo onCreate() sostituito dell'attività.

Il seguente codice verifica se l'utente ha concesso l'autorizzazione di accesso alla posizione esatta. In caso contrario, richiede l'autorizzazione. Aggiungi questo codice all'interno del metodo onCreate().

    val permissions =
      if (VERSION.SDK_INT >= VERSION_CODES.TIRAMISU) {
        arrayOf(permission.ACCESS_FINE_LOCATION, permission.POST_NOTIFICATIONS)
      } else {
        arrayOf(permission.ACCESS_FINE_LOCATION)
      }

    if (permissions.any { !checkPermissionGranted(it) }) {

      if (permissions.any { shouldShowRequestPermissionRationale(it) }) {
        // Display a dialogue explaining the required permissions.
      }

      val permissionsLauncher =
        registerForActivityResult(
          RequestMultiplePermissions(),
          { permissionResults ->
            if (permissionResults.getOrDefault(permission.ACCESS_FINE_LOCATION, false)) {
              onLocationPermissionGranted()
            } else {
              finish()
            }
          },
        )

      permissionsLauncher.launch(permissions)
    } else {
      android.os.Handler(Looper.getMainLooper()).postDelayed({ onLocationPermissionGranted() }, SPLASH_SCREEN_DELAY_MILLIS)
    }
  }

  private fun checkPermissionGranted(permissionToCheck: String): Boolean =
    ContextCompat.checkSelfPermission(this, permissionToCheck) == PackageManager.PERMISSION_GRANTED

Aggiungi una nuova funzione alla classe MainActivity, chiamata onLocationPermissionGranted, che gestirà il risultato quando l'utente concede l'autorizzazione per condividere la sua posizione. Nei passaggi successivi aggiungeremo del codice per avviare una nuova attività di navigazione.

private fun onLocationPermissionGranted() {
   //code to initialize Navigation SDK will go here
}

Crea il progetto. Se si verificano errori di generazione, individua e correggili.

Esegui il progetto su un nuovo dispositivo virtuale. La finestra di dialogo di richiesta di autorizzazione dovrebbe essere visualizzata quando l'app viene installata e avviata.

6. Aggiungi un'interfaccia utente di navigazione

Esistono due modi per aggiungere un'interfaccia utente di navigazione: SupportNavigationFragment o NavigationView.

Per semplicità, il codelab utilizza un NavigationView.

Modificare il layout

Modifica res/layout/activity_main.xml per aggiungere un layout per un NavigationView.

1. Apri il file e passa alla Vista codice.
2. Sostituisci l'intero contenuto del file con un nuovo layout di un file NavigationView all'interno di un elemento RelativeLayout, come nell'esempio seguente. Poiché aggiungerai solo una visualizzazione di navigazione all'app, sarà sufficiente un layout semplice.
3. Assegna a NavigationView un ID "@+id/navigation_view".

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="match_parent">
 <com.google.android.libraries.navigation.NavigationView
     android:id="@+id/navigation_view"
     android:layout_width="wrap_content"
     android:layout_height="wrap_content"
      />
</RelativeLayout>

Configurare l'attività di navigazione

In Android Studio, apri il file MainActivity.kt nell'editor.

Aggiungi del codice di configurazione di base per assicurarti che l'esperienza di navigazione funzioni correttamente nella tua app. Nel file MainActivity.kt, apporta le seguenti modifiche:

1. Dichiara una variabile nella classe MainActivity che faccia riferimento a NavigationView:

private lateinit var navView: NavigationView

2. Aggiungi del codice al metodo onCreate() per ottenere un riferimento a NavigationView:

navView = findViewById(R.id.navigation_view)
navView.onCreate(savedInstanceState)

3. Aggiungi del codice al metodo onCreate() per assicurarti che lo schermo rimanga attivo durante le indicazioni di navigazione:

// Ensure the screen stays on during nav.
window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)

4. Modifica il codice che chiama ViewCompat.setOnApplyWindowInsetsListener per fare riferimento all'ID di NavigationView.

ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.navigation_view)) { v, insets ->
  val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
  v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
  insets
}

5. Aggiungi un metodo showToast() alla classe per mostrare un feedback all'utente:

private fun showToast(errorMessage: String) {
   Toast.makeText(this@MainActivity, errorMessage, Toast.LENGTH_LONG).show()
}

7. Inizializzare l'SDK di navigazione

Ora che hai completato la configurazione di base dell'attività di navigazione, puoi inizializzare l'SDK Navigation. Per farlo, aggiungi il seguente codice al file MainActivity.kt:

/** Starts the Navigation API, capturing a reference when ready. */
@SuppressLint("MissingPermission")
private fun initializeNavigationApi() {
   NavigationApi.getNavigator(
       this,
       object : NavigatorListener {
           override fun onNavigatorReady(navigator: Navigator) {
               // store a reference to the Navigator object
               mNavigator = navigator
               // code to start guidance will go here
           }

           override fun onError(@NavigationApi.ErrorCode errorCode: Int) {
               when (errorCode) {
                   NavigationApi.ErrorCode.NOT_AUTHORIZED -> {
                       // Note: If this message is displayed, you may need to check that
                       // your API_KEY is specified correctly in AndroidManifest.xml
                       // and is been enabled to access the Navigation API
                       showToast(
                           "Error loading Navigation API: Your API key is " +
                                   "invalid or not authorized to use Navigation."
                       )
                   }
                   NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED -> {
                       showToast(
                           "Error loading Navigation API: User did not " +
                                   "accept the Navigation Terms of Use."
                       )
                   }
                   else -> showToast("Error loading Navigation API: $errorCode")
               }
           }
       },
   )

}

Questo codice crea un nuovo metodo denominato initializeNavigationApi(). Questo metodo ottiene un riferimento a un oggetto Navigator chiamando NavigationApi.getNavigator() e implementa un NavigatorListener per gestire il callback.

Tieni presente che quando l'API Navigation viene inizializzata, viene invocato il metodo NavigationListener.onNavigatorReady, con un oggetto Navigator passato come parametro. Il codice riportato sopra aggiornerà la variabile mNavigator che hai dichiarato in precedenza con l'oggetto Navigator inizializzato che viene passato a questo metodo.

Nota: l'annotazione @SuppressLint impedisce ad Android Studio di avvisare circa le autorizzazioni mancanti quando vengono chiamati metodi API che richiedono l'autorizzazione di accesso alla posizione da parte dell'utente.

Infine, aggiungi una chiamata al metodo initializeNavigationApi dal metodo onLocationPermissionGranted.

private fun onLocationPermissionGranted() {
   initializeNavigationApi()
}

8. Aggiungere listener per gli eventi di navigazione principali

Quando gli utenti seguono le indicazioni, l'SDK di navigazione attiva eventi che possono avvisare l'app delle modifiche dello stato chiave lungo il percorso, ad esempio quando l'utente cambia percorso o arriva a destinazione. Nel file MainActivity.kt, aggiungi gli ascoltatori per gestire questi eventi:

1. All'interno della classe MainActivity, dichiara due variabili per fare riferimento agli oggetti listener di eventi:

private var arrivalListener: Navigator.ArrivalListener? = null
private var routeChangedListener: Navigator.RouteChangedListener? = null

2. Aggiungi un metodo registerNavigationListeners() per configurare i listener quando il navigatore viene inizializzato. Questo metodo chiama Navigator.clearDestinations() per reimpostare NavigationView quando viene attivato l'evento Arrivo:

/**
* Registers a number of example event listeners that show an on screen message when certain
* navigation events occur (e.g. the driver's route changes or the destination is reached).
*/
private fun registerNavigationListeners() {
   withNavigatorAsync {
       arrivalListener =
           Navigator.ArrivalListener { // Show an onscreen message
               showToast("User has arrived at the destination!")
               mNavigator?.clearDestinations()
           }
       mNavigator?.addArrivalListener(arrivalListener)

       routeChangedListener =
           Navigator.RouteChangedListener { // Show an onscreen message when the route changes
               showToast("onRouteChanged: the driver's route changed")
           }
       mNavigator?.addRouteChangedListener(routeChangedListener)
   }
}

3. Aggiungi una chiamata a registerNavigationListeners() dal codice di callback onNavigatorReady nel metodo initializeNavigationApi:

override fun onNavigatorReady(navigator: Navigator) {
   // store a reference to the Navigator object
   mNavigator = navigator

   //listen for events en route
   registerNavigationListeners()


}

4. Configura l'interfaccia utente. Quando vengono visualizzate le indicazioni, puoi controllare vari aspetti dell'interfaccia utente di navigazione. Una personalizzazione importante è la posizione della fotocamera. Aggiungi una chiamata al metodo setTaskRemovedBehaviour dell'oggetto navigator restituito in onNavigatorReady come segue. Se l'app viene ignorata, le indicazioni stradali e le notifiche verranno interrotte:

// Disables the guidance notifications and shuts down the app and background service
// when the user dismisses/swipes away the app from Android's recent tasks.
navigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

5. Aggiungi una chiamata a GoogleMap.followMyLocation per specificare un CameraPerspective. È possibile accedere a GoogleMap tramite il metodo NavigatorView.getMapAsync() nel seguente modo:

navView.getMapAsync {
   googleMap  ->
   googleMap.followMyLocation(GoogleMap.CameraPerspective.TILTED)
}

6. Per garantire il corretto funzionamento della navigazione durante il ciclo di vita dell'app, implementa i seguenti metodi nella classe MainActivity:

override fun onSaveInstanceState(savedInstanceState: Bundle) {
   super.onSaveInstanceState(savedInstanceState)

   navView.onSaveInstanceState(savedInstanceState)
}

override fun onTrimMemory(level: Int) {
   super.onTrimMemory(level)
   navView.onTrimMemory(level)
}

override fun onStart() {
   super.onStart()
   navView.onStart()
}

override fun onResume() {
   super.onResume()
   navView.onResume()
}

override fun onPause() {
   navView.onPause()
   super.onPause()
}

override fun onConfigurationChanged(configuration: Configuration) {
   super.onConfigurationChanged(configuration)
   navView.onConfigurationChanged(configuration)
}

override fun onStop() {
   navView.onStop()
   super.onStop()
}

override fun onDestroy() {
   navView.onDestroy()
   withNavigatorAsync {
       // Unregister event listeners to avoid memory leaks.
       if (arrivalListener != null) {
           navigator.removeArrivalListener(arrivalListener)
       }
       if (routeChangedListener != null) {
           navigator.removeRouteChangedListener(routeChangedListener)
       }

       navigator.simulator?.unsetUserLocation()
       navigator.cleanup()
   }
   super.onDestroy()
}

9. Imposta una destinazione

Ora puoi impostare una destinazione e avviare le indicazioni di navigazione. Nel file MainActivity.kt, apporta le seguenti modifiche:

1. Aggiungi un nuovo metodo navigateToPlace() che imposti la destinazione della navigazione e accetti un parametro placeId.

/**
* Requests directions from the user's current location to a specific place (provided by the
* Place ID).
*/
private fun navigateToPlace(placeId: String) {

}

2. Nel metodo navigateToPlace(), utilizza il metodo Waypoint.builder() per creare un Waypoint dall'ID luogo passato al metodo. Gestisci il valore UnsupportedPlaceIdException che questo può generare nei casi in cui l'ID luogo non si risolve con un indirizzo preciso:

val waypoint: Waypoint? =
// Set a destination by using a Place ID (the recommended method)
try {
   Waypoint.builder().setPlaceIdString(placeId).build()
} catch (e: Waypoint.UnsupportedPlaceIdException) {
   showToast("Place ID was unsupported.")
   return
}

3. Aggiungi il seguente codice al metodo navigateToPlace() per impostare una destinazione utilizzando il waypoint:

val pendingRoute = mNavigator?.setDestination(waypoint)

// Set an action to perform when a route is determined to the destination
pendingRoute?.setOnResultListener { code ->
   when (code) {
       RouteStatus.OK -> {
           // Code to start guidance will go here
       }

       RouteStatus.ROUTE_CANCELED -> showToast("Route guidance canceled.")
       RouteStatus.NO_ROUTE_FOUND,
       RouteStatus.NETWORK_ERROR ->
           // TODO: Add logic to handle when a route could not be determined
           showToast("Error starting guidance: $code")

       else -> showToast("Error starting guidance: $code")
   }
}

L'oggetto Navigator ha un metodo setDestinations() che può accettare una serie di parametri. L'opzione più semplice è fornire un Waypoint. Per impostazione predefinita, verrà utilizzata la modalità di viaggio DRIVING, adatta per auto a 4 ruote. Il metodo setDestinations() restituisce un oggetto ListenableResultFuture contenente un oggetto RouteStatus. RouteStatus indica se è stato trovato un percorso per la destinazione e, in caso contrario, ti consente di gestire vari stati di errore.

4. Apporta ulteriori modifiche di configurazione per migliorare l'esperienza utente di navigazione:

// Hide the toolbar to maximize the navigation UI
supportActionBar?.hide()

// Enable voice audio guidance (through the device speaker)
mNavigator?.setAudioGuidance(Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE)


// Simulate vehicle progress along the route (for demo/debug builds)
if (BuildConfig.DEBUG) {
   mNavigator?.simulator?.simulateLocationsAlongExistingRoute(
       SimulationOptions().speedMultiplier(5f)
   )
}

Queste modifiche includono i seguenti miglioramenti:

• Nasconde la barra delle azioni per massimizzare lo spazio per l'interfaccia utente di navigazione.
• Attivazione delle indicazioni vocali per sentire avvisi e istruzioni di navigazione.
• Configurazione del simulatore per il debug specificando un moltiplicatore di velocità.

5. Trova un ID luogo che funga da destinazione. Idealmente, non si trova troppo lontano dalla località dell'utente. Utilizza l'utilità Place ID Finder di Google Maps Platform oppure ottieni un ID luogo da una chiamata API Places.

Se stai simulando la navigazione, puoi impostare la posizione dell'utente nel codice o prelevarla dal dispositivo connesso. Il codelab presuppone che tu stia simulando una località a Londra, Regno Unito.

6. Aggiungi un oggetto companion alla classe MainActivity per memorizzare una posizione di partenza e un ID luogo. Il codelab utilizzerà un punto di partenza a Londra e il Place ID di Trafalgar Square:

companion object{
   const val TRAFALGAR_SQUARE ="ChIJH-tBOc4EdkgRJ8aJ8P1CUxo" //London, UK
   val startLocation = LatLng(51.345678, -0.1234456)
}

Suggerimento: per ottenere una latitudine e una longitudine diverse da utilizzare come posizione di partenza, fai clic con il tasto destro del mouse su una posizione qualsiasi in Google Maps in un browser o fai una pressione prolungata sulla mappa nell'app mobile Google Maps.

7. Aggiungi una chiamata al metodo navigateToPlace() dal callback onNavigatorReady all'interno del metodo initializeNavigationApi e aggiungi un ramo di logica che verrà eseguito in modalità di debug e che imposta la posizione dell'utente:

// Disables the guidance notifications and shuts down the app and background service
// when the user dismisses/swipes away the app from Android's recent tasks.
navigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

mNavigator = navigator

if (BuildConfig.DEBUG) {
   mNavigator?.simulator?.setUserLocation(MainActivity.startLocation)
}
//listen for events en route
registerNavigationListeners()

navView.getMapAsync {
   googleMap  ->
   googleMap.followMyLocation(GoogleMap.CameraPerspective.TILTED)
}

//navigate to a destination
navigateToPlace(MainActivity.TRAFALGAR_SQUARE)

10. Crea ed esegui il codice

La prima volta che esegui l'app, dovrai concedere le autorizzazioni di accesso alla posizione all'app e accettare i Termini e condizioni d'uso dell'SDK Navigation.

Nota: l'esecuzione dell'app chiama il metodo setDestinations(), che comporta un addebito dopo le prime 1000 destinazioni utilizzate. Per saperne di più, consulta la sezione Utilizzo e fatturazione.

Impostazione della località

Per impostazione predefinita, la posizione del dispositivo emulato potrebbe essere impostata sul campus Google a Mountain View in California, a meno che tu non abbia impostato una posizione nel codice o utilizzando la finestra di dialogo delle proprietà dell'emulatore.

In questo caso, potresti notare che l'app non riesce a trovare un percorso verso l'ID luogo che hai configurato (per impostazione predefinita, Sydney Opera House, Sydney, Australia). Ciò sarà indicato dal messaggio "Nessun percorso trovato", visualizzato in base al metodo showToast().

Codifica fissa della località di partenza

Per impostare una posizione diversa nel codice, aggiungi la seguente riga nel metodo navigateToPlace() in MainActivity.kt, prima della chiamata a mNavigator.startGuidance():

mNavigator?.simulator?.setUserLocation(startLocation)

Avvio dell'emulatore in una posizione predefinita a tua scelta

Per impostare una località diversa nell'emulatore del dispositivo, avvialo se non è già in esecuzione e fai clic sul menu con tre puntini con la descrizione comando "Controlli avanzati". La finestra di dialogo che si apre contiene un'opzione di menu per "Posizione".

Ad esempio, se utilizzi l'ID luogo della Sydney Opera House come destinazione, scegli una località a Sydney, in Australia. Ad esempio, cerca "Bondi beach", seleziona un suggerimento e fai clic su "Salva località" in basso a destra nella finestra di dialogo. Puoi anche fare clic su "Salva punto" per aggiungere la posizione a un elenco salvato per utilizzarla in un secondo momento.

Se imposti un ID luogo diverso come destinazione, scegli una località nelle vicinanze in modo che il percorso simulato sia realistico e non troppo lungo per facilitare il debug.

Riavvia l'app. A questo punto dovrebbe arrivare alla destinazione.

11. Complimenti!

Hai completato questo codelab. Ottimo, hai raggiunto la tua destinazione. Buona programmazione :-)

12. Vuoi di più?

Se vuoi sviluppare ulteriormente la tua app, dai un'occhiata ai seguenti argomenti per trovare l'ispirazione.

• Ascolta altri eventi di navigazione. Aggiungi il codice per mostrare un messaggio se il conducente cambia percorso o quando arriva.
• Personalizza l'interfaccia di navigazione.
• Se vuoi una sfida più grande, prova ad aggiungere un controllo di selezione della località dell'API Places per consentire all'utente di impostare la destinazione. Suggerimento: le app demo dell'SDK di navigazione su GitHub hanno un'implementazione di esempio.
• Per evitare potenziali problemi nell'eseguire chiamate asincrone agli oggetti Navigator e GoogleMap, adotta l'approccio utilizzato nelle app di dimostrazione dell'SDK Navigation su GitHub. In scenari di app più complessi, questi oggetti potrebbero non aver completato l'inizializzazione durante l'esecuzione del codice. Suggerimento: puoi aggiungere la classe InitializedNavScope alla fine del file MainActivity.kt per un'implementazione molto rapida.