Introduzione all'SDK Driver per iOS

Nota: la funzionalità LMFS fornisce due modelli di sicurezza da utilizzare con SDK Driver: non attendibile e attendibile. Entrambe le impostazioni I modelli definiscono i modi in cui l'app del conducente può fornire aggiornamenti dei dati del veicolo al parco risorse di ricerca. Il modello di sicurezza non attendibile fornisce un ulteriore livello di dati controllando dall'app del conducente. Nel modello non attendibile, L'app del conducente può inviare solo aggiornamenti sulla posizione del veicolo direttamente al parco risorse di ricerca. Tutti gli altri aggiornamenti dei dati del veicolo provenienti da un'app di conducente non attendibile devono essere inviate al backend del cliente, che inoltra i dati a Fleet Engine.

Il modello di sicurezza attendibile consente all'app del conducente di inviare dati del veicolo si aggiorna direttamente a Fleet Engine, senza la necessità di un intermediario completamente gestito di Google Cloud. Questi dati includono sia la creazione che l'aggiornamento di veicoli, attività e si ferma.

Il modello non attendibile è generalmente disponibile, mentre il modello di driver attendibile è in anteprima. Per ulteriori informazioni sul modello di driver attendibile, vedi Altri ruoli dell'account di servizio.

L'SDK Driver è una libreria che puoi integrare nell'app del driver. È responsabile dell'aggiornamento di Fleet Engine con la posizione del conducente, il percorso la distanza rimanente e l'orario di arrivo stimato. Inoltre, si integra con l'SDK di navigazione, che fornisce istruzioni di navigazione passo passo per il conducente.

Requisiti minimi di sistema

Sul dispositivo mobile deve essere installato iOS 14 o versioni successive.

Xcode. versione 15 o successive.

Prerequisiti

Questa guida presuppone che la tua app implementi già SDK di navigazione e che Motore della flotta il backend è configurato e disponibile. Tuttavia, il codice di esempio fornisce un esempio di come configurare SDK di navigazione.

Devi anche attivare l'SDK Maps per iOS nel tuo progetto Google Cloud e ottieni una chiave API.

Sviluppo locale

Per lo sviluppo locale, è sufficiente accedere con Cloud SDK.

gcloud

gcloud auth login

L'email utilizzata per accedere deve essere membro del gruppo Workspace.

Automazione (sistemi di creazione o integrazione continua)

Configura gli host di automazione in base a best practice:

• Se il tuo processo viene eseguito all'interno di un ambiente Google Cloud, utilizza automatico il rilevamento delle credenziali.

• In caso contrario, archivia il file della chiave dell'account di servizio in una posizione sicura al file system dell'host e impostare GOOGLE_APPLICATION_CREDENTIALS la variabile di ambiente in modo appropriato.

L'indirizzo email dell'account di servizio associato alle credenziali deve essere un membro di il gruppo di Workspace.

Configurazione progetto

Gestore pacchetti Swift

L'SDK Driver può essere installato tramite Gestore pacchetti Swift. Per aggiungere l'SDK, assicurati di avere rimosso eventuali dipendenze esistenti dell'SDK del driver.

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 il file Xcode project o workspace, quindi seleziona File > Aggiungi dipendenze pacchetto.
2. Inserisci https://github.com/googlemaps/ios-driver-sdk come URL e premi Invio per estrarre il pacchetto e fai clic su "Aggiungi pacchetto".
3. Per installare un'entità version specifica, imposta il campo Regola di dipendenza su uno dei le opzioni basate sulla versione. Per i nuovi progetti, ti consigliamo di specificare la versione più recente con la "versione esatta" . Al termine, fai clic su "Aggiungi pacchetto".
4. Nella finestra Scegli i prodotti del pacchetto, verifica che verrà aggiunto GoogleRidesharingDriver il target main designato. Al termine, fai clic su "Aggiungi pacchetto".
5. Per verificare l'installazione, vai al riquadro General di destinazione. In Framework, librerie e contenuti incorporati dovresti vedere i pacchetti installati. Puoi anche visualizzare le "Dipendenze pacchetto" sezione di "Project Navigator" per verificare il pacchetto e la sua versione.

Per aggiornare package per un progetto esistente:

1. Se esegui l'upgrade da una versione precedente alla 9.0.0, devi rimuovere le dipendenze seguenti: GoogleMapsBase, GoogleMapsCore e GoogleMapsM4B dopo l'upgrade. Non rimuovere la dipendenza per GoogleMaps. Per ulteriori informazioni, consulta Note di rilascio della versione 9.0.0.

   Dalle impostazioni di configurazione del progetto Xcode, individua Framework, Libraries, e Contenuti incorporati. Utilizza il segno meno(-) per rimuovere il seguente framework:

   • GoogleMapsBase (solo per gli upgrade da versioni precedenti alla 9.0.0)
   • GoogleMapsCore (solo per gli upgrade da versioni precedenti alla 9.0.0)
   • GoogleMapsM4B (solo per gli upgrade da versioni precedenti alla 9.0.0)
2. Da Xcode, vai su "File > Pacchetti > Aggiorna alle ultime versioni del pacchetto".
3. Per verificare l'installazione, vai alla sezione Dipendenze pacchetto di Project Navigator per verificare il pacchetto e la sua versione.

di Gemini Advanced.

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 esistenti dell'SDK del driver aggiunte utilizzando CocoaPods, segui questi passaggi:

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

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

2. Rimuovi Podfile, Podfile.resolved e Esegui l'Xcode workspace se non lo utilizzi per scopi diversi da CocoaPods.

Per rimuovere l'SDK del driver esistente installato manualmente, segui questi passaggi:

1. Dalle impostazioni di configurazione del tuo progetto Xcode, individua Frameworks, Librerie e contenuti incorporati. Utilizza il segno meno(-) per rimuovere l'elemento. il seguente framework:

   • GoogleRidesharingDriver.xcframework

2. Dalla directory di primo livello del tuo progetto Xcode, rimuovi Set GoogleRidesharingDriver.

CocoaPods

Per configurare l'SDK Driver utilizzando CocoaPods, sono necessari i seguenti elementi:

• Lo strumento CocoaPods: per installare lo strumento, apri il terminale ed esegui .

   sudo gem install cocoapods

1. Creare un podfile per l'SDK Driver e utilizzarlo per installare l'API e e le sue dipendenze: crea un file denominato Podfile nella directory del progetto. Questo file definisce le dipendenze del progetto. Modifica il podfile e aggiungi le tue dipendenze. Ecco un esempio che include le dipendenze:

   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

   Ecco un esempio che include i pod Alpha e Beta per SDK driver come dipendenze:

   source "https://cpdc-eap.googlesource.com/ridesharing-driver-sdk.git"
   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

2. Salva il podfile. Apri un terminale e vai alla directory contenente Podfile:

   cd <path-to-project>
   

3. Esegui il comando di installazione dei pod. Questa operazione installerà le API specificate nel di pod, insieme alle eventuali dipendenze.

   pod install
   

4. Chiudi Xcode, quindi apri (fai doppio clic) nell'area di lavoro .xcworkspace del tuo progetto per avviare Xcode. D'ora in poi, dovrai utilizzare .xcworkspace per aprire il progetto.

di Gemini Advanced.

Nota: esegui periodicamente pod outdated per rilevare quando è disponibile una nuova versione dell'SDK. Per ulteriori informazioni, vedi SDK driver per iOS Versioni.

Fai riferimento alla guida introduttiva di CocoaPods guida per saperne di più i dettagli.

Installazione manuale

Attenzione: come best practice, usa Swift Package Manager oppure Cocoapod deve installare l'SDK Driver in qualsiasi momento possibile. Prima di seguire questa guida, assicurati di aver scaricato XCFramework.

Un XCFramework è un pacchetto binario che puoi usare per installare SDK driver. Puoi utilizzare questo pacchetto su più di Google Cloud, incluse le macchine che utilizzano Apple al silicio. Questa guida illustra come aggiungere manualmente l'XCFramework contenente Driver SDK nel progetto e configura la build impostazioni in Xcode.

Scarica il file binario e le risorse dell'SDK:

• GoogleRidesharingDriver.xcframework
• GoogleRidesharingDriver.bundle

Importante: prima di utilizzare questa guida, installa l'SDK di navigazione.

1. Estrai i file per accedere a XCFramework e alle risorse.

2. Avvia Xcode e apri un progetto esistente o creane uno nuovo progetto. Se è la prima volta che utilizzi iOS, crea un nuovo progetto e seleziona l'icona Modello di app.

3. Creare un gruppo Framework nel gruppo di progetto se non ne esiste uno .

4. Per installare l'SDK dei driver, trascina GoogleRidesharingDriver.xcframework nel tuo progetto in Framework, librerie e contenuti incorporati. Quando richiesto, seleziona Copia gli elementi, se necessario.

5. Trascina l'elemento GoogleRidesharingDriver.bundle scaricato in primo livello del tuo progetto Xcode. Quando richiesto, seleziona Copy items if needed.

6. Seleziona il tuo progetto dal navigatore dei progetti e scegli target dell'applicazione.

7. Apri la scheda Fasi di creazione e in Collega binario con le librerie aggiungi i seguenti framework e librerie, se non sono già presenti:

   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • LocalAuthentication.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • WebKit.framework

8. Scegli il tuo progetto, anziché un target specifico, e apri lo strumento Crea Impostazioni. Nella sezione Altri flag linker, aggiungi -ObjC per sia di debug che di release. Se queste impostazioni non sono visibili, modifica nella barra delle impostazioni della build da Di base a Tutte.

Ispeziona il file manifest della privacy di Apple

Apple richiede informazioni sulla privacy per le app disponibili sull'App Store. Visita la pagina dei dettagli sulla privacy dell'App Store di Apple per aggiornamenti e ulteriori informazioni.

Il file manifest della privacy di Apple è incluso nel bundle di risorse per l'SDK. Per verificare che il file manifest per la privacy sia stato incluso e per controllarne i contenuti, crea un archivio della tua app e genera una segnalazione sulla privacy dall'archivio.

Implementare l'autorizzazione e l'autenticazione

Quando l'app Driver genera e invia aggiornamenti al backend Fleet Engine, le richieste devono includere token di accesso validi. Per autorizzare e queste richieste, l'SDK del driver chiama l'oggetto in conformità GMTDAuthorization protocollo. L'oggetto è responsabile di fornire il token di accesso richiesto.

In qualità di sviluppatore dell'app, sei tu a scegliere il modo in cui vengono generati i token. La tua implementazione dovrebbe offrire la possibilità di:

• Recupera un token di accesso, possibilmente in formato JSON, da un server HTTPS.
• Analizza e memorizza nella cache il token.
• Aggiorna il token alla scadenza.

Per maggiori dettagli sui token previsti dal server Fleet Engine, consulta Creazione di un token JWT (JSON Web Token) per l'autorizzazione.

L'ID provider corrisponde all'ID progetto Google Cloud. Consulta la guida dell'utente dell'API Fleet Engine Deliveries per ulteriori informazioni.

L'esempio seguente implementa un provider di token di accesso:

#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

// SampleAccessTokenProvider.h
@interface SampleAccessTokenProvider : NSObject<GMTDAuthorization>
@end

static NSString *const PROVIDER_URL = @"INSERT_YOUR_TOKEN_PROVIDER_URL";

// SampleAccessTokenProvider.m
@implementation SampleAccessTokenProvider{
  // The cached vehicle token.
  NSString *_cachedVehicleToken;
  // Keep track of the vehicle ID the cached token is for.
  NSString *_lastKnownVehicleID;
  // Keep track of when tokens expire for caching.
  NSTimeInterval _tokenExpiration;
}

- (void)fetchTokenWithContext:(nullable GMTDAuthorizationContext *)authorizationContext
                   completion:(nonnull GMTDAuthTokenFetchCompletionHandler)completion {
  if (!completion) {
    NSAssert(NO, @"%s encountered an unexpected nil completion.", __PRETTY_FUNCTION__);
    return;
  }

  // Get the vehicle ID from the authorizationContext. This is set by the Driver SDK.
  NSString *vehicleID = authorizationContext.vehicleID;
  if (!vehicleID) {
    NSAssert(NO, @"Vehicle ID is missing from authorizationContext.");
    return;
  }

// Clear cached vehicle token if vehicle ID has changed.
  if (![_lastKnownVehicleID isEqual:vehicleID]) {
    _tokenExpiration = 0.0;
    _cachedVehicleToken = nil;
  }
  _lastKnownVehicleID = vehicleID;

  // Clear cached vehicle token if it has expired.
  if ([[NSDate date] timeIntervalSince1970] > _tokenExpiration) {
    _cachedVehicleToken = nil;
  }

  // If appropriate, use the cached token.
  if (_cachedVehicleToken) {
    completion(_cachedVehicleToken, nil);
    return;
  }
  // Otherwise, try to fetch a new token from your server.
  NSURL *requestURL = [NSURL URLWithString:PROVIDER_URL];
  NSMutableURLRequest *request = 
                          [[NSMutableURLRequest alloc] initWithURL:requestURL];
  request.HTTPMethod = @"GET";
  // Replace the following key values with the appropriate keys based on your
  // server's expected response.
  NSString *vehicleTokenKey = @"VEHICLE_TOKEN_KEY";
  NSString *tokenExpirationKey = @"TOKEN_EXPIRATION";
  __weak typeof(self) weakSelf = self;
  void (^handler)(NSData *_Nullable data, NSURLResponse *_Nullable response,
                  NSError *_Nullable error) =
      ^(NSData *_Nullable data, NSURLResponse *_Nullable response, NSError *_Nullable error) {
        typeof(self) strongSelf = weakSelf;
        if (error) {
          completion(nil, error);
          return;
        }

        NSError *JSONError;
        NSMutableDictionary *JSONResponse =
            [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&JSONError];

        if (JSONError) {
          completion(nil, JSONError);
          return;
        } else {
          // Sample code only. No validation logic.
          id expirationData = JSONResponse[tokenExpirationKey];
          if ([expirationData isKindOfClass:[NSNumber class]]) {
            NSTimeInterval expirationTime = ((NSNumber *)expirationData).doubleValue;
            strongSelf->_tokenExpiration = [[NSDate date] timeIntervalSince1970] + expirationTime;
          }
          strongSelf->_cachedVehicleToken = JSONResponse[vehicleTokenKey];
          completion(JSONResponse[vehicleTokenKey], nil);
        }
    };
NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *mainQueueURLSession =  
       [NSURLSession  sessionWithConfiguration:config delegate:nil
delegateQueue:[NSOperationQueue mainQueue]];
NSURLSessionDataTask *task = [mainQueueURLSession dataTaskWithRequest:request completionHandler:handler];
[task resume];
}

@end

Crea un'istanza DeliveryDriverAPI

Per ottenere un'istanza GMTDDeliveryVehicleReporter, devi prima creare un'istanza GMTDDeliveryDriverAPI utilizzando providerID, veicoliID, driverContext e accessTokenProvider. Il provider ID è uguale al valore ID progetto Google Cloud. Puoi accedere a GMTDDeliveryVehicleReporter direttamente dall'API driver.

Nota: come ottimizzazione prevista, GMSRoadSnappedLocationProvider potrebbe non inviare la posizione viene aggiornata continuamente se il dispositivo non è stato spostato dall'ultima volta aggiornamento della posizione. Questo può accadere se un conducente rimane inattivo in auto. Pertanto, se ci sono situazioni in cui GMTDDeliveryVehicleReporter è impostato come listener dopo startUpdatingLocation del giorno GMSRoadSnappedLocationProvider stata chiamato, ti consigliamo di interrompere e avviare GMSRoadSnappedLocationProvider per assicurarti che venga inviato un nuovo aggiornamento della posizione. Ad esempio, se il conducente sta aspettando inattivo in auto.

L'esempio seguente crea un'istanza GMTDDeliveryDriverAPI:

#import “SampleViewController.h”
#import “SampleAccessTokenProvider.h”
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}

- (void)viewDidLoad {
  NSString *vehicleID = @"INSERT_CREATED_VEHICLE_ID";
  SampleAccessTokenProvider *accessTokenProvider = 
                                [[SampleAccessTokenProvider alloc] init];
  GMTDDriverContext *driverContext = 
     [[GMTDDriverContext alloc] initWithAccessTokenProvider:accessTokenProvider
                                                 providerID:PROVIDER_ID 
                                              vehicleID:vehicleID 
      navigator:_mapView.navigator];

  GMTDDeliveryDriverAPI *deliveryDriverAPI = [[GMTDDeliveryDriverAPI alloc] initWithDriverContext:driverContext];
}

Facoltativamente, ascolta gli eventi di VehicleReporter

GMTDDeliveryVehicleReporter aggiorna periodicamente il veicolo quando locationTrackingEnabled è SÌ. Per rispondere a questi aggiornamenti periodici, qualsiasi può iscriversi a GMTDDeliveryVehicleReporter eventi rispettando le il protocollo GMTDVehicleReporterListener.

Puoi gestire i seguenti eventi:

• vehicleReporter:didSucceedVehicleUpdate

  Informa l'app driver che i servizi di backend hanno ricevuto correttamente il aggiornamento della posizione e dello stato del veicolo.

• vehicleReporter:didFailVehicleUpdate:withError

  Informa il listener che un aggiornamento del veicolo non è riuscito. A condizione che la posizione il monitoraggio è attivato, GMTDDeliveryVehicleReporter continua a inviare i dati più recenti al backend Fleet Engine.

Nell'esempio seguente vengono gestiti questi eventi:

SampleViewController.h
@interface SampleViewController : UIViewController<GMTDVehicleReporterListener>
@end

SampleViewController.m
#import “SampleViewController.h”
#import “SampleAccessTokenProvider.h”
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}


- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  [ridesharingDriverAPI.vehicleReporter addListener:self];
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didSucceedVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate {
  // Handle update succeeded.
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate withError:(NSError *)error {
  // Handle update failed.
}

@end

Attiva il monitoraggio della posizione

Per attivare il monitoraggio della posizione, la tua app può impostare locationTrackingEnabled su YES il giorno GMTDDeliveryVehicleReporter. Allora GMTDDeliveryVehicleReporter = invia automaticamente aggiornamenti sulla posizione. Quando GMSNavigator è in navigazione (quando una destinazione è impostata tramite setDestinations) e locationTrackingEnabled è impostato su YES, GMTDDeliveryVehicleReporter invia automaticamente anche aggiornamenti su percorso e orario di arrivo stimato.

Il percorso impostato durante questi aggiornamenti sarà lo stesso del conducente. durante la sessione di navigazione. Pertanto, affinché il monitoraggio della spedizione funzioni correttamente, il waypoint impostato tramite -setDestinations:callback: deve corrispondere impostata nel backend di Fleet Engine.

Il seguente esempio abilita il monitoraggio della posizione:

SampleViewController.m
#import “SampleViewController.h”
#import “SampleAccessTokenProvider.h”
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView; 
}

- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  deliveryDriverAPI.vehicleReporter.locationTrackingEnabled = YES;
}

@end

Per impostazione predefinita, l'intervallo di report è di 10 secondi, ma può da modificare con locationUpdateInterval. L'intervallo di aggiornamento minimo supportato è di 5 secondi. L'intervallo di aggiornamento massimo supportato è di 60 secondi. Più frequente degli aggiornamenti, le richieste e gli errori potrebbero essere più lenti.

Disattivare gli aggiornamenti della posizione

La tua app può disattivare gli aggiornamenti della posizione per un veicolo. Ad esempio, quando il turno del conducente termina, la tua app può impostare locationTrackingEnabled su NO.

  _vehicleReporter.locationTrackingEnabled = NO

Gestire gli errori update_mask

Quando GMTDDeliveryVehicleReporter invia un aggiornamento del veicolo, viene restituito un update_mask può verificarsi quando la maschera è vuota e solitamente si verifica per la prima vengono aggiornate dopo l'avvio. Nell'esempio seguente viene illustrato come gestire l'errore:

Swift

import GoogleRidesharingDriver

class VehicleReporterListener: NSObject, GMTDVehicleReporterListener {
  func vehicleReporter(
    _ vehicleReporter: GMTDVehicleReporter,
    didFail vehicleUpdate: GMTDVehicleUpdate,
    withError error: Error
  ) {
    let fullError = error as NSError
    if let innerError = fullError.userInfo[NSUnderlyingErrorKey] as? NSError {
      let innerFullError = innerError as NSError
      if innerFullError.localizedDescription.contains("update_mask cannot be empty") {
        emptyMaskUpdates += 1
        return
      }
    }
    failedUpdates += 1
  }

  override init() {
    emptyMaskUpdates = 0
    failedUpdates = 0
  }
}

Objective-C

#import "VehicleReporterListener.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

@implementation VehicleReporterListener {
  NSInteger emptyMaskUpdates = 0;
  NSInteger failedUpdates = 0;
}

- (void)vehicleReporter:(GMTDVehicleReporter *)vehicleReporter
  didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate
             withError:(NSError *)error {
  for (NSError *underlyingError in error.underlyingErrors) {
    if ([underlyingError.localizedDescription containsString:@"update_mask cannot be empty"]) {
      emptyMaskUpdates += 1;
      return;
    }
  }
  failedUpdates += 1
}

@end