Configura il progetto

Segui questa guida per integrare l'SDK di navigazione per iOS in un'app per iOS.

Prerequisiti

• Prima di iniziare a utilizzare l'SDK di navigazione per iOS, devi disporre di un progetto con un account di fatturazione e l'SDK Maps per iOS abilitati. Ti consigliamo di creare più proprietari del progetto e amministratori di fatturazione, in modo da avere sempre a disposizione del team qualcuno con questi ruoli. Per ulteriori informazioni, consulta Configurare il progetto Google Cloud.
• Per creare un progetto utilizzando l'SDK di navigazione per iOS, è necessaria la versione 15.0 o successiva di Xcode.
• La versione iOS target minima per l'SDK di navigazione è 14.0.

Importante: l'SDK Places for iOS, a partire dalla versione 5.0, non è incluso nell'SDK Navigation per iOS e deve essere installato separatamente. Google consiglia di scaricare e installare le stesse versioni dell'SDK Places e dell'SDK di navigazione. Vedi Installare l'SDK Places per iOS.

Installa l'SDK

Gestione pacchetti Swift

L'SDK di navigazione può essere installato tramite Gestione pacchetti Swift. Per aggiungere l'SDK, assicurati di aver rimosso tutte le dipendenze dell'SDK di navigazione esistenti.

Importante: queste istruzioni presuppongono l'utilizzo di Xcode 15 o versioni successive, ma dovrebbero essere simili per le versioni precedenti di Xcode.

Per aggiungere l'SDK a un progetto nuovo o esistente:

1. Apri Xcode project o workspace, quindi vai a File > Aggiungi dipendenze pacchetto.
2. Inserisci https://github.com/googlemaps/ios-navigation-sdk come URL, premi Invio per estrarre il pacchetto e fai clic su "Aggiungi pacchetto".
3. Per installare un elemento version specifico, imposta il campo Regola di dipendenza su una delle opzioni basate sulle versioni. Per i nuovi progetti, ti consigliamo di specificare la versione più recente e di utilizzare l'opzione "Versione esatta". Al termine, fai clic su "Aggiungi pacchetto".
4. Nella finestra Choose Package Products (Scegli prodotti in pacchetto), verifica che GoogleNavigation verrà aggiunto alla destinazione main designata. Al termine, fai clic su "Aggiungi pacchetto".
5. Per verificare l'installazione, vai al riquadro General della destinazione. In Framework, librerie e contenuti incorporati dovresti vedere i pacchetti installati. Puoi anche visualizzare la sezione "Dipendenze pacchetto" di "Navigatore progetti" per verificare il pacchetto e la sua versione.

Per aggiornare package per un progetto esistente:

1. Da Xcode, vai a "File > Pacchetti > Aggiorna alle versioni più recenti dei pacchetti".
2. Per verificare l'installazione, vai alla sezione Dipendenze pacchetto di Navigatore progetto per verificare il pacchetto e la relativa versione.

Importante: a volte gli artefatti non possono essere risolti o possono verificarsi errori, in questo caso seleziona "File > Pacchetti > Reimposta cache pacchetto".

Per rimuovere le dipendenze dell'SDK di navigazione esistenti aggiunte utilizzando CocoaPods, segui questi passaggi:

1. Chiudi l'area di lavoro Xcode. Apri terminale ed esegui questo comando:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. Rimuovi Podfile, Podfile.resolved e Xcode workspace se non li utilizzi per scopi diversi da CocoaPods.

Per rimuovere manualmente l'SDK di navigazione esistente per iOS:

1. Nelle impostazioni di configurazione del progetto Xcode, individua Frameworks, librerie e contenuti incorporati. Utilizza il segno meno(-) per rimuovere il seguente framework:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
2. Dalla directory di primo livello del progetto Xcode, rimuovi il bundle GoogleMaps.

CocoaPods

L'SDK Navigation per iOS è disponibile come pod CocoaPods. CocoaPods è un gestore delle dipendenze open source per i progetti Cocoa Swift e Objective-C.

Se non hai ancora lo strumento CocoaPods, installalo su macOS eseguendo questo comando dal terminale. Per maggiori dettagli, consulta la Guida introduttiva di CocoaPods.

sudo gem install cocoapods

Crea un Podfile per l'SDK Navigation per iOS e utilizzalo per installare l'API e le sue dipendenze:

1. Se non hai ancora un progetto Xcode, creane uno e salvalo nella tua macchina locale. Se non hai mai utilizzato lo sviluppo su iOS:
   1. Crea un nuovo progetto.
   2. Seleziona il modello iOS > App.
   3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
2. Crea un file denominato Podfile nella directory del progetto. Questo file definisce le dipendenze del progetto.
3. Modifica Podfile e aggiungi le dipendenze insieme alle relative versions. Ecco un esempio che include la dipendenza necessaria per l'SDK di navigazione per iOS: # Riferimento installazione di Cocoapods #

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '5.3.1'
   end
           

   Assicurati di eseguire regolarmente pod outdated per rilevare versioni più recenti. Se necessario, esegui l'upgrade alla versione più recente.
4. Salva Podfile.

5. Apri un terminale e vai alla directory contenente Podfile:

   cd <path-to-project>

6. Esegui il comando pod install. Questa operazione installa le API specificate in Podfile, insieme a eventuali dipendenze.

   pod install

7. Chiudi Xcode, quindi apri (doppio clic) il file .xcworkspace del tuo progetto per avviare Xcode. Da questo momento in poi, dovrai utilizzare il file .xcworkspace per aprire il progetto.

Per aggiornare l'API per un progetto esistente:

1. Apri un terminale e vai alla directory del progetto contenente Podfile.
2. Esegui il comando pod update. Tutte le API specificate in Podfile vengono aggiornate all'ultima versione.

Installazione manuale

Questa guida mostra come aggiungere manualmente XCFrameworks, contenenti l'SDK Navigation per iOS, e l'SDK Maps per iOS al progetto, nonché come configurare le impostazioni di build in Xcode. Un XCFramework è un pacchetto binario che puoi utilizzare su più piattaforme, incluse le macchine che utilizzano il chipset M1

Per installare XCFrameworks for Navigation SDK per iOS e Maps SDK for iOS:

1. Scarica i seguenti file binari dell'SDK e file di risorse:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. Avvia Xcode e apri un progetto esistente o creane uno nuovo. Se è la prima volta che utilizzi iOS, crea un nuovo progetto e seleziona il modello di app per iOS.
3. Rimuovi dal progetto tutti i riferimenti a Maps, Navigation e Places esistenti.
   Importante: l'SDK Places per iOS non è incluso nell'SDK Navigation per iOS e deve essere installato separatamente. Questo vale a partire dalla versione 5.0 dell'SDK Places per iOS. Google consiglia di scaricare e installare le stesse versioni dell'SDK Places per iOS e dell'SDK Navigation per iOS. Consulta la pagina relativa all'installazione dell'SDK Places for iOS.
4. Trascina i seguenti XCFrameworks nel progetto in Frameworks, librerie e contenuti incorporati per installare sia Maps che gli SDK di navigazione (se richiesto, seleziona Copia elementi se necessario):
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
5. Trascina GoogleMaps.bundle da GoogleMapsResources che hai scaricato nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che sia selezionata l'opzione Copia elementi se necessario.
6. Trascina GoogleNavigation.bundle da GoogleNavigationResources che hai scaricato nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che l'opzione Copia elementi nella cartella del gruppo di destinazione sia selezionata.
7. Seleziona il progetto dal Navigatore progetti e scegli il target dell'applicazione.
8. Apri la scheda Fasi di creazione e, in Collega file binario alle librerie, aggiungi i seguenti framework e librerie:
   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • UserNotifications.framework
   • WebKit.framework
9. Nel target dell'applicazione, seleziona la scheda Funzionalità, attiva Modalità in background e attiva le seguenti modalità:
   • Audio, AirPlay e Picture in picture
   • Aggiornamenti sulla posizione
10. Scegli il tuo progetto anziché una destinazione specifica e apri la scheda Impostazioni build. Nella sezione Altri flag Linker, aggiungi ‑ObjC sia per debug che release. Se queste impostazioni non sono visibili, nella barra Impostazioni build cambia il filtro da Di base a Tutti.
11. Apri Info.plist e aggiungi le seguenti coppie chiave-valore:
    • Chiave: NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)
      Valore: "Questa app richiede l'autorizzazione per utilizzare la tua posizione per la navigazione passo passo".
    • Chiave: NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description)
      Valore: "Questa app richiede l'autorizzazione per usare la tua posizione per la navigazione passo passo".

Aggiungi il file manifest sulla privacy di Apple

Importante: queste istruzioni relative al file manifest sulla privacy di Apple si applicano solo alla versione più recente dell'SDK.

1. Scarica il bundle Manifest per la privacy dell'SDK di navigazione per iOS: GoogleNavigationPrivacy.
2. Estrai il file per accedere a GoogleNavigationPrivacy.bundle.
3. Aggiungi GoogleNavigationPrivacy.bundle nel navigatore dei progetti Xcode utilizzando uno di questi metodi. Assicurati che la casella "Aggiungi ai target" sia selezionata per il target dell'app. Una volta aggiunto, il file PrivacyInfo viene visualizzato nella barra di navigazione dei progetti e puoi esaminare i valori.

4. Verifica che il manifest per la privacy sia stato aggiunto creando un archivio della tua app e generando un report sulla privacy dall'archivio.

Aggiungi una chiave API al progetto

I seguenti esempi mostrano come aggiungere la chiave API al tuo progetto in Xcode:

Swift

Aggiungi la tua chiave API a AppDelegate.swift come segue:

1. Aggiungi le seguenti istruzioni di importazione:

   import GoogleMaps
   import GoogleNavigation

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

   GMSServices.provideAPIKey("YOUR_API_KEY")

Objective-C

Aggiungi la tua chiave API a AppDelegate.m come segue:

1. Aggiungi le seguenti istruzioni di importazione:

   @import GoogleMaps;
   @import GoogleNavigation;

2. Aggiungi quanto segue al tuo metodo application:didFinishLaunchingWithOptions::

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

Aggiungi una mappa

Questo codice mostra come aggiungere una mappa semplice a un elemento ViewController esistente, incluse alcune impostazioni iniziali per la navigazione.

Prima di poter attivare la navigazione, l'utente deve accettare i termini e le condizioni. Per chiedere all'utente, chiama il numero GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(), quindi controlla se i termini sono stati accettati. Se l'utente rifiuta i termini, mapView.isNavigationEnabled = true non ha alcun effetto e mapView.navigator è nullo.

Swift

import UIKit
import GoogleNavigation

class ViewController: UIViewController {

  var mapView: GMSMapView!
  var locationManager: CLLocationManager!

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

    let camera = GMSCameraPosition.camera(withLatitude: 47.67, longitude: -122.20, zoom: 14)
    mapView = GMSMapView.map(withFrame: CGRect.zero, camera: camera)

    // Show the terms and conditions.
    let companyName = "Ride Sharing Co."
    GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
      withCompanyName: companyName) { termsAccepted in
      if termsAccepted {
        // Enable navigation if the user accepts the terms.
        self.mapView.isNavigationEnabled = true
      } else {
        // Handle the case when the user rejects the terms and conditions.
      }
    }

    view = mapView
  }

  // TODO: Add navigation code.

}

Objective-C

#import "ViewController.h"
@import GoogleNavigation;

@interface ViewController ()
@end

@implementation ViewController
GMSMapView *_mapView;
CLLocationManager *_locationManager;

-   (void)loadView {

  _locationManager = [[CLLocationManager alloc] init];
  [_locationManager requestAlwaysAuthorization];

  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.67
                                                          longitude:-122.20
                                                               zoom:14];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];

  // Show the terms and conditions.
  NSString *companyName = @"Ride Sharing Co.";
  [GMSNavigationServices
    showTermsAndConditionsDialogIfNeededWithCompanyName:companyName
    callback:^(BOOL termsAccepted) {
     if (termsAccepted) {
       // Enable navigation if the user accepts the terms.
       _mapView.navigationEnabled = YES;
     } else {
       // Handle the case when the user rejects the terms and conditions.
     }
   }];

  self.view = _mapView;
}

// TODO: Add navigation code.

@end

Esegui l'applicazione. Dovresti visualizzare una mappa centrata su Kirkland, Washington. Se la mappa non è visibile, verifica di aver fornito la chiave API corretta.

Se sei un cliente di Servizi di mobilità

Se sei un cliente di Mobility Services, scopri di più sulla fatturazione nella documentazione di Mobility. Per ulteriori informazioni sulla registrazione delle transazioni, consulta Configurare la fatturazione. Per scoprire come aggiungere ID transazione all'implementazione dell'SDK di navigazione, consulta Associare l'utilizzo del servizio alle transazioni per la mobilità.