Route Overview API to usługa typu Last Mile Fleet Solution utworzona w oparciu o pakiet DriverSDK. Dzięki niej możesz pobierać informacje o trasie danego pojazdu, zarówno jednorazowo, jak i w sposób ciągły, korzystając z detektora aktualizacji. Interfejs Route Overview API obsługuje te rodzaje informacji:
- Pełny plan trasy, z uwzględnieniem przystanków pojazdów, czasu podróży i odległości
- Ścieżka linii łamanej trasy między każdym przystankiem.
W tym dokumencie opisujemy kroki integracji z interfejsem API w Twojej aplikacji.
Wymagania wstępne
- Musisz używać aplikacji na Androida przy użyciu kanału alfa pakietu DriverSDK w wersji 4.1.0 lub nowszej. Kanał alfa jest dostępny przy użyciu parametru
transportation-driver-alphajako identyfikator artefaktu Maven. - Interfejs API wykorzystuje informacje o trasach dostarczone przez Fleet Engine za pomocą interfejsu Deliveries API. Można to zrobić za pomocą interfejsów API w pakiecie DriverSDK (
DeliveryDriverApi) lub bezpośrednio do Fleet Engine.
Etapy integracji
W tej sekcji omawiamy podstawowe kroki wymagane do integracji aplikacji sterowników na Androida z interfejsem API. Przy tych instrukcjach przyjęto takie założenia:
- Masz już aplikację na Androida zintegrowaną z pakietem Driver SDK
- inicjujesz
DeliveryDriverApiw aplikacji za pomocą obiektu kontekstu,
Więcej informacji znajdziesz w artykule Pierwsze kroki z pakietem Driver SDK na Androida.
Krok 0. Konfiguracja trasy
Możesz pominąć ten krok, jeśli masz już skonfigurowaną usługę Fleet Engine i możesz tworzyć zadania związane z zatrzymaniem pojazdów i dostawą.
Aby wczytać informacje o zatrzymaniach i zadaniach do Fleet Engine, potrzebujesz pojazdu dostawy przypisanego do prawidłowej trasy. Dzieje się tak, ponieważ do pobierania danych interfejs Route Overview API wymaga prawidłowych tras. Prawidłowe trasy składają się z serii punktów pośrednich i przystanków, a przystanek może istnieć tylko wtedy, gdy jest z nim powiązane co najmniej jedno zadanie. Więcej informacji znajdziesz w przewodniku po integracji interfejsu Fleet Engine API.
Krok 1. Zainicjuj interfejs API
Po ustaleniu prawidłowej trasy z powiązanymi przystankami i zadaniami możesz zainicjować interfejs Route Overview API. Inicjowanie zapewnia platformę niezbędną do połączenia między Fleet Engine a interfejsem API. Interfejs Route Overview API powinien zostać zainicjowany tym samym obiektem kontekstu, którego użyto do zainicjowania DeliveryDriverApi w pakiecie DriverSDK, ponieważ obiekt odwołuje się do tego samego identyfikatora pojazdu, który został zdefiniowany wcześniej w obiekcie DriverContext. Poniższy przykład pokazuje, jak utworzyć instancję RouteOverviewApi.
RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
api = RouteOverviewApi.createInstance(context);
}
Krok 2. Zarejestruj pojazd na potrzeby zdarzeń zmiany trasy
Po zainicjowaniu interfejsu API możesz używać obiektu VehicleRouteOverview, aby korzystać z funkcji przeglądu tras. Dzięki temu aplikacja może korzystać z informacji o trasie podanych podczas konfiguracji trasy.
Używaj detektora zdarzeń interfejsu API, aby ułatwić sobie aktualizowanie zdarzeń i pobieranie tras.
Zdarzenie zmiany trasy ma miejsce za każdym razem, gdy zaktualizujesz ścieżkę do dowolnego z przystanków przypisanych do pojazdu, zmieni się kolejność przystanków lub gdy Fleet Engine zaktualizuje informacje o szacowanym czasie dotarcia.
vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
// handle route update events
});
Krok 3. Włącz interfejs API
Teraz gdy możesz już korzystać z informacji o trasie, musisz włączyć interfejs API, aby mógł odpowiadać na zdarzenia związane z pojazdami. Pamiętaj, że interfejs API jest inicjowany jako wyłączony, aby uniknąć niepotrzebnego wykorzystania przepustowości sieci.
vehicleRouteOverview.setRouteOverviewEnabled(true);
Możesz wstrzymać te aktualizacje w dowolnym momencie, wywołując tę samą metodę z wartością false.
Krok 4. Narysuj trasę w Mapach Google.
Po uzyskaniu listy RouteToVehicleStop możesz jej użyć w swojej aplikacji. Na przykład w instancji Map Google możesz narysować ścieżkę linii łamanej trasy. Ten fragment kodu pokazuje przykładową linię łamaną trasy w widoku mapy, która dodaje znaczniki do lokalizacji każdego przystanku.
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);
}
W ten sposób zobaczysz widok podobny do tego na zrzucie ekranu po prawej stronie:
Krok 5. Pobierz zrzut trasy
Jeśli chcesz, aby aplikacja wysłała jednorazowe wywołanie w celu pobrania zrzutu z informacjami o bieżącej trasie, możesz to zrobić, korzystając z tej metody:
ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();
Możesz to zrobić, zamiast subskrybować aktualizacje tras za pomocą detektorów zdarzeń.
Krok 6. Wyczyść dane
Jeśli w Twojej aplikacji nie jest już potrzebna funkcja przeglądu trasy, musisz ją wyczyścić. Pozwala to uniknąć niepotrzebnego użycia pamięci, przetwarzania i wykorzystania sieci w aplikacji.
Usuwanie konkretnego detektora zdarzeń
Usuń odbiornik, gdy nie jest już potrzebny.
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
Wyczyść wszystkie detektory zdarzeń
W ramach procedury czyszczenia możesz usunąć wszystkie zarejestrowane detektory zdarzeń jednocześnie.
vehicleRouteOverview.clearEventListeners();
Wyczyść instancję interfejsu Route Overview API
Za każdym razem, gdy Przegląd trasy nie jest już potrzebny lub zmienił się identyfikator śledzonego pojazdu, możesz wywołać ten interfejs API, aby usunąć wewnętrzne odniesienia.
vehicleRouteOverview.clearInstance();