Rota planlama

Bazen uygulamanızın kullanıcılara sunduğu rotayı planlamak isteyebilirsiniz. Routes API veya Route Optimization API'den alınan rota jetonunu kullanarak planlanan rotanız için iki şeyi belirtebilirsiniz:

• Rota için çoklu çizgi

• Rota hedefleriniz

Örneğin, sahip olabileceğiniz bazı rota hedefleri şunlardır:

• Teslimat süresini en aza indirme: Yemek teslimatı yapan bir işletme, yemek teslimat süresini en aza indirmek isteyebilir.

• Seyahat süresini veya yakıt tüketimini en aza indirme: Bir lojistik işletmesi, sürücülerinin verimliliğini artırmak ve yakıt maliyetlerini azaltmak isteyebilir.

• Hedefe ulaşma süresini en aza indirme: Bir hizmet sevk işlemi, operatörlerin bir iş isteğine ulaşması için gereken süreyi en aza indirmek isteyebilir.

• Maliyetleri düşürme ve güvenliği artırma: Araç paylaşımı işletmesi, yolcular için daha düşük maliyetli ve güvenlik nedeniyle belirli bölgelerden kaçınan bir rota bulmak isteyebilir.

Rota jetonu kullanarak rota planlama hakkında daha fazla bilgi için Routes API'deki Rota jetonu alma ve Route Optimization API'deki Geçiş çoklu çizgileri ve rota jetonları bölümlerini inceleyin.

Rota hedefleri için neden rota jetonu kullanılır?

Routes API veya Route Optimization API'den alınan rota jetonuyla, sağlanan rota üzerinde daha fazla kontrol sahibi olursunuz:

• Navigation SDK'nın kullanması için önceden bir rota planlayın.

• Navigation SDK'nın kullanacağı en iyi rotayı seçin. Routes API'de rota oluştururken rota jetonları isterseniz oluşturulan her rota için bir rota jetonu alırsınız. Ardından, kullanmak istediğiniz rotanın jetonunu seçip Navigation SDK'ya iletebilirsiniz.

• TVS ve mesafe tahminleri de dahil olmak üzere fiyatı önceden tahmin edin. Gerçek maliyet ve süre farklılık gösterebilir ancak bu tahmin, beklenen ve gerçek rota maliyeti arasındaki farkı azaltır.

• Çevre dostu rota veya en kısa rota gibi daha gelişmiş rota hedefleri belirtebilirsiniz.

Rota jetonlarının işleyiş şekli

Rota hedeflerini kullanarak rota planlamak için Routes API veya Route Optimization API'yi kullanabilirsiniz. Bu API'lerden birinden döndürülen rota jetonunu Navigation SDK'ya ileterek aracınızın rotasını nasıl belirleyeceğini yönlendirebilirsiniz.

Rota jetonu isteyip kullandığınızda şunlar gerçekleşir:

1. Routes API veya Route Optimization API, rota çoklu çizgisini ve rota hedeflerini içeren şifrelenmiş bir rota jetonu döndürür.

2. Rota jetonunu Navigation SDK'ya iletirsiniz.

3. Navigation SDK, daha hızlı bir rota olsa bile planladığınız rotada navigasyonu başlatır.

4. Yolculuk sırasında trafik veya yol koşulları değişirse ya da araç planlanan rotadan çıkarsa Navigasyon SDK'sı, rota jetonunuzda ayarlanan rota hedeflerine ve rota seçeneklerine uygun yeni bir rota hesaplar.

Bu işlem, gerçek rotanın planlanan rotanıza mümkün olduğunca yakın olmasını sağlar.

Planlanan rotanın tam olarak takip edilememesinin olası nedenleri

Navigasyon, planlanan rotanızda başlar ancak gerçek rota aşağıdaki gibi durumlarda planlanan rotadan farklı olabilir:

• Araç, planlanan başlangıç noktasından uzakta çalıştırılıyor.
• Gezi sırasında trafik veya yol koşulları değiştiğinde.
• Araç, planlanan rotadan ayrıldığında

Bu farklılıklar, planladığınız mesafe, TVS ve diğer önemli gezi özelliklerini etkileyebilir.

Rota jetonu kullanarak rota planlama

Rota jetonu oluşturup Navigasyon SDK'sına ileterek rota planlayabilirsiniz. Bunun için aşağıdaki adımları uygulayın:

1. adım: Routes API veya Route Optimization API'yi kullanarak rota jetonu oluşturun

1. Aşağıdaki yöntemlerden birini kullanarak rota jetonu isteyin:

   • Routes API: computeRoutes. Routes API'de rota jetonu isteme hakkında daha fazla bilgi için Rota hesaplama ve Rota jetonu alma başlıklı makaleleri inceleyin.

   • Route Optimization API: optimizeTours veya batchOptimizeTours. Route Optimization API'de rota jetonu isteme hakkında daha fazla bilgi için Geçiş Çoklu Çizgileri ve Rota Jetonları başlıklı makaleyi inceleyin.

2. Rota jetonu kullanma koşullarını karşılamak için Routes API isteğinizi ayarlayın:

   • travelMode değerini DRIVE veya TWO_WHEELER olarak ayarlayın.
   • routingPreference değerini TRAFFIC_AWARE veya TRAFFIC_AWARE_OPTIMAL olarak ayarlayın.
   • Via yol noktası kullanmayın.

2. adım: Rota jetonunu Navigasyon SDK'sına iletin

1. Rota jetonunu saklama: Navigation SDK'da rota jetonunu saklamak için bir dize oluşturun. Örneğin:

   let routeToken = "route token returned by Routes API"
   

   Döndürülen rota jetonu örneği:

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

2. mapView.navigator sınıfının setDestinationsWithToken:completionHandler: yöntemini kullanarak rota jetonunu Navigasyon SDK'sına iletin. Navigasyon SDK'sı, varış noktalarını ve rota seçeneklerini rota jetonundan alır. Bu nedenle, ara noktaları iletmeniz gerekmez.

   Uygulamanızda ayarlanan seyahat modu (ör. mapView.travelMode) aşağıdaki değerlerden biri olmalıdır:

   • .driving (GMSNavigationTravelModeDriving): Araba. Bu, varsayılan değerdir. Bu nedenle çoğu uygulamanın bu değeri değiştirmesi gerekmez.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): İki tekerlekli araç.

   Başka bir seyahat modu, isteğin .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported) ile başarısız olmasına neden olur. Desteklenen her iki değerde de rota, rota jetonunuzdaki seyahat modunu kullanır. Örneğin, uygulamanız sürüş modunu kullanıyorsa ve rota jetonunuz iki tekerlekli araç rotası içinse Navigasyon SDK'sı iki tekerlekli araç rotası sağlar. Rotanın hangi seyahat modunu kullandığını onaylamak için resolvedParameters.travelMode simgesini kontrol edin. Daha fazla bilgi için Çözümlenmiş yönlendirme seçenekleri başlıklı makaleyi inceleyin.

3. Tamamlama işleyicinizde rota durumunu kontrol edin. Navigation SDK'sı, rotayı hesaplamayı tamamladığında tamamlama işleyicinize bir GMSNavigationRouteDescription iletir. Araç konumundan rota jetonunuzdaki hedeflere giden bir rota bulunursa rota açıklamasının routeStatus değeri .OK (GMSRouteStatusOK) olur ve rehberliği başlatabilirsiniz. Aksi takdirde, tamamlama işleyiciniz hatayı açıklayan bir NSError da alır. Örneğin:

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

Navigasyon SDK'sının rota jetonunuzu uygulayıp uygulamadığını kontrol etme

Rota durumunun .OK olması, Navigasyon SDK'sının bir rota bulduğu ancak bu rotanın planladığınız rota olmayabileceği anlamına gelir. Rotanın planladığınız rotayla eşleşip eşleşmediğini kontrol etmek için tamamlama işleyicinizde aşağıdaki adımları uygulayın:

1. Rota açıklamasının routeStatus değerinin .OK olduğunu doğrulayın. Navigation SDK, rota jetonu ayrıntılarını yalnızca rota bulduğunda sağlar. Daha fazla bilgi için 2. adım'a bakın.

2. Rota açıklamasının routeTokenExecutionDetails değerini alın. Bu, GMSNavigationRouteTokenExecutionDetails protokolüne uygun bir nesnedir. Sunucu, rota jetonu ayrıntılarını sağlamıyorsa bu özellik nil olur.

3. Yürütme ayrıntılarının tokenExecutionStatus özelliğini kontrol edin. .tokenSuccessfullyApplied ise rota, planladığınız rotayla eşleşir. Diğer durumlar, rotanın planladığınız rotadan farklı olabileceği anlamına gelir. Her bir durum hakkında daha fazla bilgi için Jeton yürütme durumu değerleri başlıklı makaleyi inceleyin.

4. İsteğe bağlı: Durum .tokenSuccessfullyApplied ise aynı yürütme ayrıntılarının resolvedParameters özelliğini kontrol ederek rotanın hangi rota seçeneklerini kullandığını (ör. ücretli yollardan kaçınıp kaçınmadığını) öğrenin. Daha fazla bilgi için Çözümlenmiş yönlendirme seçenekleri başlıklı makaleyi inceleyin.

Jeton yürütme durumu değerleri

routeStatus, .OK ise rehberliği herhangi bir jeton yürütme durumuyla başlatabilirsiniz. Durum, rotanın planladığınız rotayı takip edip etmediğini gösterir.

Rota, planladığınız rotayı tam olarak takip etmiyorsa ve tam rota önemliyse (ör. fiyatı hesaplamak için kullandığınız için) durumu günlüğe kaydedin veya aracın mevcut konumundan yeni bir rota jetonu isteyin.

Çözümlenen yönlendirme seçenekleri

resolvedParameters, GMSNavigationRouteTokenResolvedParameters protokolüne uyan bir nesnedir veya rota seçenekleri kullanılamıyorsa nil değeridir. Aşağıdaki özelliklere sahiptir:

• travelMode: Rotanın kullandığı seyahat modu (ör. .driving (GMSNavigationTravelModeDriving)). Navigation SDK, rota eşleşen değeri olmayan bir seyahat modu kullandığında veya seyahat modu kullanılamadığında da .driving değerini bildirir.
• avoidTolls: Rotada ücretli geçişlerin kullanılıp kullanılmadığı.
• avoidHighways: Rotada otoyolların kullanılmaması.
• avoidFerries: Rotada feribot kullanılıp kullanılmadığı.
• avoidTunnels: Rotanın, mümkün olduğunda tünellerden kaçınacak şekilde hesaplanıp hesaplanmadığı.
• avoidVignettes: Mümkün olduğunda vinyetlerden kaçınmak için rotanın hesaplandığı ülkeler. İsviçre için CH gibi Unicode CLDR iki harfli bölge kodları olarak gösterilir.
• rerouteStrategy: Yolculuk sırasında yeni rotaları hesaplamak için rota arka ucunun kullandığı strateji. Stratejiler arasında, yeni rotaları hesaplamak için rota jetonunuzdaki rota parametrelerini kullanan .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters) yer alır.

Jeton yürütme durumu .tokenSuccessfullyApplied değilse Navigation SDK yalnızca travelMode, avoidTolls, avoidHighways ve avoidFerries değerlerini bildirir. Rota jetonunu istediğinizde tünellerden veya ücretli vinyetlerden kaçınmayı talep etmiş olsanız bile diğer özellikler varsayılan değerlerine sahiptir: avoidTunnels, false (NO), avoidVignettes boş ve rerouteStrategy, .unknown (GMSNavigationRerouteStrategyUnknown).

Örnek

Aşağıdaki kod örneğinde, rota jetonu kullanarak rota planlama, Navigasyon SDK'sının jetonu uygulayıp uygulamadığını kontrol etme ve rehberliği başlatma işlemleri gösterilmektedir.

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

Birden fazla durak içeren senaryolar

En fazla 25 yol noktası yapılandırabilirsiniz.

Navigation SDK, bir sonraki hedefe otomatik olarak ilerlemez. Araç bir ara noktaya ulaştığında gezinin bir sonraki ayağını başlatmak için continueToNextDestinationWithCompletion: yöntemini çağırın. Bu durum, ara noktaları olan rota jetonları için de geçerlidir. Bir sonraki hedefe ilerlediğinizde Navigasyon SDK'sı, yeni bir rota planlamak yerine rota jetonunuzdaki rotayı takip etmeye devam eder.

Rota jetonları ve Navigasyon SDK'sının etkileşimi

Navigation SDK'sı, planlanan rotanızı şu şekilde işler:

• Daha önce ayarlanmış tüm hedefleri geçersiz kılar.

• Aracın başlangıç konumunu kullanır.

• Yol ve trafik koşullarına göre ayarlanır. Planlanan bir rotanın tam olarak takip edilememesinin nedenleri başlıklı makaleyi inceleyin.

• Uygulamanızdaki aşağıdaki ayarlar yerine rota jetonunuzda ayarlanan rota seçeneklerini kullanır. Bu ayarlar, gezi sırasında yeni bir rota hesaplarken de geçerlidir:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • Uygulamanızda ayarlanan seyahat modu

• Rotayı hesaplarken veya ayarlarken şu ayarlara uyar:

  • Çevre dostu rota veya en kısa rota gibi rota jetonunuzdaki rota hedefleri. Navigasyon SDK'sının rotayı ayarlaması gerekiyorsa rota jetonunu isterken belirttiğiniz rota hedeflerini kullanır.
  • Yol kenarı tercihi gibi rota jetonunuzdaki ara noktayla ilgili seçenekler.