Zaplanuj trasę

Czasami możesz chcieć zaplanować trasę, którą aplikacja udostępnia użytkownikom. Użycie tokena trasy z interfejsu Routes API, Routes Preferred 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.

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, Routes Preferred 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.

Jak działają tokeny trasy

Do planowania trasy z użyciem celów trasy możesz używać interfejsów Routes API, Routes Preferred API lub Route Optimization API. Możesz przekazać token trasy zwrócony przez dowolny z tych interfejsów API do pakietu Navigation SDK, 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, Routes Preferred 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.

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, Routes Preferred 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.

   • Routes Preferred API: computeCustomRoutes. Więcej informacji o wysyłaniu żądań tokena trasy w interfejsie Routes Preferred API znajdziesz w artykule Planowanie 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 lub Routes Preferred API, aby spełniało wymagania dotyczące używania 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.

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:

   let 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 setDestinationsWithToken:completionHandler: interfejsu mapView.navigator. Pakiet Navigation SDK pobiera miejsca docelowe i opcje wyznaczania trasy z tokena trasy, więc nie musisz przekazywać punktów pośrednich.

   Tryb podróży ustawiony w aplikacji, np. mapView.travelMode, musi być jedną z tych wartości:

   • .driving (GMSNavigationTravelModeDriving): samochodem. Jest to wartość domyślna, więc w większości aplikacji nie trzeba jej zmieniać.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): jednoślad.

   W przypadku każdego innego środka transportu żądanie nie powiedzie się i zostanie zwrócony błąd .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). W przypadku obu obsługiwanych wartości trasa używa środka transportu określonego w tokenie trasy. Jeśli na przykład aplikacja używa trybu jazdy, a token trasy dotyczy trasy dla jednośladu, pakiet Navigation SDK udostępni trasę dla jednośladu. Aby sprawdzić, jaki środek transportu jest używany na trasie, sprawdź resolvedParameters.travelMode. Więcej informacji znajdziesz w artykule Rozwiązane opcje routingu.

3. Sprawdź stan trasy w module obsługi ukończenia. Gdy pakiet Navigation SDK zakończy obliczanie trasy, przekazuje modułowi obsługi zakończenia obiekt GMSNavigationRouteDescription. Jeśli znajdzie trasę z lokalizacji pojazdu do miejsc docelowych w tokenie trasy, routeStatus opisu trasy będzie mieć wartość .OK (GMSRouteStatusOK) i będzie można rozpocząć nawigację. W przeciwnym razie moduł obsługi zakończenia otrzyma też obiekt NSError, który opisuje błąd. Na przykład:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

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 module obsługi zakończenia:

1. Sprawdź, czy routeStatus opisu trasy to .OK. Pakiet SDK Navigation podaje szczegóły tokena trasy tylko wtedy, gdy znajdzie trasę. Więcej informacji znajdziesz w kroku 2.

2. Pobierz routeTokenExecutionDetails opisu trasy, czyli obiekt zgodny z protokołem GMSNavigationRouteTokenExecutionDetails. Jeśli serwer nie podaje szczegółów tokena trasy, ta właściwość ma wartość nil.

3. Sprawdź właściwość tokenExecutionStatus w szczegółach wykonania. Jeśli jest to .tokenSuccessfullyApplied, 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 sekcji Wartości stanu wykonania tokena.

4. Opcjonalnie: jeśli stan to .tokenSuccessfullyApplied, sprawdź właściwość resolvedParameters tych samych szczegółów wykonania, aby zobaczyć, jakich opcji wyznaczania trasy używa trasa, np. czy unika opłat. Więcej informacji znajdziesz w artykule Rozwiązane opcje routingu.

Wartości stanu wykonania tokena

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

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

resolvedParameters to obiekt zgodny z protokołem GMSNavigationRouteTokenResolvedParameters lub nil, jeśli opcje wyznaczania trasy są niedostępne. Ma te właściwości:

• travelMode: środek transportu używany na trasie, np. .driving (GMSNavigationTravelModeDriving). Pakiet Navigation SDK zgłasza też .driving, gdy trasa korzysta ze środka transportu, który nie ma pasującej wartości, lub gdy środek transportu jest niedostępny.
• avoidTolls: czy trasa omija drogi płatne.
• avoidHighways: czy trasa omija autostrady.
• avoidFerries: czy trasa omija promy.
• avoidTunnels: określa, czy trasa została obliczona tak, aby w miarę możliwości unikać tuneli.
• avoidVignettes: kraje, w których trasa została obliczona tak, aby w miarę możliwości unikać winiet, jako dwuliterowe kody regionów Unicode CLDR, np. CH dla Szwajcarii.
• rerouteStrategy: strategia, której backend routingu używa do obliczania nowych tras podczas przejazdu. Strategie obejmują .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), która używa parametrów wyznaczania trasy w tokenie trasy do obliczania nowych tras.

Jeśli stan wykonania tokena nie jest równy .tokenSuccessfullyApplied, pakiet Navigation SDK zgłasza tylko travelMode, avoidTolls, avoidHighways i avoidFerries. Inne właściwości mają wartości domyślne, nawet jeśli podczas wysyłania prośby o token trasy poprosisz o unikanie tuneli lub winiet: avoidTunnels to false (NO), avoidVignettes jest puste, a rerouteStrategy to .unknown (GMSNavigationRerouteStrategyUnknown).

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.

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Scenariusze z kilkoma przystankami

Możesz skonfigurować maksymalnie 25 punktów pośrednich.

Pakiet SDK do nawigacji nie przechodzi automatycznie do następnego miejsca docelowego. Gdy pojazd dotrze do punktu pośredniego, wywołaj metodę continueToNextDestinationWithCompletion:, aby rozpocząć kolejny etap podróży. Dotyczy to również tokenów trasy, które mają punkty pośrednie. Gdy przejdziesz do następnego miejsca docelowego, pakiet SDK Navigation będzie nadal podążać trasą z tokena trasy, zamiast planować nową trasę.

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:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 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.