Zaplanuj trasę

Czasami możesz chcieć zaplanować trasę, którą aplikacja udostępnia użytkownikom. Użycie tokena trasy z interfejsu Routes API lub Route Optimization API może pomóc Ci określić 2 rzeczy dotyczące planowanej trasy:

• linii łamanej trasy,

• celów trasy.

Oto kilka przykładów celów mechanizmu planowania trasy:

• Skrócenie czas dostawy: firma dostarczająca jedzenie może chcieć skrócić czas dostawy.

• Skrócenie czasu podróży lub zmniejszenie zużycia paliwa: firma logistyczna może chcieć zwiększyć wydajność kierowców i obniżyć koszty paliwa.

• Skrócenie czasu dotarcia do miejsca docelowego: firma świadcząca usługi może chcieć skrócić czas dotarcia operatorów do miejsca realizacji zlecenia.

• Niższe koszty i większe bezpieczeństwo: firma oferująca wspólne przejazdy może chcieć znaleźć trasę, która jest tańsza dla pasażerów i ze względów bezpieczeństwa omija określone obszary.

Ważne: trasa, którą pokonują kierowcy, może się różnić od zaplanowanej przez Ciebie. Zmiana natężenia ruchu lub warunków drogowych, zjechanie pojazdu z zaplanowanej trasy lub przełączenie się na szybszą trasę może spowodować zmianę trasy podczas przejazdu. Za każdym razem, gdy pakiet SDK Navigation oblicza nową trasę, używa opcji wyznaczania trasy ustawionych w tokenie trasy, takich jak unikanie opłat.

Więcej informacji o planowaniu trasy za pomocą tokena trasy znajdziesz w artykule Pobieranie tokena trasy w interfejsie Routes API oraz w artykule Przejście na linie łamane i tokeny trasy w interfejsie Route Optimization API.

Dlaczego warto używać tokena trasy do celów trasy

Dzięki tokenowi trasy z interfejsu Routes API lub Route Optimization API masz większą kontrolę nad podaną trasą:

• Zaplanuj trasę z wyprzedzeniem, aby pakiet Navigation SDK mógł z niej korzystać.

• Wybieranie najlepszej trasy do użycia przez pakiet Navigation SDK. Jeśli podczas generowania tras w interfejsie Routes API poprosisz o tokeny trasy, otrzymasz token dla każdej wygenerowanej trasy. Następnie możesz wybrać token trasy, której chcesz użyć, i przekazać go do pakietu SDK Navigation.

• oszacować cenę z góry, w tym szacowany czas dotarcia na miejsce i odległość; Rzeczywisty koszt i czas mogą się różnić, ale to oszacowanie zmniejsza różnicę między oczekiwanym a rzeczywistym kosztem trasy.

• Określ bardziej zaawansowane cele trasy, takie jak trasa ekologiczna lub najkrótsza trasa.

Wskazówka: token trasy jest przeznaczony dla konkretnego miejsca początkowego i docelowego oraz określonego czasu. Aby uzyskać nowy token trasy, musisz wysłać nowe żądanie do interfejsu Routes API lub Route Optimization API.

Jak działają tokeny trasy

Do planowania trasy z uwzględnieniem celów możesz używać interfejsu Routes API lub Route Optimization API. Możesz przekazać token trasy zwrócony przez jeden z tych interfejsów API do pakietu SDK Navigation, aby określić, jak ma on wyznaczać trasę pojazdu.

Oto co się dzieje, gdy poprosisz o token trasy i go użyjesz:

1. Interfejs Routes API lub Route Optimization API zwraca zaszyfrowany token trasy, który zawiera linię łamaną trasy i cele trasy.

2. Przekazujesz token trasy do pakietu Navigation SDK.

3. Pakiet Navigation SDK rozpoczyna nawigację po zaplanowanej trasie, nawet jeśli dostępna jest szybsza trasa.

4. Jeśli podczas podróży zmienią się warunki drogowe lub natężenie ruchu albo pojazd opuści zaplanowaną trasę, pakiet Navigation SDK obliczy nową trasę, która będzie zgodna z celami i opcjami wyznaczania trasy ustawionymi w tokenie trasy.

Dzięki temu rzeczywista trasa jest jak najbardziej zbliżona do zaplanowanej.

Dlaczego zaplanowana trasa może nie zostać dokładnie przejechana

Nawigacja rozpoczyna się na zaplanowanej trasie, ale rzeczywista trasa może się od niej różnić w takich sytuacjach:

• Pojazd rozpoczyna jazdę z dala od zaplanowanego punktu początkowego.
• warunki drogowe lub natężenie ruchu zmieniają się podczas przejazdu;
• Pojazd opuszcza zaplanowaną trasę.

Te różnice mogą wpływać na odległość, szacowany czas dotarcia na miejsce i inne ważne parametry zaplanowanego przejazdu.

Wskazówka: sprawdzoną metodą jest zawsze prosić o nowy token trasy za każdym razem, gdy ustawiasz miejsce docelowe w pakiecie Navigation SDK, i zaplanować pewne zmiany, aby uniknąć wpływu na działalność firmy.

Planowanie trasy za pomocą tokena trasy

Możesz zaplanować trasę, tworząc token trasy, a następnie przekazując go do pakietu Navigation SDK, jak opisano w tych krokach:

Krok 1. Utwórz token trasy za pomocą interfejsu Routes API lub Route Optimization API

1. Poproś o token trasy, korzystając z jednej z tych metod:

   • Routes API: computeRoutes. Więcej informacji o wysyłaniu żądań tokena trasy w interfejsie Routes API znajdziesz w artykule Obliczanie trasy i Pobieranie tokena trasy.

   • Route Optimization API: optimizeTours lub batchOptimizeTours. Więcej informacji o wysyłaniu żądań tokena trasy w interfejsie Route Optimization API znajdziesz w artykule Przejście na linie łamane i tokeny trasy.

2. Skonfiguruj żądanie do interfejsu Routes API, aby spełniało wymagania dotyczące korzystania z tokena trasy:

   • Ustaw travelMode na DRIVE lub TWO_WHEELER.
   • Ustaw routingPreference na TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL.
   • NIE używaj Via punktów pośrednich.

Uwaga: w tokenie trasy możesz określić dokładne wartości miejsca rozpoczęcia i zakończenia trasy, takie jak wejścia, doki załadunkowe lub wyznaczone miejsca odbioru, używając tokena punktu nawigacyjnego.

Krok 2. Przekaż token trasy do pakietu Navigation SDK

1. Przechowywanie tokena trasy: w Navigation SDK skonfiguruj ciąg znaków do przechowywania tokena trasy. Na przykład:

   String routeToken = "route token returned by Routes API";
   

   Przykład zwróconego tokena trasy:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Przekaż token trasy do pakietu Navigation SDK za pomocą metody Navigator.setDestinationsWithToken. Navigation SDK pobiera miejsca docelowe i opcje wyznaczania trasy z tokena trasy, więc nie musisz przekazywać punktów pośrednich ani trybu podróży.

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

   Uwaga: jeśli Twoja aplikacja używa pakietu Navigation SDK w wersji starszej niż 8.1, użyj wycofanych metod setDestinations, które przyjmują CustomRoutesOptions, i przekaż te same punkty docelowe, które zostały użyte do utworzenia tokena trasy.

3. Sprawdź stan trasy w wywołaniu zwrotnym. Gdy pakiet SDK Navigation zakończy obliczanie trasy, przekaże do wywołania zwrotnego obiekt RouteDescription. Jeśli znajdzie trasę z lokalizacji pojazdu do miejsc docelowych w tokenie trasy, RouteDescription.getRouteStatus zwraca Navigator.RouteStatus.OK i możesz rozpocząć nawigację. Na przykład:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

Uwaga: jeśli musisz ponownie pokonać tę samą trasę, poproś o nowy token trasy.

Sprawdzanie, czy pakiet Navigation SDK zastosował token trasy

Stan trasy OK oznacza, że pakiet Navigation SDK znalazł trasę, ale niekoniecznie zaplanowaną przez Ciebie. Aby sprawdzić, czy trasa jest zgodna z zaplanowaną, wykonaj te czynności w wywołaniu zwrotnym:

1. Sprawdź, czy RouteDescription.getRouteStatus zwraca Navigator.RouteStatus.OK. Pakiet Navigation SDK podaje szczegóły tokena trasy tylko wtedy, gdy znajdzie trasę. Więcej informacji znajdziesz w kroku 2.

2. Wywołaj RouteDescription.getRouteTokenExecutionDetails, aby uzyskać obiekt RouteTokenExecutionDetails. Jeśli serwer nie podaje szczegółów tokena trasy, ta metoda zwraca wartość null.

3. Wywołaj getTokenExecutionStatus na obiekcie RouteTokenExecutionDetails. Jeśli zwróci wartość TOKEN_SUCCESSFULLY_APPLIED, trasa jest zgodna z zaplanowaną trasą. Każdy inny stan oznacza, że trasa może się różnić od zaplanowanej. Więcej informacji o poszczególnych stanach znajdziesz w artykule Wartości stanu wykonania tokena.

4. Opcjonalnie: jeśli stan to TOKEN_SUCCESSFULLY_APPLIED, wywołaj getResolvedParameters na tym samym obiekcie RouteTokenExecutionDetails, aby sprawdzić, z których opcji wyznaczania trasy korzysta trasa, np. czy unika opłat. Więcej informacji znajdziesz w artykule Rozwiązane opcje routingu.

Wartości stanu wykonania tokena

Jeśli stan trasy to OK, możesz rozpocząć wskazówki z dowolnym stanem wykonania tokena. Stan informuje, czy trasa jest zgodna z zaplanowaną.

Stan	podąża zaplanowaną trasą,	Opis
TOKEN_SUCCESSFULLY_APPLIED	Tak	Pakiet Navigation SDK zastosował token trasy.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Niekoniecznie	Pakiet Navigation SDK nie mógł odtworzyć zaplanowanej trasy, ponieważ lokalizacja w żądaniu trasy znajdowała się w odległości większej niż 25 metrów od pasującej lokalizacji w tokenie trasy. W przypadku błędu setDestinationsWithToken oznacza to, że urządzenie znajdowało się w odległości większej niż 25 metrów od punktu początkowego w tokenie trasy. Trasa nadal prowadzi do miejsc docelowych, ale pakiet Navigation SDK nie może potwierdzić, że używa opcji wyznaczania trasy z tokena trasy, takich jak unikanie opłat.
TOKEN_IGNORED_OTHER	Niekoniecznie	Pakiet Navigation SDK nie mógł odtworzyć zaplanowanej trasy z innego powodu, np. dlatego, że droga na zaplanowanej trasie jest zamknięta. Trasa nadal prowadzi do miejsc docelowych, ale pakiet Navigation SDK nie może potwierdzić, że używa opcji wyznaczania trasy z tokena trasy, takich jak unikanie opłat.
NO_TOKEN_PROVIDED	Nie dotyczy	Żądanie trasy nie zawierało tokena trasy.
UNKNOWN	Nieznany	Stan jest nieznany.

Jeśli trasa nie musi być zgodna z zaplanowaną, a dokładna trasa ma znaczenie, na przykład dlatego, że została użyta do obliczenia ceny, zarejestruj stan lub poproś o nowy token trasy z bieżącej lokalizacji pojazdu.

Rozwiązane opcje routingu

getResolvedParameters zwraca obiekt RouteTokenResolvedParameters lub null, jeśli opcje wyznaczania trasy są niedostępne. RouteTokenResolvedParameters ma te metody:

• getTravelMode: środek transportu używany na trasie, np. RoutingOptions.TravelMode.DRIVING. Pakiet Navigation SDK zwraca też wartość RoutingOptions.TravelMode.DRIVING, gdy trasa korzysta ze środka transportu, który nie ma pasującej wartości, lub gdy środek transportu jest niedostępny.
• getAvoidTolls: czy trasa omija drogi płatne.
• getAvoidHighways: czy trasa omija autostrady.
• getAvoidFerries: czy trasa omija promy.

Przykład

Poniższy przykładowy kod pokazuje, jak zaplanować trasę za pomocą tokena trasy, sprawdzić, czy pakiet Navigation SDK zastosował token, i rozpocząć wskazówki.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

Uwaga: możesz skonfigurować maksymalnie 25 punktów pośrednich.

Interakcja tokenów trasy z Navigation SDK

Oto jak Navigation SDK obsługuje zaplanowaną trasę:

• Zastępuje wszystkie wcześniej ustawione miejsca docelowe.

• wykorzystuje lokalizację początkową pojazdu;

• Dostosowuje się do warunków na drodze i natężenia ruchu. Zobacz Dlaczego zaplanowana trasa może nie zostać dokładnie przejechana.

• Używa opcji wyznaczania trasy ustawionych w tokenie trasy zamiast tych ustawień w aplikacji, w tym podczas obliczania nowej trasy w trakcie przejazdu:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • tryb podróży ustawiony w aplikacji,

• Uwzględnia te ustawienia podczas obliczania lub dostosowywania trasy:

  • Cele trasy z tokena trasy, takie jak trasa ekologiczna lub najkrótsza trasa. Jeśli pakiet SDK Navigation musi dostosować trasę, używa celów trasy określonych podczas wysyłania żądania tokena trasy.
  • Opcje związane z punktami orientacyjnymi z tokena trasy, takie jak preferowana strona drogi.

Uwaga: w przypadku setDestinationsWithToken nie przekazujesz punktów pośrednich, więc Navigation SDK używa miejsc docelowych i opcji punktów pośrednich z tokena trasy. Aby ustawić opcje punktów orientacyjnych, takie jak preferowana strona drogi lub postoje pojazdu, użyj pól sideOfRoad i vehicleStopover w punktach orientacyjnych w żądaniu do interfejsu Routes API. Punktem początkowym jest zawsze lokalizacja urządzenia, więc opcje ustawione w punkcie początkowym w żądaniu do interfejsu Routes API nie mają zastosowania.