L'API Route Overview est un produit de solution Last Mile Fleet basé sur le DriverSDK. Vous pouvez ainsi récupérer les informations sur l'itinéraire d'un véhicule donné, soit en tant que récupération unique, soit en continu à l'aide d'un écouteur pour les mises à jour. L'API Route Overview accepte les types d'informations suivants:
- Plan complet de l'itinéraire, y compris l'emplacement des arrêts des véhicules, les temps de trajet et les distances
- Trajet de la polyligne d'itinéraire entre chaque arrêt.
Ce document décrit les étapes d'intégration à l'API pour votre application.
Conditions préalables
- Vous devez exécuter votre application Android à l'aide du canal alpha de DriverSDK 4.1.0 ou version ultérieure. Le canal alpha est disponible en utilisant
transportation-driver-alpha
comme ID de l'artefact Maven. - L'API utilise les informations de routage fournies par Fleet Engine via l'API Deliveries. Ces informations peuvent être fournies via les API sur DriverSDK (
DeliveryDriverApi
) ou directement à Fleet Engine.
Étapes d'intégration
Cette section décrit les étapes de base nécessaires pour intégrer votre application pilote Android à l'API. Ces instructions reposent sur les hypothèses suivantes:
- Vous disposez d'une application Android existante qui est déjà intégrée au SDK Driver
- Vous avez initialisé
DeliveryDriverApi
dans votre application avec un objet de contexte que vous pouvez trouver
Pour en savoir plus, consultez Premiers pas avec le SDK Driver pour Android.
Étape 0 : Configurer le routage
Vous pouvez ignorer cette étape si vous avez déjà configuré Fleet Engine et que vous pouvez créer des arrêts de véhicule et des tâches de livraison.
Pour charger les informations sur les arrêts et les tâches dans Fleet Engine, vous devez disposer d'un véhicule de livraison affecté à un itinéraire valide. En effet, l'API Route Overview a besoin d'itinéraires valides pour récupérer des données. Les itinéraires valides sont composés d'une série de points de cheminement et d'arrêts. Un arrêt ne peut exister que s'il est associé à au moins une tâche. Consultez le guide d'intégration de l'API Fleet Engine pour plus d'informations.
Étape 1 : Initialiser l'API
Une fois que vous avez établi un itinéraire valide avec les arrêts et les tâches associés, vous pouvez initialiser l'API Route Overview. L'initialisation fournit le framework nécessaire à la connexion entre Fleet Engine et l'API. L'API Route Overview doit être initialisée avec le même objet de contexte que celui utilisé pour initialiser DeliveryDriverApi
dans DriverSDK, car l'objet fait référence au même ID de véhicule défini précédemment dans votre objet DriverContext
. L'exemple suivant montre comment créer une instance de RouteOverviewApi
.
RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
api = RouteOverviewApi.createInstance(context);
}
Étape 2 : Enregistrer le véhicule pour les événements de modification d'itinéraire
Maintenant que vous avez initialisé l'API, vous pouvez utiliser l'objet VehicleRouteOverview
pour interagir avec les fonctionnalités de présentation de l'itinéraire. Cela permet à votre application d'utiliser les informations de routage que vous avez fournies lors de la configuration du routage.
Utilisez l'écouteur d'événements de l'API pour faciliter la mise à jour des événements et la récupération des routes.
Un événement de modification d'itinéraire se produit chaque fois que le chemin vers l'un des arrêts attribués au véhicule est mis à jour, qu'un arrêt est réorganisé ou que Fleet Engine met à jour les informations sur l'heure d'arrivée prévue.
vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
// handle route update events
});
Étape 3 : Activez l'API
Maintenant que vous êtes prêt à utiliser les informations sur les itinéraires, vous devez activer l'API pour l'autoriser à répondre aux événements de véhicule. N'oubliez pas que l'API est initialisée dans un état désactivé afin d'éviter une consommation inutile de bande passante réseau.
vehicleRouteOverview.setRouteOverviewEnabled(true);
Vous pouvez suspendre ces mises à jour à tout moment en appelant la même méthode avec la valeur false
.
Étape 4 : Tracez l'itinéraire sur une carte Google Maps
Une fois que vous avez obtenu la liste des éléments RouteToVehicleStop
, vous pouvez l'utiliser dans votre application. Par exemple, vous pouvez dessiner le tracé d'une polyligne d'itinéraire dans une instance de carte Google Maps. L'extrait de code suivant montre un exemple qui dessine la polyligne d'itinéraire sur la vue plan et ajoute des repères au-dessus de chaque emplacement d'arrêt.
GoogleMap googleMap = … // Instance of the Map view you are using
ImmutableList<RouteToVehicleStop> route = event.newRoute();
PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
for (RouteToVehicleStop stop : route) {
routePolyline.addAll(stop.path());
MarkerOptions marker =
new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
googleMap.addMarker(marker);
}
googleMap.addPolyline(routePolyline);
}
Vous obtenez un affichage semblable à la capture d'écran de droite:
Étape 5 : Obtenez un instantané de route
Si vous souhaitez que votre application émette un appel unique pour récupérer un instantané des informations de l'itinéraire actuel, vous pouvez utiliser la méthode suivante pour récupérer ces données:
ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();
Vous pouvez le faire au lieu de vous abonner aux mises à jour des routes via des écouteurs d'événements.
Étape 6 : Effectuez un nettoyage
Si votre application n'a plus besoin de la fonctionnalité d'aperçu des routes, assurez-vous d'avoir effectué un nettoyage. Ce nettoyage évite des opérations de mémoire, de traitement et de consommation réseau inutiles dans votre application.
Supprimer un écouteur d'événements spécifique
Vous devez supprimer un écouteur d'événements lorsqu'un écouteur spécifique n'est plus nécessaire.
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
Effacer tous les écouteurs d'événements
Dans le cadre de votre routine de nettoyage, vous pouvez supprimer simultanément tous les différents écouteurs d'événements enregistrés.
vehicleRouteOverview.clearEventListeners();
Effacer l'instance de l'API Route Overview
Chaque fois que vous n'avez plus besoin de la présentation de l'itinéraire ou que l'identifiant du véhicule suivi a changé, vous pouvez appeler cette API pour effacer les références internes.
vehicleRouteOverview.clearInstance();