Last Mile Fleet Solution n'est actuellement disponible que pour certains clients. Contactez le service commercial pour en savoir plus.

Premiers pas avec le SDK Driver pour iOS

Le SDK Driver est une bibliothèque que vous intégrez à votre application de pilote. Il est chargé de mettre à jour le moteur Fleet Engine en indiquant la position du conducteur, l'itinéraire, la distance restante et l'heure d'arrivée prévue. Il s'intègre également au SDK Navigation, qui fournit des instructions de navigation détaillées au conducteur.

Configuration système minimale requise

  • L'appareil mobile doit être équipé d'iOS 12 ou version ultérieure.
  • Xcode version 13 ou ultérieure.
  • Prérequis

    Ce guide suppose que votre application implémente déjà le SDK Navigation et que le backend de Fleet Engine est configuré et disponible. Cependant, l'exemple de code fournit un exemple de configuration du SDK Navigation.

    Vous devez également activer le SDK Maps pour iOS dans votre projet Google Cloud et obtenir une clé API.

    Obtenir l'accès

    Si vous êtes un client Google Workspace, créez un groupe Workspace tel que google-maps-platform-sdk-users@workspacedomain.com lors de l'intégration et fournissez le nom à Google. Il s'agit de l'approche recommandée. Votre groupe Workspace sera ensuite ajouté à une liste d'autorisation qui accorde l'accès aux dépôts CocoaPods appropriés. Vérifiez que cette liste contient les adresses e-mail des utilisateurs et les adresses e-mail du compte de service qui doivent être accessibles.

    Si votre organisation ne peut pas créer de groupes Workspace, envoyez à Google la liste des adresses e-mail des utilisateurs et des comptes de service qui ont besoin d'accéder à ces artefacts.

    Développement local

    Pour le développement local, il suffit de se connecter avec le SDK Cloud.

    gcloud

    gcloud auth login
    

    L'adresse e-mail utilisée pour se connecter doit faire partie du groupe Workspace.

    Automatisation (systèmes de compilation ou intégration continue)

    Configurez vos hôtes d'automatisation conformément aux bonnes pratiques:

    • Si votre processus s'exécute dans un environnement Google Cloud, utilisez la détection automatique des identifiants.

    • Sinon, stockez le fichier de clé de compte de service à un emplacement sécurisé dans le système de fichiers de l'hôte et définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS de manière appropriée.

    L'adresse e-mail du compte de service associé aux identifiants doit être membre de Google Workspace.

    Configuration du projet

    Vous pouvez configurer le SDK Driver à l'aide de CocoaPods.

    Utiliser CocoaPods

    Pour configurer le SDK Driver à l'aide de CocoaPods, vous avez besoin des éléments suivants:

    • Outil CocoaPods: pour installer cet outil, ouvrez le terminal et exécutez la commande suivante. shell sudo gem install cocoapods Pour en savoir plus, consultez le guide de démarrage de CocoaPods.
    1. Créez un fichier Podfile pour le SDK Driver et utilisez-le pour installer l'API et ses dépendances: créez un fichier nommé Podfile dans le répertoire de votre projet. Ce fichier définit les dépendances de votre projet. Modifiez le fichier Podfile et ajoutez vos dépendances. Voici un exemple qui inclut les dépendances:

      source "https://github.com/CocoaPods/Specs.git"
      
      target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
        pod 'GoogleRidesharingDriver'
      end
      
    2. Enregistrez le Podfile. Ouvrez un terminal et accédez au répertoire contenant le Podfile:

      cd <path-to-project>
      
    3. Exécuter la commande d'installation du pod Cette opération installe les API spécifiées dans le Podfile, ainsi que les dépendances éventuelles.

      pod install
      
    4. Fermez Xcode, puis ouvrez (en double-cliquant) le fichier .xcworkspace de votre projet pour lancer Xcode. À partir de cette date, vous devez utiliser le fichier .xcworkspace pour ouvrir le projet.

    Versions du SDK alpha et bêta

    Pour configurer les versions alpha ou bêta du SDK Driver pour iOS, vous avez besoin des éléments suivants:

    • Outil CocoaPods: pour installer cet outil, ouvrez le terminal et exécutez la commande suivante.

      sudo gem install cocoapods
      

      Pour en savoir plus, consultez le Guide de démarrage de CocoaPods.

    • Votre compte de développement sur la liste d'accès Google Le dépôt du pod des versions alpha et bêta du SDK n'est pas une source publique. Pour y accéder, contactez l'ingénieur client Google. L'ingénieur ajoute votre compte de développement à la liste d'accès, puis définit un cookie pour l'authentification.

    Une fois votre projet dans la liste des accès, vous pouvez accéder au pod.

    1. Créez un fichier Podfile pour le SDK Driver pour iOS et utilisez-le pour installer l'API et ses dépendances: créez un fichier nommé Podfile dans le répertoire de votre projet. Ce fichier définit les dépendances de votre projet. Modifiez le fichier Podfile et ajoutez vos dépendances. Voici un exemple qui inclut les dépendances:

      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. Enregistrez le Podfile. Ouvrez un terminal et accédez au répertoire contenant le Podfile:

      cd <path-to-project>
      
    3. Exécuter la commande d'installation du pod Cette opération installe les API spécifiées dans le Podfile, ainsi que les dépendances éventuelles.

      pod install
      
    4. Fermez Xcode, puis ouvrez (en double-cliquant) le fichier .xcworkspace de votre projet pour lancer Xcode. À partir de cette date, vous devez utiliser le fichier .xcworkspace pour ouvrir le projet.

    Installer XCFramework

    Un XCFramework est un package binaire que vous utilisez pour installer le SDK Driver. Vous pouvez utiliser ce package sur plusieurs plates-formes, y compris les machines à l'aide du chipset M1. Ce guide explique comment ajouter manuellement le XCFramework contenant le SDK Driver à votre projet et configurer vos paramètres de compilation dans Xcode.

    1. Décompressez les fichiers sources que vous avez reçus de Google.

    2. Lancez Xcode, puis ouvrez un projet existant ou créez-en un. Si vous découvrez iOS, créez un projet et sélectionnez le modèle d'application iOS.

    3. S'il n'en existe pas déjà un, créez-en un sous votre groupe de projets.

    4. Faites glisser le fichier gRPCCertificates.bundle inclus dans le répertoire Resources du fichier ZIP contenant le XCFramework dans le répertoire de premier niveau de votre projet Xcode. Lorsque vous y êtes invité, sélectionnez "Copier les éléments" si nécessaire.

    5. Pour installer le SDK Driver, faites glisser le fichier GoogleRidesharingDriver.xcframework dans votre projet sous Frameworks, Libraries, and Embedded Content. Lorsque vous y êtes invité, sélectionnez "Copier les éléments" si nécessaire.

    6. Sélectionnez votre projet dans le navigateur du projet, puis choisissez la cible de votre application.

    7. Ouvrez l'onglet Phases de compilation, puis, dans le lien binaire avec les bibliothèques, ajoutez les frameworks et bibliothèques suivants s'ils ne sont pas déjà présents:

      • 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
      • OpenGLES.framework
      • QuartzCore.framework
      • SystemConfiguration.framework
      • UIKit.framework
      • LocalAuthentication.framework
      • WebKit.framework
    8. Choisissez votre projet plutôt qu'une cible spécifique, puis ouvrez l'onglet Build Settings (Paramètres de compilation). Dans la section Autres indicateurs d'association, ajoutez ‑ObjC pour le débogage et la version. Si ces paramètres ne sont pas visibles, remplacez le filtre Basic par Tous dans la barre "Paramètres de compilation".

    Implémenter l'autorisation et l'authentification

    Lorsque votre application Driver génère et envoie des mises à jour au backend de Fleet Engine, les requêtes doivent inclure des jetons d'accès valides. Pour autoriser et authentifier ces requêtes, le SDK Driver appelle votre objet conformément au protocole GMTDAuthorization. L'objet est chargé de fournir le jeton d'accès requis.

    En tant que développeur de l'application, vous choisissez comment les jetons sont générés. Votre implémentation doit permettre:

    • Récupérez un jeton d'accès, peut-être au format JSON, à partir d'un serveur HTTPS.
    • Analyser et mettre en cache le jeton
    • Actualisez le jeton lorsqu'il expire.

    Pour en savoir plus sur les jetons attendus par le serveur Fleet Engine, consultez Créer un jeton Web JSON (JWT) pour l'autorisation.

    L'ID du fournisseur est le même que l'ID du projet Google Cloud. Pour en savoir plus, consultez le guide de l'utilisateur pour l'API Fleet Engine Deliveries.

    L'exemple suivant met en œuvre un fournisseur de jetons d'accès:

    #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
    

    Créer une instance DeliveryDriverAPI

    Pour obtenir une instance GMTDDeliveryVehicleReporter, vous devez d'abord créer une instance GMTDDeliveryDriverAPI à l'aide de l'ID du fournisseur, de l'ID du véhicule, du piloteContext et du accessTokenProvider. L'ID fournisseur est identique à l'ID du projet Google Cloud. Vous pouvez également accéder directement à l'instance GMTDDeliveryVehicleReporter à partir de l'API du pilote.

    L'exemple suivant crée une instance 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];
    }
    

    Écouter les événements VehicleReporter (facultatif)

    GMTDDeliveryVehicleReporter met régulièrement à jour le véhicule lorsque locationTrackingEnabled est OUI. Pour répondre à ces mises à jour périodiques, n'importe quel objet peut s'abonner à des événements GMTDDeliveryVehicleReporter en se conformant au protocole GMTDVehicleReporterListener.

    Vous pouvez gérer les événements suivants:

    • vehicleReporter:didSucceedVehicleUpdate

      Indique à l'application Driver que les services de backend ont bien reçu la mise à jour de l'emplacement et de l'état du véhicule.

    • vehicleReporter:didFailVehicleUpdate:withError

      Indique à l'écouteur qu'une mise à jour du véhicule a échoué. Tant que le suivi de la position est activé, GMTDDeliveryVehicleReporter continue d'envoyer les dernières données au backend de Fleet Engine.

    L'exemple suivant gère ces événements:

    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
    

    Activer le suivi de la position

    Pour activer le suivi de la position, votre application peut définir locationTrackingEnabled sur YES sur GMTDDeliveryVehicleReporter. Ensuite, GMTDDeliveryVehicleReporter enverra automatiquement les mises à jour de votre position. Lorsque GMSNavigator est en mode navigation (lorsqu'une destination est définie via setDestinations) et que locationTrackingEnabled est défini sur YES, GMTDDeliveryVehicleReporter envoie automatiquement les mises à jour de l'itinéraire et de l'heure d'arrivée prévue.

    L'itinéraire défini lors de ces mises à jour sera le même que celui emprunté par le conducteur lors de la session de navigation. Ainsi, pour que le suivi des livraisons fonctionne correctement, le point de cheminement défini via -setDestinations:callback: doit correspondre à la destination définie dans le backend de Fleet Engine.

    L'exemple suivant active le suivi de la position:

    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
    

    Par défaut, l'intervalle de reporting est de 10 secondes, mais vous pouvez le modifier avec locationUpdateInterval. L'intervalle de mise à jour minimal accepté est de 5 secondes. L'intervalle de mise à jour maximal est de 60 secondes. Des mises à jour plus fréquentes peuvent ralentir les requêtes et les erreurs.

    Désactiver les notifications de position

    Votre application peut désactiver la mise à jour de la position pour un véhicule. Par exemple, à la fin de la rotation d'un conducteur, votre application peut définir locationTrackingEnabled sur NO.

      _vehicleReporter.locationTrackingEnabled = NO
    

    Gérer les erreurs update_mask

    Lorsque GMTDDeliveryVehicleReporter envoie une mise à jour du véhicule, une erreur update_mask peut se produire lorsque le masque est vide. Elle se produit généralement pour la première mise à jour après le démarrage. L'exemple suivant montre comment gérer cette erreur:

    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