Erste Schritte mit dem Driver SDK für iOS

Das Driver SDK ist eine Bibliothek, die Sie in Ihre Treiber-App einbinden. Es sorgt dafür, dass die Fleet Engine mit dem Standort des Fahrers, der Route, der verbleibenden Entfernung und der voraussichtliche Ankunftszeit aktualisiert wird. Außerdem ist sie in das Navigation SDK integriert, das dem Fahrer eine detaillierte Routenführung bietet.

Mindestsystemanforderungen

  • Auf dem Mobilgerät muss iOS 14 oder höher installiert sein.
  • Xcode Version 14 oder höher.
  • Voraussetzungen

    In diesem Leitfaden wird davon ausgegangen, dass in Ihrer Anwendung bereits das Navigation SDK implementiert ist und das Fleet Engine-Back-End eingerichtet und verfügbar ist. Der Beispielcode enthält jedoch ein Beispiel für die Einrichtung des Navigation SDK.

    Außerdem müssen Sie in Ihrem Google Cloud-Projekt das Maps SDK for iOS aktivieren und API-Schlüssel anfordern.

    Zugriff erhalten

    Wenn Sie Google Workspace-Kunde sind, erstellen Sie während des Onboardings eine Arbeitsbereichgruppe wie google-maps-platform-sdk-users@workspacedomain.com und geben Sie Google den Namen an. Dies ist der empfohlene Ansatz. Ihre Arbeitsbereichsgruppe wird dann einer Zulassungsliste hinzugefügt, die Zugriff auf die richtigen CocoaPods-Repositories gewährt. Bestätigen Sie, dass die E-Mail-Adressen der Nutzer und des Dienstkontos, die Zugriff benötigen, in dieser Liste enthalten sind.

    Wenn Ihre Organisation keine Arbeitsbereichsgruppen erstellen kann, senden Sie eine Liste der Nutzer- und Dienstkonto-E-Mails, die Zugriff auf diese Artefakte benötigen, an Google.

    Lokale Entwicklung

    Für die lokale Entwicklung reicht es aus, sich mit dem Cloud SDK anzumelden.

    gcloud

    gcloud auth login
    

    Die E-Mail-Adresse, mit der Sie sich anmelden, muss Mitglied der Workspace-Gruppe sein.

    Automatisierung (Systeme erstellen oder Continuous Integration)

    Richten Sie Ihre Automatisierungshosts gemäß den Best Practices ein:

    • Wenn Ihr Prozess in einer Google Cloud-Umgebung ausgeführt wird, verwenden Sie die automatische Anmeldedatenerkennung.

    • Andernfalls speichern Sie die Dienstkonto-Schlüsseldatei an einem sicheren Ort im Dateisystem des Hosts und legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS entsprechend fest.

    Die mit den Anmeldedaten verknüpfte E-Mail-Adresse des Dienstkontos muss Mitglied der Workspace-Gruppe sein.

    Projektkonfiguration

    Sie können das Driver SDK mithilfe von CocoaPods konfigurieren.

    Mit CocoaPods

    Um das Treiber SDK mit CocoaPods zu konfigurieren, benötigen Sie Folgendes:

    • CocoaPods-Tool: Öffnen Sie zum Installieren dieses Tools das Terminal und führen Sie den folgenden Befehl aus. shell sudo gem install cocoapods Weitere Informationen findest du im Startleitfaden zu CocoaPods.
    1. Erstellen Sie eine Podfile-Datei für das Driver SDK und installieren Sie damit die API und die zugehörigen Abhängigkeiten: Erstellen Sie in Ihrem Projektverzeichnis eine Datei namens Podfile. In dieser Datei sind die Abhängigkeiten Ihres Projekts definiert. Bearbeiten Sie die Podfile-Datei und fügen Sie die Abhängigkeiten hinzu. Hier ist ein Beispiel mit den Abhängigkeiten:

      source "https://github.com/CocoaPods/Specs.git"
      
      target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
        pod 'GoogleRidesharingDriver'
      end
      
    2. Speichern Sie die Podfile-Datei. Öffnen Sie ein Terminal und rufen Sie das Verzeichnis auf, das die Podfile-Datei enthält:

      cd <path-to-project>
      
    3. Führen Sie den Befehl "pod install" aus. Dadurch werden die in der Podfile-Datei angegebenen APIs und alle zugehörigen Abhängigkeiten installiert.

      pod install
      
    4. Schließen Sie Xcode und öffnen Sie per Doppelklick die .xcworkspace-Datei Ihres Projekts, um Xcode zu starten. Ab diesem Zeitpunkt müssen Sie zum Öffnen des Projekts die .xcworkspace-Datei verwenden.

    Alpha-/Beta-SDK-Versionen

    Zum Konfigurieren der Alpha- oder Betaversionen des Driver SDK for iOS benötigen Sie Folgendes:

    • CocoaPods-Tool: Öffnen Sie zum Installieren dieses Tools das Terminal und führen Sie den folgenden Befehl aus.

      sudo gem install cocoapods
      

      Weitere Informationen findest du im Startleitfaden zu CocoaPods.

    • Ihr Entwicklungskonto auf der Google-Zugriffsliste. Das Pod-Repository der Alpha- und Betaversionen des SDK ist keine öffentliche Quelle. Um auf diese Versionen zuzugreifen, wenden Sie sich an den Google Customer Engineer. Der Entwickler fügt Ihr Entwicklungskonto der Zugriffsliste hinzu und speichert dann ein Cookie für die Authentifizierung.

    Sobald sich Ihr Projekt in der Zugriffsliste befindet, können Sie auf den Pod zugreifen.

    1. Erstellen Sie eine Podfile-Datei für das Driver SDK for iOS und installieren Sie damit die API und die zugehörigen Abhängigkeiten: Erstellen Sie in Ihrem Projektverzeichnis eine Datei namens Podfile. In dieser Datei sind die Abhängigkeiten Ihres Projekts definiert. Bearbeiten Sie die Podfile-Datei und fügen Sie die Abhängigkeiten hinzu. Hier ist ein Beispiel mit den Abhängigkeiten:

      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. Speichern Sie die Podfile-Datei. Öffnen Sie ein Terminal und rufen Sie das Verzeichnis auf, das die Podfile-Datei enthält:

      cd <path-to-project>
      
    3. Führen Sie den Befehl "pod install" aus. Dadurch werden die in der Podfile-Datei angegebenen APIs und alle zugehörigen Abhängigkeiten installiert.

      pod install
      
    4. Schließen Sie Xcode und öffnen Sie per Doppelklick die .xcworkspace-Datei Ihres Projekts, um Xcode zu starten. Ab diesem Zeitpunkt müssen Sie zum Öffnen des Projekts die .xcworkspace-Datei verwenden.

    XCFramework installieren

    Ein XCFramework ist ein Binärpaket, mit dem Sie das Driver SDK installieren. Sie können dieses Paket auf mehreren Plattformen verwenden, einschließlich Computern mit dem M1-Chipsatz. In diesem Leitfaden erfahren Sie, wie Sie das XCFramework mit dem Treiber-SDK manuell zu Ihrem Projekt hinzufügen und Ihre Build-Einstellungen in Xcode konfigurieren.

    Laden Sie die SDK-Binärdatei und die Ressourcen herunter:

    1. Entpacken Sie die ZIP-Dateien, um auf XCFramework und Ressourcen zuzugreifen.

    2. Starten Sie Xcode und öffnen Sie entweder ein vorhandenes Projekt oder erstellen Sie ein neues. Wenn Sie neu bei iOS sind, erstellen Sie ein neues Projekt und wählen Sie die Vorlage für iOS-Apps aus.

    3. Erstellen Sie eine Frameworks-Gruppe in Ihrer Projektgruppe, falls noch keine vorhanden ist.

    4. Ziehen Sie die heruntergeladene Datei gRPCCertificates.bundle in das Verzeichnis der obersten Ebene Ihres Xcode-Projekts. Wenn Sie dazu aufgefordert werden, wählen Sie bei Bedarf Elemente kopieren aus.

    5. Ziehen Sie zum Installieren des Driver SDK die Datei GoogleRidesharingDriver.xcframework in Ihr Projekt unter Frameworks, Bibliotheken und eingebettete Inhalte. Wenn Sie dazu aufgefordert werden, wählen Sie bei Bedarf Elemente kopieren aus.

    6. Ziehen Sie das heruntergeladene GoogleRidesharingDriver.bundle in das Verzeichnis der obersten Ebene Ihres Xcode-Projekts. Wenn Sie dazu aufgefordert werden, wählen Sie Copy items if needed aus.

    7. Wählen Sie Ihr Projekt aus dem Project Navigator und anschließend das Ziel Ihrer App aus.

    8. Öffnen Sie den Tab „Build Phases“ (Build-Phasen) und fügen Sie unter „Link Binary with Libraries“ (Binärdatei mit Bibliotheken verknüpfen) die folgenden Frameworks und Bibliotheken hinzu, sofern sie noch nicht vorhanden sind:

      • 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. Wählen Sie Ihr Projekt anstelle eines bestimmten Ziels aus und öffnen Sie den Tab Build Settings (Build-Einstellungen). Fügen Sie im Bereich Weitere Verknüpfungs-Flags ‑ObjC für die Fehlerbehebung und den Release hinzu. Falls diese Einstellungen nicht angezeigt werden, ändern Sie den Filter in der Build-Einstellungsleiste von Einfach in Alle.

    Autorisierung und Authentifizierung implementieren

    Wenn Ihre Treiberanwendung Updates generiert und an das Fleet Engine-Back-End sendet, müssen die Anfragen gültige Zugriffstokens enthalten. Zum Autorisieren und Authentifizieren dieser Anfragen ruft das Driver SDK das Objekt gemäß dem GMTDAuthorization-Protokoll auf. Das Objekt ist für die Bereitstellung des erforderlichen Zugriffstokens verantwortlich.

    Als App-Entwickler entscheiden Sie, wie Tokens generiert werden. Ihre Implementierung sollte Folgendes ermöglichen:

    • Rufen Sie ein Zugriffstoken, möglicherweise im JSON-Format, von einem HTTPS-Server ab.
    • Parsen Sie das Token und speichern Sie es im Cache.
    • Aktualisieren Sie das Token, wenn es abläuft.

    Weitere Informationen zu den vom Fleet Engine-Server erwarteten Tokens finden Sie unter JSON Web Token (JWT) für die Autorisierung erstellen.

    Die Anbieter-ID ist mit der Google Cloud-Projekt-ID identisch. Weitere Informationen finden Sie im Nutzerhandbuch der Fleet Engine Deliveries API.

    Im folgenden Beispiel wird ein Zugriffstoken-Anbieter implementiert:

    #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
    

    DeliveryDriverAPI-Instanz erstellen

    Um eine GMTDDeliveryVehicleReporter-Instanz zu erhalten, müssen Sie zuerst eine GMTDDeliveryDriverAPI-Instanz mit den Anbieter-IDs, vehicleID, driverContext und accessTokenProvider erstellen. Die providerID ist mit der Google Cloud-Projekt-ID identisch. Außerdem können Sie über die Treiber API direkt auf die GMTDDeliveryVehicleReporter-Instanz zugreifen.

    Im folgenden Beispiel wird eine GMTDDeliveryDriverAPI-Instanz erstellt:

    #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];
    }
    

    Optional: VehicleReporter-Ereignisse überwachen

    GMTDDeliveryVehicleReporter aktualisiert das Fahrzeug regelmäßig, wenn locationTrackingEnabled JA ist. Um auf diese regelmäßigen Updates zu reagieren, kann jedes Objekt GMTDDeliveryVehicleReporter-Ereignisse abonnieren, indem es dem GMTDVehicleReporterListener-Protokoll entspricht.

    Sie können die folgenden Ereignisse verarbeiten:

    • vehicleReporter:didSucceedVehicleUpdate

      Informiert die Fahrer-App darüber, dass die Back-End-Dienste den Fahrzeugstandort und die Statusaktualisierung erfolgreich erhalten haben.

    • vehicleReporter:didFailVehicleUpdate:withError

      Informiert den Listener, dass eine Fahrzeugaktualisierung fehlgeschlagen ist. Solange die Standortverfolgung aktiviert ist, sendet GMTDDeliveryVehicleReporter weiterhin die neuesten Daten an das Fleet Engine-Back-End.

    Im folgenden Beispiel werden diese Ereignisse verarbeitet:

    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
    

    Standortermittlung aktivieren

    Um das Standort-Tracking zu aktivieren, kann deine App locationTrackingEnabled auf YES auf GMTDDeliveryVehicleReporter setzen. Dann sendet GMTDDeliveryVehicleReporter automatisch Standortaktualisierungen. Wenn sich GMSNavigator im Navigationsmodus befindet (wenn über setDestinations ein Ziel festgelegt wird) und locationTrackingEnabled auf YES gesetzt ist, sendet GMTDDeliveryVehicleReporter auch automatisch Aktualisierungen der Route und der voraussichtliche Ankunftszeit.

    Die bei diesen Aktualisierungen festgelegte Route ist die Route, die der Fahrer während der Navigation durchläuft. Damit die Sendungsverfolgung ordnungsgemäß funktioniert, muss der über -setDestinations:callback: festgelegte Wegpunkt mit dem im Fleet Engine-Back-End festgelegten Ziel übereinstimmen.

    Im folgenden Beispiel wird die Standortermittlung aktiviert:

    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
    

    Das Berichtsintervall beträgt standardmäßig 10 Sekunden, kann aber mit locationUpdateInterval geändert werden. Das mindestens unterstützte Aktualisierungsintervall beträgt 5 Sekunden. Das maximal unterstützte Aktualisierungsintervall beträgt 60 Sekunden. Häufigere Updates können zu langsameren Anfragen und Fehlern führen.

    Standortaktualisierungen deaktivieren

    Ihre App kann Standortaktualisierungen für ein Fahrzeug deaktivieren. Wenn beispielsweise die Schicht eines Fahrgasts endet, kann Ihre Anwendung locationTrackingEnabled auf NO setzen.

      _vehicleReporter.locationTrackingEnabled = NO
    

    „update_mask“-Fehler beheben

    Wenn GMTDDeliveryVehicleReporter ein Fahrzeugupdate sendet, kann ein update_mask-Fehler auftreten, wenn die Maske leer ist. Dies geschieht normalerweise bei der ersten Aktualisierung nach dem Start. Das folgende Beispiel zeigt, wie dieser Fehler behandelt wird:

    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