Crea una semplice app di navigazione per iOS in Swift con l'SDK di navigazione Google Maps Platform

1. Prima di iniziare

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

Ecco l'aspetto dell'app al termine.

Prerequisiti

• Conoscenza di base dello sviluppo di app per iOS in Swift.
• Una certa familiarità con i concetti di base di Google Maps SDK, ad esempio creare una mappa centrata su una posizione specifica.

Cosa imparerai a fare

• Come creare una semplice app Swift per iOS che utilizza l'SDK Navigation per raggiungere una destinazione.
• Come integrare l'SDK Navigation dal repository Cocoapods remoto.
• Come gestire le autorizzazioni di accesso alla posizione e il contratto con l'utente con i termini per l'utente finale dell'SDK Navigation.
• Come inizializzare l'SDK.
• Come impostare una destinazione e avviare le indicazioni stradali.

Che cosa ti serve

• L'ultima versione stabile di Xcode.
• Un account Google e un progetto con la fatturazione abilitata.
• Un dispositivo iOS o un dispositivo emulato in Xcode Simulator. Qualunque tu scelga, deve soddisfare i requisiti minimi per l'SDK Navigation.

2. Configurazione

Se non hai ancora un account Google Cloud Platform e un progetto con la fatturazione abilitata, configura il tuo progetto Google Cloud seguendo le istruzioni per iniziare a utilizzare Google Maps Platform.

Seleziona un 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.

Nota: l'utilizzo di Navigation SDK non è coperto dal credito mensile ricorrente di 200 $di Google Maps Platform, ma le prime 1000 destinazioni al mese non comportano alcun costo.

Attivare l'SDK Navigation nel progetto

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

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

Dovresti visualizzare un risultato di ricerca.

Fai clic su SDK Navigation per aprire la pagina Dettagli prodotto. Fai clic su Abilita per abilitare l'SDK nel tuo progetto.

Ripeti questa procedura per Google Maps SDK for iOS.

Crea una chiave API

Genera una chiave API nella pagina Credenziali di Cloud Console. Tutte le richieste a Google Maps Platform richiedono una chiave API. Nella pagina Credenziali della console. Fai clic su "+ Crea credenziali" nella parte superiore della pagina e seleziona "Chiave API" dalle opzioni.

Per l'utilizzo in produzione, la best practice prevede di impostare una limitazione dell'applicazione per la chiave API, ma questa operazione è facoltativa per questo codelab.

3. Ottieni i file di progetto di esempio

Questa sezione descrive come configurare un progetto di app Xcode vuoto di base clonando i file dal repository GitHub per questo codelab. Il repository GitHub contiene le versioni del codice del codelab prima e dopo la modifica. Il codelab inizierà con un modello di progetto vuoto e verrà creato fino allo stato finale. Se hai difficoltà, puoi utilizzare il progetto completato nel repository come riferimento.

Clona il repository o scarica il codice

Vai alla directory in cui vuoi archiviare il codelab.

Poi clona il repository o scarica il codice:

git clone https://github.com/googlemaps-samples/codelab-navigation-101-ios-swift

Se non hai installato git, fai clic su questo pulsante per ottenere il codice:

Ottieni il codice

Per iniziare il più rapidamente possibile, il repository contiene del codice iniziale nella cartella Starter per aiutarti a seguire questo codelab. È disponibile anche un progetto Solution completato nel caso in cui tu voglia andare avanti o controllare i tuoi progressi in qualsiasi momento. Per utilizzare il progetto della soluzione, devi seguire le istruzioni riportate di seguito in "Installazione tramite CocoaPods" e poi eseguire il comando "pod update" dalla cartella solution/Navigation SDK Codelab.

Dopo aver clonato il repository in locale, utilizza Xcode per aprire la cartella Starter come progetto esistente. Verifica che il progetto venga compilato ed eseguito.

Nota: il progetto per questo codelab è scritto in Swift con UIKit.

Collega un dispositivo o configura il simulatore Xcode

4. Aggiungere l'SDK Navigation alla tua app

Esistono tre modi per integrare l'SDK Navigation in un progetto Xcode:questo codelab utilizza CocoaPods. Per informazioni dettagliate su come eseguire l'integrazione utilizzando Swift Package Manager o per eseguire l'installazione manuale scaricando l'SDK, consulta Creare il progetto Xcode e installare l'SDK Navigation nella documentazione dell'SDK Navigation.

Installare utilizzando CocoaPods

Se non hai ancora lo strumento CocoaPods, installalo su macOS eseguendo il seguente comando dal terminale. Per maggiori dettagli, consulta la guida introduttiva a CocoaPods.

sudo gem install cocoapods

Crea un nuovo file denominato Podfile nella cartella del progetto, all'interno della cartella starter/Navigation SDK Codelab (in Xcode, File > New > File > Other > Empty, salva come "Podfile")

Aggiungi i seguenti contenuti a Podfile:

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'Navigation SDK Codelab' do
  pod 'GoogleNavigation', '9.1.1'
end

Risparmia Podfile.

Apri un terminale e cambia directory nella posizione in cui hai salvato il Podfile (deve essere la cartella "starter/Navigation SDK Codelab" nel repository codelab)

cd "<path-to-starter-project-folder>/Navigation SDK Codelab"

Esegui il comando pod install. Vengono installate le API specificate in Podfile, insieme a tutte le dipendenze

pod install

Chiudi Xcode e poi apri il file .xcworkspace del progetto per avviare Xcode. Da questo momento in poi, devi utilizzare il file .xcworkspace per aprire il progetto.

Controlla che sia stata aggiunta una directory Pods alla struttura del progetto e che contenga i pod "GoogleMaps" e "GoogleNavigation".

Aggiungere la chiave API

Aggiungi la chiave API al tuo AppDelegate.swift nel seguente modo:

1. Aggiungi le seguenti istruzioni di importazione:

import GoogleMaps
import GoogleNavigation

2. Aggiungi quanto segue al metodo application(_:didFinishLaunchingWithOptions:):

GMSServices.provideAPIKey("YOUR_API_KEY")

Sostituisci "YOUR_API_KEY" con la chiave API che hai creato nel passaggio precedente.

Crea il progetto e correggi eventuali errori.

5. Configurare le autorizzazioni app

Navigation SDK si basa sui segnali GPS per fornire la posizione agganciata alla strada e indicazioni passo passo, pertanto la tua app dovrà chiedere all'utente di concedere l'accesso ai dati sulla posizione esatta.

Per farlo, devi aggiungere alcune proprietà al file Info.plist delle tue app in Xcode, aggiungere del codice alla tua app per richiedere l'autorizzazione all'utente in fase di runtime e gestire eventuali errori, ad esempio l'autorizzazione non concessa o la posizione non disponibile.

Apri Info.plist in Xcode. L'annuncio dovrebbe avere un aspetto simile a questo.

Richiedere l'autorizzazione di accesso alla posizione esatta

Puoi aggiungere nuovi valori passando il puntatore del mouse sopra la riga "Elenco proprietà informazioni" finché non viene visualizzata l'icona "+". Fai clic su "+" per visualizzare una finestra di dialogo con i nomi delle proprietà suggeriti, ma tieni presente che puoi anche aggiungere proprietà manualmente.

Aggiungi le seguenti proprietà e valori a Info.plist:

Proprietà	Valore
Privacy - Descrizione dell'utilizzo della posizione Sempre e Quando in uso	"Questa app richiede la posizione del dispositivo per fornire la navigazione passo passo"
Privacy - Descrizione dell'utilizzo della posizione durante l'uso	"Questa app richiede la posizione del dispositivo per fornire la navigazione passo passo"
allowsBackgroundLocationUpdates	SÌ

Richiedere l'autorizzazione di accesso alla posizione in background

Aggiungi le seguenti proprietà e valori a Info.plist:

UIBackgroundModes > Aggiungi riga > Item 0: App registers for location updates (seleziona questo valore dall'elenco a discesa dei suggerimenti)

Al termine, il file Info.plist dovrebbe avere un aspetto simile a questo.

Richiedere l'accesso alla posizione in fase di runtime

Aggiungi le seguenti istruzioni di importazione a ViewController.swift:

import GoogleNavigation

Aggiungi la seguente dichiarazione alla classe ViewController:

var locationManager: CLLocationManager!

Aggiungi un override del metodo per loadView() e chiama locationManager.requestAlwaysAuthorization():

override func loadView() {
        locationManager = CLLocationManager()
        locationManager.requestAlwaysAuthorization()

L'app ora richiederà la posizione all'utente e la renderà disponibile se concede l'autorizzazione .

Richiedere l'autorizzazione per mostrare le notifiche

Aggiungi il seguente codice a loadView() per richiedere all'utente l'autorizzazione a mostrare le notifiche, che saranno necessarie per mostrare le istruzioni di manovra di navigazione.

UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
        granted, error in
        // Handle denied authorization to display notifications.
          if !granted || error != nil {
              print("User rejected request to display notifications.")
          }
        }

Crea ed esegui l'app e verifica che ti venga chiesto di condividere la posizione e attivare le notifiche.

6. Aggiungere un'interfaccia utente di navigazione

In questo passaggio aggiungerai una mappa e la configurerai per mostrare una posizione. A questo punto, mostrerai all'utente una finestra di dialogo con i termini di servizio dell'SDK Navigation.

Aggiungere una visualizzazione della mappa all'app

Aggiungi questa riga per dichiarare una variabile GMSMapView nel tuo ViewController.

var mapView: GMSMapView!

Aggiungi il seguente codice a loadView() in Viewcontroller.swift per inizializzare la mappa.

let camera = GMSCameraPosition.camera(withLatitude: 51.483174, longitude: -0.177369, zoom: 14)
let options = GMSMapViewOptions()
options.camera = camera
options.frame = .zero
        
mapView = GMSMapView(options: options)
view = mapView

Crea ed esegui l'app. Dovresti visualizzare una mappa centrata sul sud-ovest di Londra.

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 tieni premuto sulla mappa nell'app mobile Google Maps e copia o prendi nota delle coordinate.

Mostra la finestra di dialogo dei termini di servizio del prodotto SDK Navigation

Aggiungi il seguente codice a ViewController.swift nello stesso metodo loadView() del codice precedente. Verranno visualizzati i termini di utilizzo per l'utente finale dell'SDK Navigation. Se non viene accettata, la navigazione non verrà attivata.

// Show the terms and conditions.
let companyName = "Navigation SDK Codelab"
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(withCompanyName: companyName) { termsAccepted in
  if termsAccepted {
    // Enable navigation if the user accepts the terms.
    self.mapView.isNavigationEnabled = true
    // Request authorization for alert notifications which deliver guidance instructions
    // in the background.
  } else {
    // Handle the case when the user rejects the terms and conditions.
  }
}

Crea ed esegui l'app per visualizzare la finestra di dialogo.

7. Aggiungere listener per gli eventi di navigazione chiave

Questo passaggio ti mostrerà come configurare i listener per gli eventi chiave, ad esempio l'arrivo a destinazione o il cambio di itinerario dell'autista.

Per ascoltare questi eventi, il controller della visualizzazione deve adottare il protocollo GMSNavigatorListener.

Aggiungi questo protocollo alla definizione della classe in ViewController.swift.

class ViewController: UIViewController,
                      GMSNavigatorListener {

Ora aggiungi una riga di codice per configurare il listener in loadView():

// Add a listener for GMSNavigator.
mapView.navigator?.add(self)

Infine, aggiungi due metodi alla classe per gestire gli eventi generati.

// Listener to handle arrival events.
func navigator(_ navigator: GMSNavigator, didArriveAt waypoint: GMSNavigationWaypoint) {
  print("You have arrived at: \(waypoint.title)")
}

// Listener for route change events.
func navigatorDidChangeRoute(_ navigator: GMSNavigator) {
  print("The route has changed.")
}

8. Impostare una destinazione e avviare la guida

Questa sezione ti insegnerà a impostare una destinazione e ad avviare la guida alla navigazione.

Crea una nuova funzione per la logica di navigazione.

Innanzitutto, aggiungi una nuova funzione chiamata startNav() al tuo ViewController. Questo conterrà la logica per impostare una destinazione e avviare la navigazione.

Nota: l'attributo @objc è necessario per rendere il metodo disponibile al codice Objective-C ed evitare di attivare un errore di build dopo aver aggiunto il codice che chiama l'SDK Navigation.

// Create a route and start guidance.
@objc func startNav() {
}

Crea un Waypoint per la destinazione.

Successivamente, crea un array di destinazioni con un singolo waypoint.

Suggerimento: utilizza un ID luogo per il waypoint. L'utilizzo di un ID luogo consente a Navigation SDK di decidere la posizione migliore per raggiungere la destinazione. Per trovare gli ID luogo, puoi utilizzare l'app Trova ID luogo o l'API Places di Google Maps Platform per cercare luoghi.

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
  destinations.append(
    GMSNavigationWaypoint.init(
      placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
      title: "Trafalgar Square")!)
}

Chiama setDestinations()e gestisci la risposta.

Quindi, chiama setDestinations e gestisci GMSRouteStatus restituito.

Se GMSRouteStatus è "OK", avvia la guida impostando isGuidanceActive=true sull'oggetto navigator di mapView. In caso contrario, stampa un estratto conto per dimostrare che si è verificato un errore.

Se il valore GMSRouteStatus restituito è "OK", inizia a simulare la guida lungo il percorso chiamando mapView.locationSimulator.simulateLocationsAlongExistingRoute().

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
    destinations.append(
      GMSNavigationWaypoint.init(
        placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
          title: "Trafalgar Square")!)
      
  mapView.navigator?.setDestinations(
    destinations
  ) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      return
    }
    //If routeStatus is OK, start guidance.
    self.mapView.navigator?.isGuidanceActive = true
    //start simulating driving along the route. self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
    self.mapView.cameraMode = .following
  }
}

Gestire gli stati di errore comuni

È utile gestire gli errori GMSRouteStatus in modo più esplicito, soprattutto durante il debug dei problemi iniziali della nuova app. Ad esempio, potresti riscontrare più frequentemente errori relativi all'autorizzazione di accesso alla posizione, alla chiave API o "Nessun percorso trovato" all'inizio a causa della configurazione di debug, pertanto può essere utile gestire questi stati di errore.

Aggiungi il codice che gestisce questi casi specifici e stampa un'istruzione nella console.

mapView.navigator?.setDestinations(
  destinations
) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      switch routeStatus {
       case .locationUnavailable:
        print("Location unavailable.") //check permissions
      case .noRouteFound:
        print("No route found.") //check start location and destination
      case .waypointError:
        print("Waypoint error") //check Place ID
      default:
        print("Not sure what happened")
      }
    return
  }

Aggiungere un pulsante per avviare le indicazioni stradali

Infine, aggiungi un pulsante all'interfaccia utente e collegalo al metodo startNav. Crea un metodo denominato makeButton() con il seguente codice. Chiama la funzione makeButton() da loadView().

// Add a button to the view.
func makeButton() {
  // A button to start navigation.
  let navButton = UIButton(frame: CGRect(x: 5, y: 150, width: 200, height: 35))
  navButton.backgroundColor = .blue
  navButton.alpha = 0.5
  navButton.setTitle("Start navigation", for: .normal)
  navButton.addTarget(self, action: #selector(startNav), for: .touchUpInside)
  self.mapView.addSubview(navButton)
}

Crea ed esegui la tua app.

Nota: l'esecuzione del codice in

startNav()

chiamerà il

setDestinations()

metodo che comporta un addebito dopo le prime 1000 destinazioni utilizzate. Per ulteriori informazioni, vedi Utilizzo e fatturazione.

Suggerimento: imposta una nuova posizione di partenza predefinita per il simulatore Xcode selezionando Funzionalità > Posizione > Posizione personalizzata dal menu del simulatore oppure aggiungi codice per simulare la posizione con l'SDK Navigation chiamando il metodo mapview.locationSimulator?.simulateLocationAt() nella funzione startNav().

9. Complimenti!

Ben fatto, hai raggiunto la tua destinazione.

Hai creato un'app semplice che fornisce indicazioni di navigazione passo passo verso una destinazione utilizzando l'SDK Navigation di Google Maps Platform.

Hai configurato le autorizzazioni dell'app e la finestra di dialogo dei termini per l'utente finale dell'SDK Navigation e hai specificato una destinazione utilizzando un ID luogo. Hai gestito vari stati di successo ed errore nella tua app.

10. Vuoi di più?

Se vuoi sviluppare ulteriormente la tua app, dai un'occhiata agli argomenti riportati di seguito per trovare ispirazione.

• Ascolta altri eventi di navigazione. Aggiungi codice per visualizzare un messaggio se il tempo o la distanza rimanenti superano una soglia.
• Personalizzare l'interfaccia di navigazione.
• Se vuoi una sfida più impegnativa, prova ad aggiungere un selettore di luoghi dell'API Places per consentire all'utente di impostare la destinazione. Suggerimento: le app demo dell'SDK Navigation hanno un'implementazione di esempio. Esegui pod try GoogleNavigation nella cartella del progetto per visualizzare il codice.