API für Routenübersicht

Die Route Overview API ist ein Produkt für die Last Mile Fleet Solution, das auf dem DriverSDK basiert. Damit können Sie Routeninformationen für ein bestimmtes Fahrzeug abrufen, entweder einmalig oder fortlaufend mithilfe eines Listeners für Updates. Die Route Overview API unterstützt die folgenden Arten von Informationen:

  • Vollständiger Routenplan, einschließlich Haltestellenpositionen, Fahrtzeiten und Entfernungen
  • Der Polylinienpfad der Route zwischen den einzelnen Haltestellen.

In diesem Dokument werden die Integrationsschritte der API für Ihre Anwendung beschrieben.

Voraussetzungen

  • Sie müssen Ihre Android-Anwendung mit dem Alphakanal des DriverSDK Version 4.1.0 oder höher ausführen. Der Alphakanal ist verfügbar, wenn Sie transportation-driver-alpha für die Maven-Artefakt-ID verwenden.
  • Die API verarbeitet Routeninformationen, die von Fleet Engine über die Deliveries API bereitgestellt werden. Dies kann entweder über die APIs im DriverSDK (DeliveryDriverApi) oder direkt für Fleet Engine bereitgestellt werden.

Integrationsschritte

In diesem Abschnitt werden die grundlegenden Schritte zur Einbindung der Android-Treiber-App in die API beschrieben. In dieser Anleitung wird von folgenden Voraussetzungen ausgegangen:

  • Sie haben bereits eine Android-App, die bereits in das Driver SDK integriert ist.
  • Sie haben die DeliveryDriverApi in Ihrer Anwendung mit einem Kontextobjekt initialisiert, das Sie finden können.

Weitere Informationen finden Sie unter Erste Schritte mit dem Treiber-SDK für Android.

Schritt 0: Routen einrichten

Sie können diesen Schritt überspringen, wenn Sie Fleet Engine bereits eingerichtet haben und Haltestellen und Lieferaufgaben erstellen können.

Zum Laden der Haltestellen- und Aufgabeninformationen in Fleet Engine benötigen Sie ein Lieferfahrzeug, das einer gültigen Route zugewiesen ist. Das liegt daran, dass die Route Overview API gültige Routen benötigt, um Daten abzurufen. Gültige Routen bestehen aus einer Reihe von Wegpunkten und Haltestellen. Eine Haltestelle kann nur existieren, wenn ihr mindestens eine Aufgabe zugewiesen ist. Weitere Informationen finden Sie im Integrationsleitfaden für die Fleet Engine API.

Schritt 1 – API initialisieren

Nachdem Sie eine gültige Route mit den zugehörigen Haltestellen und Aufgaben erstellt haben, können Sie die Route Overview API initialisieren. Die Initialisierung stellt das Framework bereit, das für die Verbindung zwischen Fleet Engine und der API erforderlich ist. Die Route Summary API sollte mit demselben Kontextobjekt initialisiert werden, das Sie zum Initialisieren von DeliveryDriverApi im DriverSDK verwendet haben, da das Objekt auf dieselbe Fahrzeug-ID verweist, die zuvor im DriverContext-Objekt definiert wurde. Das folgende Beispiel zeigt, wie eine Instanz von RouteOverviewApi erstellt wird.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Schritt 2: Fahrzeug für Routenänderungen registrieren

Nachdem Sie die API initialisiert haben, können Sie das VehicleRouteOverview-Objekt verwenden, um mit den Funktionen der Routenübersicht zu interagieren. Dadurch kann Ihre Anwendung die Routeninformationen nutzen, die Sie während der Routeneinrichtung angegeben haben. Verwenden Sie den API-Ereignis-Listener, um Ereignisaktualisierungen und den Routenabruf zu vereinfachen.

Ein Routenänderungsereignis tritt ein, wenn der Pfad zu einer der dem Fahrzeug zugewiesenen Haltestellen aktualisiert, eine Haltestelle neu angeordnet oder die voraussichtliche Ankunftszeit von Fleet Engine aktualisiert wird.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Schritt 3 – API aktivieren

Jetzt können Sie Routeninformationen nutzen. Aktivieren Sie als Nächstes die API, damit sie auf Fahrzeugereignisse reagieren kann. Denken Sie daran, dass die API mit einem deaktivierten Zustand initialisiert wird, um eine unnötige Nutzung der Netzwerkbandbreite zu vermeiden.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Sie können diese Aktualisierungen jederzeit anhalten, indem Sie dieselbe Methode mit dem Wert false aufrufen.

Schritt 4: Route auf einer Google-Karte zeichnen

Sobald Sie eine Liste von RouteToVehicleStops erhalten haben, können Sie diese in Ihrer Anwendung verwenden. So lässt sich beispielsweise der Polylinienpfad der Route in einer Google Maps-Instanz zeichnen. Das folgende Code-Snippet zeigt ein Beispiel, bei dem die Polylinie der Route in der Kartenansicht gezeichnet wird und dabei Markierungen über den einzelnen Haltestellenpositionen hinzugefügt werden.

    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);
}

Screenshot mit einer Routenübersicht

Daraufhin wird eine Ansicht angezeigt, die dem Screenshot auf der rechten Seite ähnelt:

Schritt 5: Routen-Snapshot abrufen

Wenn Sie möchten, dass Ihre Anwendung einmalig einen Snapshot der aktuellen Routeninformationen abruft, können Sie diese Daten mit der folgenden Methode abrufen:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

Dies können Sie tun, anstatt Routenaktualisierungen über Ereignis-Listener zu abonnieren.

Schritt 6 – Bereinigen

Wenn Ihre Anwendung die Funktion „Routenübersicht“ nicht mehr benötigt, sollten Sie prüfen, ob Sie sie bereinigt haben. Durch die Bereinigung werden unnötige Arbeitsspeicher-, Verarbeitungs- und Netzwerknutzungen in Ihrer Anwendung vermieden.

Einen bestimmten Event-Listener entfernen

Sie sollten einen Event-Listener entfernen, wenn ein bestimmter Listener nicht mehr erforderlich ist.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Alle Event-Listener löschen

Im Rahmen der Bereinigung können Sie alle gleichzeitig registrierten Ereignis-Listener entfernen.

vehicleRouteOverview.clearEventListeners();

Route Overview API-Instanz löschen

Wenn die Routenübersicht nicht mehr benötigt wird oder sich die ID des verfolgten Fahrzeugs geändert hat, können Sie diese API aufrufen, um interne Verweise zu löschen.

vehicleRouteOverview.clearInstance();