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 Google Maps Platform Navigation SDK per navigare verso una destinazione preconfigurata.

Ecco come apparirà l'app al termine.

Prerequisiti

• Conoscenza di base dello sviluppo di app per iOS in Swift.
• Familiarità con i concetti di base di Google Maps SDK, ad esempio la creazione di una mappa centrata su una località specifica.

Cosa imparerai a fare

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

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 sia la tua scelta, deve soddisfare i requisiti minimi per l'SDK Navigation.

2. Configurazione

Se non hai già un account Google Cloud Platform e un progetto con la fatturazione abilitata, configura il progetto Google Cloud seguendo le istruzioni riportate nella guida introduttiva a 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 dell'SDK Navigation non è coperto dal credito mensile ricorrente di 200 $di Google Maps Platform, ma le prime 1000 destinazioni al mese non comportano costi.

Abilita 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 "SDK Navigation".

Dovresti visualizzare un risultato di ricerca.

Fai clic su SDK Navigation per aprire la pagina dei dettagli del prodotto. Fai clic su Abilita per abilitare l'SDK nel progetto.

Ripeti questa procedura per Google Maps SDK for iOS.

Crea una chiave API

Genera una chiave API nella pagina Credenziali della console Cloud. 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, è una best practice impostare una limitazione dell'applicazione per la chiave API, ma questa operazione è facoltativa per questo codelab.

3. Ottieni i file del progetto di esempio

Questa sezione descrive come configurare un progetto di base vuoto per l'app XCode clonando i file dal repository GitHub per questo codelab. Il repository GitHub contiene le versioni prima e dopo del codice del codelab. 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.

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 alcuni codici di avvio 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 creato ed eseguito.

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

Collega un dispositivo o configura XCode Simulator

4. Aggiungi 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.

Installazione tramite 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 > Nuovo > File > Altro > Vuoto, salva come "Podfile")

Aggiungi i seguenti contenuti al file Podfile:

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

platform :ios, '15.0'

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

Salva Podfile.

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

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

Esegui il comando pod install. Vengono installate le API specificate nel file Podfile, insieme a eventuali 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.

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

Aggiungi la chiave API

Aggiungi la chiave API al file AppDelegate.swift come segue:

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. Configura le autorizzazioni dell'app

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

Per farlo, aggiungerai alcune proprietà al file Info.plist delle app in Xcode, aggiungerai del codice all'app per richiedere l'autorizzazione all'utente in fase di runtime e gestirai eventuali errori, ad esempio se l'autorizzazione non viene concessa o se la posizione non è disponibile.

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

Richiedi l'autorizzazione di accesso alla posizione precisa

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

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

Proprietà	Valore
Privacy - Location Always And When In Use Usage Description	Questa app richiede la posizione del dispositivo per fornire navigazione passo passo
Privacy - Location When In Use Usage Description	Questa app richiede la posizione del dispositivo per fornire navigazione passo passo
allowsBackgroundLocationUpdates	SÌ

Richiedi l'autorizzazione di accesso alla posizione in background

Aggiungi le seguenti proprietà e i seguenti 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, Info.plist dovrebbe avere un aspetto simile a questo.

Richiedi 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()

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

Richiedi 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 per le manovre 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 di attivare le notifiche.

6. Aggiungi un'interfaccia utente di navigazione

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

Aggiungi una visualizzazione della mappa all'app

Aggiungi questa riga per dichiarare una variabile GMSMapView in 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 vedere 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 qualsiasi posizione 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 utilizzo 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 vengono accettati, 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. Aggiungi listener per gli eventi di navigazione chiave

Questo passaggio ti mostrerà come configurare i listener per gli eventi chiave, ad esempio l'arrivo a una destinazione o il ricalcolo del percorso del conducente.

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. Imposta una destinazione e avvia le indicazioni

Questa sezione ti insegnerà a impostare una destinazione e ad avviare le indicazioni di navigazione.

Crea una nuova funzione per la logica di navigazione.

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

Nota: l'attributo @objc è necessario per rendere il metodo disponibile per il codice Objective-C ed evitare di attivare un errore di compilazione 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.

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

Suggerimento: utilizza un ID luogo per il waypoint. L'utilizzo di ID luogo consente all'SDK Navigation di decidere la posizione migliore per il percorso verso la destinazione. Per trovare gli ID luogo, puoi utilizzare l'app Place ID Finder o l'API Places di Google Maps Platform per cercare i 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.

Poi, chiama setDestinations e gestisci GMSRouteStatus restituito.

Se GMSRouteStatus è "OK", avvia le indicazioni impostando isGuidanceActive=true sull'oggetto navigator di mapView. In caso contrario, stampa un'istruzione per indicare 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
  }
}

Gestisci 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 di autorizzazione di accesso alla posizione, chiave API o "nessun percorso trovato" all'inizio a causa della configurazione di debug, quindi 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
  }

Aggiungi un pulsante per avviare le indicazioni di navigazione

Infine, aggiungi un pulsante all'interfaccia utente e collegalo al metodo startNav. Crea un metodo chiamato 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 l'app.

Nota: l'esecuzione del codice in

startNav()

chiamerà il metodo

setDestinations()

che comporta un addebito dopo le prime 1000 destinazioni utilizzate. Per maggiori informazioni, consulta Utilizzo e fatturazione.

Suggerimento: imposta una nuova posizione di partenza predefinita per XCode Simulator 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!

Ottimo lavoro, hai raggiunto la tua destinazione.

Hai creato una semplice app che fornisce indicazioni passo passo verso una destinazione utilizzando Google Maps Platform Navigation SDK.

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 ai seguenti argomenti per trovare ispirazione.

• Ascolta altri eventi di navigazione. Aggiungi codice per visualizzare un messaggio se il tempo o la distanza rimanenti superano una soglia.
• Personalizza l'interfaccia di navigazione.
• Se vuoi una sfida più grande, 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.