Introduzione all'SDK Driver per iOS

L'SDK Driver è una libreria che puoi integrare nell'app del driver. È responsabile dell'aggiornamento di Fleet Engine con la posizione del veicolo, 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 in un secondo momento.
  • 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.

    Accesso

    Se sei cliente di Google Workspace, crea un Gruppo di Workspace come google-maps-platform-sdk-users@workspacedomain.com durante l'onboarding e fornire il nome a Google. Questo è l'approccio consigliato. Il tuo gruppo Workspace verrà poi aggiunto a una lista consentita concede l'accesso ai repository CocoaPods corretti. Verifica che l'utente le email e quelle degli account di servizio che richiedono l'accesso sono incluse in questo elenco.

    Se la tua organizzazione non può creare gruppi di Workspace, invia a Google un elenco di indirizzi email di account di utenti e servizi che necessitano dell'accesso a questi artefatti.

    Sviluppo locale

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

    gcloud

    gcloud auth login

    L'indirizzo email utilizzato per accedere deve essere un 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 gruppo Workspace.

    Configurazione progetto

    Puoi configurare Driver SDK per iOS utilizzando Cocoapods o manualmente.

    Usa Cocoapods

    Per configurare l'SDK Driver per iOS, sono necessari i seguenti elementi:

    • Lo strumento CocoaPods: per installare lo strumento, apri il terminale ed esegui . shell sudo gem install cocoapods Consulta le Guida introduttiva di CocoaPods per ulteriori dettagli.

    1. Crea un podfile per l'SDK Driver per iOS e utilizzalo per installare API e relative dipendenze: crea un file denominato Podfile nel progetto . Questo file definisce le dipendenze del progetto. Modifica il e aggiungi le tue dipendenze. Ecco un esempio che include delle dipendenze:

      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 installa 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.

    Installare XCFramework

    Scarica il file binario e le risorse dell'SDK:

    Un XCFramework è un pacchetto binario che puoi utilizzare per installare l'SDK Driver. Puoi utilizzare questo pacchetto su più piattaforme, incluse le macchine che utilizzano il chipset M1. Questa guida mostra come aggiungere manualmente al progetto l'XCFramework contenente l'SDK dei driver e configurare le impostazioni di build in Xcode.

    1. Decomprimi i file compressi per accedere a XCFramework e alle risorse.

    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. Crea un gruppo di framework nel gruppo di progetto, se non ne esiste già uno.

    4. Trascina il file gRPCCertificates.bundle scaricato nella directory di primo livello del tuo progetto Xcode. Quando richiesto, seleziona Copia elementi, se necessario.

    5. Per installare l'SDK Driver, trascina il file GoogleRidesharingDriver.xcframework nel progetto in Framework, librerie e contenuti incorporati. Quando richiesto, seleziona Copia elementi, se necessario.

    6. Trascina l'oggetto GoogleRidesharingDriver.bundle scaricato nella directory di primo livello del tuo progetto Xcode. Quando richiesto, seleziona Copy items if needed.

    7. Seleziona il tuo progetto dal navigatore dei progetti e scegli il target della tua applicazione.

    8. Apri la scheda Fasi di creazione e, in Collega binario con le librerie, aggiungi i framework e le librerie seguenti 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

    9. Scegli il progetto anziché una destinazione specifica e apri la scheda Impostazioni build. Nella sezione Altri flag linker, aggiungi ‑ObjC sia per il debug che per la release. Se queste impostazioni non sono visibili, modifica il filtro nella barra delle impostazioni della build da Di base a Tutte.

    Versioni SDK alpha/beta

    Per configurare le versioni alpha o beta dell'SDK Driver per iOS è necessario i seguenti elementi:

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

      sudo gem install cocoapods

      Consulta le Guida introduttiva a CocoaPods per ulteriori dettagli.

    • Il tuo account di sviluppo nell'elenco di accesso di Google. Il repository dei pod delle versioni alpha e beta dell'SDK non sono di origine pubblica. A per accedere a queste versioni, contatta un Customer Engineer di Google. Il tecnico aggiunge il tuo account di sviluppo all'elenco per gli accessi e quindi imposta un cookie per autenticazione.

    Quando il progetto è nell'elenco per gli accessi, puoi accedere al pod.

    1. Crea un podfile per l'SDK Driver per iOS e utilizzalo per installare API e relative dipendenze: crea un file denominato Podfile nel progetto . Questo file definisce le dipendenze del progetto. Modifica il e aggiungi le tue dipendenze. Ecco un esempio che include delle 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. Questo comando installa le API specificate nel podfile, 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.

    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 di autenticare queste richieste, l'SDK del driver chiama conforme a 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 i token providerID, vehicleID, driverContext e accessTokenProvider. Il providerID è uguale a ID progetto Google Cloud. Puoi accedere a GMTDDeliveryVehicleReporter direttamente dall'API driver.

    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. Poi 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 è lo stesso del conducente. durante la sessione di navigazione. Affinché il monitoraggio della flotta 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.

    Disattiva gli aggiornamenti sulla posizione e metti offline il veicolo

    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