Premiers pas avec le SDK Driver pour Android

Remarque:La fonctionnalité LMFS propose deux modèles de sécurité pour le SDK Driver: Approuvé et Approuvé. Les deux modèles de sécurité définissent comment l'application de conducteur peut fournir des mises à jour de données sur les véhicules à Fleet Engine. Le modèle de sécurité non approuvé fournit une couche supplémentaire de vérification des données depuis l'application de pilote. Cela signifie que, dans le modèle non approuvé, l'application de pilote ne peut envoyer que des mises à jour de position du véhicule directement à Fleet Engine. Toutes les autres mises à jour des données du véhicule provenant d'une application de conducteur non approuvée doivent être envoyées au backend du client, qui transmet la date à Fleet Engine.

Le modèle de sécurité approuvé permet à l'application de pilote d'envoyer des mises à jour de données sur les véhicules directement à Fleet Engine, sans recourir à un service intermédiaire. Cela inclut la création et la mise à jour de véhicules, de tâches et d'arrêts.

Enfin, la fonctionnalité du modèle non approuvé est en disponibilité générale, tandis que celle du modèle de pilote de confiance est en version preview. Pour en savoir plus, consultez la page Intégrer l'API de livraison dans la documentation de Fleet Engine.

Configuration système minimale requise

L'appareil mobile doit être équipé d'Android 5.0 (niveau d'API 21) ou version 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.

Le SDK Driver pour Android est publié dans un dépôt Maven Artifact Registry. Le dépôt inclut les fichiers .pom du modèle d'objet de projet du SDK et les Javadocs hors connexion.

Obtenir l'accès

Si vous êtes un client Google Workspace, créez un groupe Workspace tel que [e-mail] lors de l'intégration et fournissez le nom à Google. Il s'agit de l'approche recommandée. Votre groupe Workspace sera alors ajouté à une liste d'autorisation qui accorde l'accès au dépôt Maven gmp-artifacts/transportation. 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.

Remarque :Les groupes Workspace sont différents de Google Groupes (se terminant par @googlegroups.com). Seuls les groupes Workspace sont compatibles.

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 du groupe Workspace.

Configuration

Configurez Maven ou Gradle pour détecter automatiquement les identifiants de l'utilisateur ou du service.

Gradle

Ajoutez le code suivant au fichier build.gradle de votre module d'application, et non au fichier build.gradle du module racine du projet:

  plugins {
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
  }
  repositories {
    maven {
      url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
  }

Remarque :Si vous utilisez Android Studio, cliquez sur l'action Synchroniser le projet avec les fichiers Gradle pour tester votre configuration.

Maven

Ajoutez les éléments suivants à votre pom.xml :

  <repositories>
    <repository>
      <id>gmp-artifacts</id>
      <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
  </repositories>
  <build>
    <extensions>
      <extension>
        <groupId>com.google.cloud.artifactregistry</groupId>
        <artifactId>artifactregistry-maven-wagon</artifactId>
        <version>2.1.0</version>
      </extension>
    </extensions>
  </build>

Pour en savoir plus sur la vérification des accès, consultez la page Gérer les packages Java.

Configuration du projet

Pour utiliser le SDK Driver, votre application doit cibler minSdkVersion 21 ou version ultérieure. Pour en savoir plus, consultez Notes de version.

Pour exécuter une application créée avec le SDK Driver, les services Google Play doivent être installés sur l'appareil Android.

Configurer votre projet de développement

Pour configurer votre projet de développement et obtenir une clé API pour le projet dans la console Google Cloud, procédez comme suit:

1. Créez un projet Google Cloud Console ou sélectionnez un projet existant à utiliser avec le SDK Driver. Attendez quelques minutes que le nouveau projet soit visible dans la console Google Cloud.

2. Pour que vous puissiez exécuter l'application de démonstration, votre projet doit avoir accès au SDK Maps pour Android. Dans Google Cloud Console, sélectionnez API et services > Bibliothèque, puis recherchez et activez le SDK Maps pour Android.

3. Obtenez une clé API pour le projet en sélectionnant API et services > Identifiants > Créer des identifiants > Clé API. Pour savoir comment obtenir une clé API, consultez Obtenir une clé API.

Ajouter le SDK Driver à votre application

Le SDK Driver est disponible via un dépôt Maven privé. Le dépôt inclut les fichiers .pom du modèle d'objet de projet du SDK et les documents Javadocs. Pour ajouter le SDK Driver à votre application:

1. Configurez votre environnement pour accéder au dépôt Maven de l'hôte, comme décrit dans la section Configuration.

2. Ajoutez la dépendance suivante à votre configuration Gradle ou Maven, en remplaçant l'espace réservé VERSION_NUMBER par la version souhaitée du pilote du pilote.

   Gradle

   Ajoutez les éléments suivants à votre build.gradle :

   dependencies {
     ...
     implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:[VERSION_NUMBER]'
   }
   

   Maven

   Ajoutez les éléments suivants à votre pom.xml :

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.mapsplatform.transportation.driver</groupId>
       <artifactId>transportation-driver</artifactId>
       <version>[VERSION_NUMBER]</version>
     </dependency>
   </dependencies>
   

Ajouter la clé API à votre application

Une fois que vous avez ajouté le SDK Driver à votre application, ajoutez la clé API à votre application. Vous devez utiliser la clé API du projet obtenue lors de la configuration de votre projet de développement.

Cette section explique comment stocker votre clé API pour qu'elle puisse être référencée de manière plus sécurisée par votre application. Vous ne devez pas l'enregistrer dans votre système de contrôle des versions. Il doit être stocké dans le fichier local.properties, situé dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier local.properties, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, utilisez le plug-in Secrets Gradle pour Android. Suivez cette procédure pour installer le plug-in Secrets Gradle et stocker votre clé API de manière sécurisée.

1. Ouvrez votre fichier build.gradle au niveau racine et ajoutez le code suivant à l'élément dependencies sous buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
       }
   }
   

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
       }
   }
   

2. Ouvrez le fichier build.gradle au niveau de l'application et ajoutez le code suivant à l'élément plugins.

   Groovy

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   

   Kotlin

   id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   

3. Synchronisez votre projet avec Gradle.

4. Ouvrez local.properties dans votre répertoire au niveau du projet, puis ajoutez le code suivant. Veillez à remplacer YOUR_API_KEY par votre clé API.

   MAPS_API_KEY=YOUR_API_KEY
   

5. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY et mettez à jour l'attribut android:value comme suit:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
   

L'exemple suivant présente un fichier manifeste complet pour un exemple d'application:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.driverapidemo" >
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/_AppTheme" >

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${MAPS_API_KEY}" />

        <activity android:name=".MainActivity" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Remarque :Pour une expérience de navigation optimale, l'utilisateur doit accorder les autorisations android.permission.ACCESS_COARSE_LOCATION et android.permission.ACCESS_FINE_LOCATION. Veillez à demander les deux au moment de l'exécution dans l'application.

Inclure les attributions requises dans votre application

Si vous utilisez le SDK Driver dans votre application, vous devez inclure un texte d'attribution et des licences Open Source dans la section dédiée aux mentions légales de votre application. Il est préférable d'inclure les attributions en tant qu'élément de menu indépendant ou dans un élément de menu À propos.

Le texte d'attribution et les licences Open Source requis se trouvent dans le fichier ZIP du SDK Driver:

• NOTICE.txt
• LICENSES.txt

Dépendances

Le SDK Driver utilise gRPC pour communiquer avec le serveur Fleet Engine. Si vous n'intégrez pas déjà gRPC, vous devrez peut-être déclarer les dépendances suivantes:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

Sans ces dépendances, le SDK Driver rencontrera des erreurs au moment de l'exécution lors de la tentative de communication avec le serveur Fleet Engine.

Si vous utilisez ProGuard pour optimiser vos compilations, vous devrez peut-être ajouter les lignes suivantes à votre fichier de configuration ProGuard:

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

Le niveau d'API minimal accepté est 21.

Initialiser le SDK

Un ID de fournisseur (généralement l'ID de projet Google Cloud) est nécessaire pour initialiser l'objet DriverContext. Pour en savoir plus sur la configuration du projet Google Cloud, consultez Authentification et autorisation.

Avant d'utiliser le SDK Driver, vous devez d'abord initialiser le SDK Navigation. Pour initialiser le SDK, procédez comme suit :

1. Obtenez un objet Navigator à partir de NavigationApi.

   NavigationApi.getNavigator(
       this, // Activity
       new NavigationApi.NavigatorListener() {
         @Override
         public void onNavigatorReady(Navigator navigator) {
           // Keep a reference to the Navigator (used to configure and start nav)
           this.navigator = navigator;
         }
       }
   );
   

2. Créez un objet DriverContext en remplissant les champs obligatoires.

   DriverContext driverContext = DriverContext.builder(application)
       .setProviderId(providerId)
       .setVehicleId(vehicleId)
       .setAuthTokenFactory(authTokenFactory)
       .setNavigator(navigator)
       .setRoadSnappedLocationProvider(
           NavigationApi.getRoadSnappedLocationProvider(application))
       .build();
   

3. Utilisez l'objet DriverContext pour initialiser *DriverApi.

   DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
   

4. Obtenez le DeliveryVehicleReporter auprès de l'objet API. (DeliveryVehicleReporter étend NavigationVehicleReporter).

   DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
   

Authentification avec AuthTokenFactory

Lorsque le SDK Driver génère des mises à jour de la position, il doit les envoyer au serveur Fleet Engine. Pour authentifier ces requêtes, le SDK Driver appelle une instance fournie par l'appelant de AuthTokenFactory. La fabrique est chargée de générer des jetons d'authentification au moment de la mise à jour de l'établissement.

La façon exacte dont les jetons sont générés dépend de la situation de chaque développeur. Cependant, l'implémentation devra probablement:

• récupérer un jeton d'authentification (éventuellement au format JSON) à partir d'un serveur HTTPS.
• analyser et mettre en cache le jeton
• actualiser 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.

Voici une implémentation de squelette de AuthTokenFactory:

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // initially null
  private long expiryTimeMs = 0;

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  @Override
  public String getToken(AuthTokenContext authTokenContext) {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(vehicleId);
    }
    if (ServiceType.VEHICLE.equals(authTokenContext.getServiceType)) {
      return vehicleServiceToken;
    } else {
      throw new RuntimeException("Unsupported ServiceType: " + authTokenContext.getServiceType());
    }
  }

  private void fetchNewToken(String vehicleId) {
    String url = "https://yourauthserver.example/token/" + vehicleId;

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      vehicleServiceToken = obj.get("VehicleServiceToken").getAsString();
      expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      // The expiry time could be an hour from now, but just to try and avoid
      // passing expired tokens, we subtract 10 minutes from that time.
      expiryTimeMs -= 10 * 60 * 1000;
    } catch (IOException e) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw new RuntimeException("Could not get auth token", e);
    }
  }
}

Cette implémentation particulière utilise le client HTTP Java intégré pour récupérer un jeton au format JSON à partir du serveur d'authentification du développeur. Le jeton est enregistré pour être réutilisé. Le jeton est récupéré à nouveau dans les 10 minutes précédant son délai d'expiration.

Votre implémentation peut effectuer différentes opérations, par exemple utiliser un thread en arrière-plan pour actualiser les jetons.

Les exceptions dans AuthTokenFactory seront traitées comme temporaires, sauf si elles se produisent de manière répétée. Après plusieurs tentatives, le SDK Driver supposera que l'erreur est définitive et cessera d'essayer d'envoyer des mises à jour.

Rapports d'état et d'erreur avec StatusListener

Étant donné que le SDK Driver effectue des actions en arrière-plan, utilisez StatusListener pour déclencher des notifications lorsque certains événements se produisent, tels que des erreurs, des avertissements ou des messages de débogage. Les erreurs peuvent être de nature temporaire (comme BACKEND_CONNECTIVITY_ERROR) ou entraîner l'arrêt définitif des mises à jour de la position (comme VEHICLE_NOT_FOUND), ce qui indique une erreur de configuration.

Vous pouvez ajouter une implémentation StatusListener facultative comme suit:

class MyStatusListener implements StatusListener {
  /** Called when background status is updated, during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

Remarques sur SSL/TLS

En interne, l'implémentation du SDK du pilote utilise SSL/TLS pour communiquer de manière sécurisée avec le serveur Fleet Engine. Les anciennes versions d'Android (API 21 ou version antérieure) peuvent nécessiter un correctif SecurityProvider pour pouvoir communiquer avec le serveur. Pour en savoir plus sur l'utilisation de SSL dans Android, consultez cet article. Il contient également des exemples de code pour appliquer des correctifs au fournisseur de sécurité.

Activer les notifications de position

Une fois que vous disposez d'une instance *VehicleReporter, vous pouvez facilement activer les mises à jour de la position:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Les mises à jour de la position géographique sont envoyées à intervalles réguliers, si possible. Chaque mise à jour de la position indique également que le véhicule est en ligne.

Par défaut, l'intervalle du rapport est de 10 secondes. L'intervalle de reporting peut être modifié avec reporter.setLocationReportingInterval(long, TimeUnit). L'intervalle de mise à jour minimal accepté est de 5 secondes. Des mises à jour plus fréquentes peuvent ralentir les requêtes et les erreurs.

Désactivation des notifications de position

Une fois la journée de travail du chauffeur terminée, vous pouvez arrêter les mises à jour de la position en appelant DeliveryVehicleReporter.disableLocationTracking.

Cas d'utilisation de modèles de confiance

Ce produit ou cette fonctionnalité est en phase de preview (pré-DG). La compatibilité des fonctionnalités et produits pré-DG peut être limitée, et il se peut que les modifications apportées à ces fonctionnalités ou produits ne soient pas compatibles avec d'autres versions pré-DG. Les offres en pré-DG sont couvertes par les Conditions spécifiques du service Google Maps Platform. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette section explique comment utiliser le SDK Driver pour implémenter des cas d'utilisation courants lorsque vous utilisez le modèle de confiance.

Créer un véhicule

Vous pouvez créer un véhicule à partir du SDK Driver.

Avant de créer un véhicule, veillez à initialiser l'API Delivery Driver. L'ID du véhicule doit être créé avec l'ID du véhicule et du fournisseur utilisé lors de l'initialisation du SDK du pilote. Créez ensuite le véhicule comme indiqué dans l'exemple suivant:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

Créer une tâche de retrait en livraison

Vous pouvez créer une tâche de retrait en livraison à partir du SDK Driver.

Avant de créer une tâche, veillez à initialiser l'API Delivery Driver. La tâche doit être créée à l'aide de l'ID de fournisseur spécifié lors de l'initialisation du SDK du pilote. Créez ensuite la tâche de retrait comme indiqué dans l'exemple suivant. Pour en savoir plus sur les ID de tâche, consultez les exemples d'ID de tâche.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_PICKUP)
   .build();

try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Créer une tâche de livraison

Vous pouvez créer une tâche de livraison à partir du SDK Driver.

Avant de créer une tâche, veillez à initialiser l'API Delivery Driver. Créez ensuite la tâche de livraison comme indiqué dans l'exemple suivant. Pour en savoir plus sur les ID de tâche, consultez les exemples d'ID de tâche.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Indisponibilité planifiée

Vous pouvez créer une tâche indiquant une indisponibilité (par exemple, pour une pause ou le ravitaillement d'un véhicule) à partir du SDK Driver. Une tâche d'indisponibilité planifiée ne doit pas inclure d'ID de suivi. Vous pouvez éventuellement indiquer un lieu.

Avant de créer une tâche, veillez à initialiser l'API Delivery Driver. Créez ensuite la tâche d'indisponibilité comme indiqué dans l'exemple suivant. Pour en savoir plus sur les ID de tâche, consultez les exemples d'ID de tâche.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
   .setTaskType(TaskType.UNAVAILABLE)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Arrêts planifiés

Vous pouvez créer une tâche d'arrêt planifié à partir du SDK Driver. Une tâche d'arrêt planifié peut ne pas inclure d'ID de suivi.

Avant de créer une tâche, veillez à initialiser l'API Delivery Driver. Créez ensuite la tâche d'arrêt planifié, comme indiqué dans l'exemple suivant. Pour en savoir plus sur les ID de tâche, consultez les exemples d'ID de tâche.

static final String TASK_ID = "task-8241890"; //  Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Modifier l'ordre des tâches

Vous pouvez modifier l'ordre d'exécution des tâches attribuées à un véhicule à partir du SDK Driver.

La mise à jour de l'ordre des tâches attribue également des tâches à un véhicule si elles n'ont pas été précédemment attribuées à un véhicule. Elle ferme également les tâches précédemment attribuées à un véhicule et qui n'ont pas été mises à jour dans l'ordre. L'attribution d'une tâche à un autre véhicule si elle a déjà été attribuée à un autre véhicule génère une erreur. Avant d'attribuer une tâche au nouveau véhicule, fermez-la, puis créez-en une autre.

Vous pouvez modifier l'ordre des tâches à tout moment.

Avant de modifier l'ordre des tâches pour un véhicule, assurez-vous qu'il a déjà été créé dans Fleet Engine. Ensuite, mettez à jour l'ordre des tâches pour le véhicule, comme indiqué dans l'exemple suivant.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
try {
   List<VehicleStop> stops = reporter.setVehicleStops(
     ImmutableList.of(
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.ARRIVED)
             .setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
             .setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
             .build(),
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
             .setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
             .setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
             .build(),
         VehicleStop.builder()
             .setVehicleStopState(VehicleStopState.NEW)
             .setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
             .setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
             .build())).get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
   // errors.
}

Une exception peut se produire et empêcher l'actualisation de l'état interne du SDK du pilote. Si cela se produit, résolvez le problème, puis appelez de nouveau setVehicleStops jusqu'à ce que l'appel aboutisse.

Exemples de problèmes potentiels:

• Les véhicules spécifiés ne suivent pas un schéma valide. Seul le premier VehicleStop peut se trouver dans l'un des VehicleStopStates: NEW, ENROUTE ou ARRIVED. Les véhicules à l'arrêt actuels doivent être dans le VehicleStopState.

• Les tâches n'existent pas ou sont associées à un autre véhicule.

• Le véhicule n'existe pas.

Le véhicule est en route pour le prochain arrêt

Fleet Engine doit être notifié lorsqu'un véhicule part d'un arrêt et commence le trajet. Vous pouvez informer Fleet Engine à partir du SDK Driver.

Avant d'informer Fleet Engine qu'un véhicule a décollé d'un arrêt, assurez-vous qu'il a été créé et défini. Informez ensuite Fleet Engine du départ du véhicule, comme indiqué dans l'exemple suivant.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.

navigator.setDestination(vehicleStop.getWaypoint());
try {
   List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ENROUTE state.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

Une exception peut se produire et empêcher l'actualisation de l'état interne du SDK du pilote. Si cela se produit, résolvez le problème, puis appelez enrouteToNextStop à nouveau jusqu'à ce que l'opération réussisse.

Exemples de problèmes potentiels:

• VehicleStops n'a pas été défini dans le SDK du pilote.

Le véhicule arrive à un arrêt

Fleet Engine doit être notifié lorsqu'un véhicule arrive à un arrêt. Vous pouvez en informer Fleet Engine à partir du SDK Driver.

Avant d'informer Fleet Engine qu'un véhicule est arrivé à un arrêt, assurez-vous qu'il a été défini. Informez ensuite Fleet Engine de l'arrivée du véhicule à l'arrêt, comme illustré dans l'exemple suivant.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.

try {
   List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ARRIVED state.
   navigator.clearDestinations();
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

Une exception peut se produire et empêcher l'actualisation de l'état interne du SDK du pilote. Si cela se produit, résolvez le problème, puis appelez arrivedAtStop à nouveau jusqu'à ce que l'opération réussisse.

Exemples de problèmes potentiels:

• VehicleStops n'a pas été défini dans le SDK du pilote.

Le véhicule effectue un arrêt

Fleet Engine doit être notifié lorsqu'un véhicule effectue un arrêt. Toutes les tâches associées à l'arrêt sont alors définies sur "FERMÉES". Vous pouvez informer Fleet Engine à partir du SDK Driver.

Informez Fleet Engine que le véhicule a terminé son VehicleStop, comme illustré dans l'exemple suivant.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// After completing the tasks at the VehicleStop, remove it from the
// the current list of VehicleStops.

try {
   List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
   // Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
   // Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

Une exception peut se produire et empêcher l'actualisation de l'état interne du SDK du pilote. Si cela se produit, résolvez le problème, puis appelez completedStop à nouveau jusqu'à ce que l'opération réussisse.

Exemples de problèmes potentiels:

• VehicleStops n'a pas été défini dans le SDK du pilote.

Fermer une tâche

Pour fermer une tâche attribuée à un véhicule, informez-en Fleet Engine que le véhicule a terminé l'arrêt où la tâche a lieu ou supprimez-la de la liste des arrêts de véhicules. Pour ce faire, vous pouvez définir la liste des arrêts de véhicules restants de la même manière que lorsque vous mettez à jour l'ordre des tâches d'un véhicule.

Si une tâche n'a pas encore été attribuée à un véhicule et qu'elle doit être fermée, définissez l'état de la tâche sur FERMÉE. Toutefois, vous ne pouvez pas rouvrir une tâche fermée.

La fermeture d'une tâche n'indique pas la réussite ni l'échec. Il indique que la tâche n'est plus considérée comme en cours. Pour le suivi des livraisons, il est important d'indiquer le résultat réel d'une tâche afin qu'un résultat de livraison puisse être affiché.

Une tâche doit être attribuée à un véhicule pour pouvoir la fermer en utilisant le SDK Driver. Pour fermer une tâche attribuée à un véhicule, informez Fleet Engine que le véhicule a terminé l'arrêt où la tâche a lieu.

Vous pouvez également mettre à jour l'ordre des tâches du véhicule auquel la tâche est attribuée, puis supprimer la tâche souhaitée de la liste des arrêts.

Définir le résultat de la tâche et son emplacement

La fermeture d'une tâche n'indique pas la réussite ni l'échec. Il indique que la tâche n'est plus considérée comme en cours. Pour le suivi des livraisons, il est important d'indiquer le résultat réel d'une tâche afin qu'un résultat de livraison puisse être affiché et que la facturation des services soit appropriée. Une fois défini, vous ne pouvez plus modifier le résultat de la tâche. Toutefois, vous pouvez modifier l'heure et le lieu de résultat de la tâche après l'avoir définie.

Le résultat des tâches à l'état FERMÉE peut être défini sur SUCCEEDED ou FAILED. Fleet Engine ne facture que les tâches de livraison à l'état SUCCEEDED.

Lorsque vous marquez le résultat d'une tâche, Fleet Engine renseigne automatiquement l'emplacement du résultat de la tâche avec la dernière position connue du véhicule. Vous pouvez ignorer ce comportement.

L'exemple suivant vous montre comment utiliser le SDK Driver pour définir le résultat et l'horodatage d'une tâche. Vous ne pouvez pas définir l'emplacement du résultat de la tâche à l'aide du SDK Driver.

static final String TASK_ID = "task-8241890";

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();

// Updating an existing DeliveryTask which is already CLOSED. Manually
// setting TaskOutcomeLocation with Driver SDK is not supported at this time.
UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
    .setTaskOutcome(TaskOutcome.SUCCEEDED)
    .setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
    .build();

try {
   DeliveryTask updatedTask = taskManager.updateTask(req);
   // Handle UpdateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle UpdateTaskRequest error.
}

Rechercher un véhicule

Vous pouvez rechercher un véhicule à partir du SDK Driver. Avant de rechercher un véhicule, veillez à initialiser l'API Delivery Driver. Vous pouvez ensuite rechercher le véhicule comme illustré dans l'exemple suivant.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
   DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
   // Handle GetVehicleRequest DeliveryVehicle response.
} catch (Exception e)  {
   // Handle GetVehicleRequest error.
}

DeliveryVehicleManager peut uniquement rechercher le DeliveryVehicle de l'ID de véhicule fourni lors de l'initialisation de l'API Delivery Driver.