API Route Overview

Ce produit ou cette fonctionnalité est en phase expérimentale (pré-DG). La prise en charge 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.

Important :L'API Route Overview n'est actuellement disponible que sur Android.

L'API Route Overview est un produit de la solution Last Mile Fleet, basé sur le DriverSDK. Elle vous permet de récupérer les informations sur l'itinéraire d'un véhicule donné, soit de manière unique, soit en continu à l'aide d'un écouteur pour les mises à jour. L'API Routes Overview accepte les types d'informations suivants:

• le 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 de l'itinéraire entre chaque arrêt.

Ce document décrit les étapes d'intégration à l'API pour votre application.

Prérequis

• Vous devez exécuter votre application Android à l'aide de la version alpha du DriverSDK version 4.1.0 ou version ultérieure. La version alpha est disponible en utilisant transportation-driver-alpha comme ID d'artefact Maven.
• L'API utilise les informations sur les itinéraires fournies par Fleet Engine via l'API Deliveries. Il peut être fourni via les API du DriverSDK (DeliveryDriverApi) ou directement à Fleet Engine.

Étapes d'intégration

Cette section décrit la procédure de base à suivre pour intégrer votre application de pilote Android à l'API. Ces instructions reposent sur les hypothèses suivantes:

• Vous disposez d'une application Android 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 la page Premiers pas avec le SDK Driver pour Android.

Étape 0 : Configurer la route

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 l'arrêt et la tâche dans Fleet Engine, vous devez attribuer un véhicule de livraison à un itinéraire valide. En effet, l'API Route Overview nécessite des routes valides pour extraire les 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. Pour en savoir plus, consultez le guide d'intégration de l'API Fleet Engine.

Étape 1 : Initialiser l'API

Une fois que vous avez établi un itinéraire valide avec des arrêts et des 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 le 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);
}

Remarque :Lorsque vous initialisez l'API Route Overview, elle est automatiquement désactivée pour éviter de consommer de la bande passante inutile pendant la configuration.

Étape 2 : Enregistrez 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 des itinéraires. Cela permet à votre application d'utiliser les informations de routage que vous avez fournies lors de la configuration de la route. Utilisez l'écouteur d'événements de l'API pour faciliter les mises à jour d'événements et la récupération des routes.

Un événement de modification d'itinéraire se produit chaque fois que le tracé vers l'un des arrêts attribués au véhicule est mis à jour, qu'un arrêt est réorganisé ou lorsque 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 l'itinéraire, vous devez activer l'API pour lui permettre de répondre aux événements du véhicule. N'oubliez pas que l'API est initialisée dans un état désactivé pour éviter toute 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 de false.

Étape 4 : Tracez l'itinéraire sur une carte Google Maps

Une fois que vous avez obtenu la liste des RouteToVehicleStop, vous pouvez l'utiliser dans votre application. Par exemple, vous pouvez dessiner le tracé de la polyligne de l'itinéraire dans une instance Google Maps. L'extrait de code suivant montre un exemple qui trace la polyligne d'itinéraire sur la carte et ajoute des repères au-dessus de chaque 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 une vue semblable à la capture d'écran ci-contre:

É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 routage actuelles, 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 du routage via les écouteurs d'événements.

Étape 6 : Effectuer un nettoyage

Si votre application n'a plus besoin de la fonctionnalité d'aperçu des itinéraires, vous devez vous assurer que vous avez effectué le nettoyage. Un nettoyage permet d'éviter toute consommation inutile de mémoire, de traitement et de réseau 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 tous les différents écouteurs d'événements enregistrés en même temps.

vehicleRouteOverview.clearEventListeners();

Effacer l'instance de l'API Route Overview

Chaque fois que l'aperçu de l'itinéraire n'est plus nécessaire ou que l'identifiant du véhicule suivi a changé, vous pouvez appeler cette API pour effacer les références internes.

vehicleRouteOverview.clearInstance();