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.

Önemli: Sürücülerin izlediği rota, planladığınız rotadan farklı olabilir. Trafik veya yol koşullarının değişmesi, aracın planlanan rotadan çıkması ya da daha hızlı bir rotaya geçilmesi, gezi sırasında rotanın değişmesine neden olabilir. Navigation SDK, yeni bir rota hesapladığında rota jetonunuzda ayarlanan rota seçeneklerini (ör. ücretli yollardan kaçınma) kullanır.

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.

İpucu: Rota jetonu, belirli bir başlangıç ve varış noktası için ve belirli bir zamanda kullanılır. Yeni bir rota jetonu için yeni bir Routes API veya Route Optimization API isteği göndermeniz gerekir.

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.

İpucu: En iyi uygulama olarak, Navigation SDK'da varış noktasını her ayarladığınızda yeni bir rota jetonu isteyin ve işletmenizin etkilenmemesi için bazı varyasyonlar planlayın.

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.

Not: Girişler, yükleme alanları veya belirlenmiş teslim alma alanları gibi kesin başlangıç ve hedef değerlerini, rota jetonunuzda bir navigasyon noktası jetonu kullanarak belirtebilirsiniz.

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:

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

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

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

2. Navigator.setDestinationsWithToken yöntemini kullanarak rota jetonunu Navigation SDK'ya iletin. Navigation SDK'sı, hedefleri ve rota seçeneklerini rota jetonundan alır. Bu nedenle, ara nokta veya seyahat modu iletmeniz gerekmez.

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

   Not: Uygulamanız Navigation SDK'nın 8.1'den önceki bir sürümünü kullanıyorsa bunun yerine CustomRoutesOptions alan, desteği sonlandırılmış setDestinations yöntemlerini kullanın ve rota jetonunu oluşturmak için kullandığınız hedef yol noktalarını iletin.

3. Geri çağırma işlevinizde rota durumunu kontrol edin. Navigation SDK, rotayı hesaplamayı tamamladığında geri çağırma işlevinize bir RouteDescription iletir. Araç konumundan rota jetonunuzdaki varış noktalarına giden bir rota bulursa RouteDescription.getRouteStatus, Navigator.RouteStatus.OK değerini döndürür ve rehberliği başlatabilirsiniz. Örneğin:

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

Not: Aynı rotada tekrar seyahat etmeniz gerekiyorsa yeni bir rota jetonu isteyin.

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 geri çağırma işlevinizde aşağıdaki adımları uygulayın:

1. RouteDescription.getRouteStatus işlevinin Navigator.RouteStatus.OK değerini döndürdüğünü 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. RouteTokenExecutionDetails nesnesi almak için RouteDescription.getRouteTokenExecutionDetails yöntemini çağırın. Sunucu, rota jetonu ayrıntılarını sağlamazsa bu yöntem null değerini döndürür.

3. RouteTokenExecutionDetails nesnesinde getTokenExecutionStatus yöntemini çağırın. TOKEN_SUCCESSFULLY_APPLIED döndürülürse rota, planladığınız rotayla eşleşir. Başka bir durum, 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 TOKEN_SUCCESSFULLY_APPLIED ise aynı RouteTokenExecutionDetails nesnesinde getResolvedParameters yöntemini çağırarak rotanın hangi rota seçeneklerini kullandığını (ör. ücretli yollardan kaçınıp kaçınmadığını) kontrol edin. Daha fazla bilgi için Çözümlenmiş yönlendirme seçenekleri başlıklı makaleyi inceleyin.

Jeton yürütme durumu değerleri

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

Durum	Planladığınız rotayı takip eder.	Açıklama
TOKEN_SUCCESSFULLY_APPLIED	Evet	Navigation SDK, rota jetonunuzu uyguladı.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Her zaman değil	Navigation SDK, rota isteğindeki bir konum, rota jetonunuzdaki eşleşen konumdan 25 metreden daha uzakta olduğu için planlanan rotanızı yeniden oluşturamadı. setDestinationsWithToken ile bu, cihazın rota jetonunuzdaki başlangıç noktasından 25 metreden daha uzakta olduğu anlamına gelir. Rota yine de hedeflerinize gider ancak Navigasyon SDK'sı, rota jetonunuzdaki rota seçeneklerini (ör. ücretli yollardan kaçınma) kullandığını onaylayamaz.
TOKEN_IGNORED_OTHER	Her zaman değil	Navigation SDK, başka bir nedenle (ör. planlanan rotanızdaki bir yolun kapalı olması) planlanan rotanızı yeniden oluşturamadı. Rota yine de hedeflerinize gider ancak Navigasyon SDK'sı, rota jetonunuzdaki rota seçeneklerini (ör. ücretli yollardan kaçınma) kullandığını onaylayamaz.
NO_TOKEN_PROVIDED	Geçerli değil	Rota isteği, rota jetonu içermiyordu.
UNKNOWN	Bilinmiyor	Durum bilinmiyor.

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

getResolvedParameters, bir RouteTokenResolvedParameters nesnesi veya rota seçenekleri mevcut değilse null döndürür. RouteTokenResolvedParameters şu yöntemlere sahiptir:

• getTravelMode: Rotanın kullandığı seyahat modu (ör. RoutingOptions.TravelMode.DRIVING). Navigation SDK, rota eşleşen değeri olmayan bir seyahat modu kullandığında veya seyahat modu kullanılamadığında da RoutingOptions.TravelMode.DRIVING değerini bildirir.
• getAvoidTolls: Rotada ücretli geçişlerin kullanılıp kullanılmadığı.
• getAvoidHighways: Rotada otoyolların kullanılmaması.
• getAvoidFerries: Rotada feribot kullanılıp kullanılmadığı.

Ö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.

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

Not: En fazla 25 ara nokta yapılandırabilirsiniz.

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:

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • 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.

Not: setDestinationsWithToken ile ara nokta iletmediğiniz için Navigasyon SDK'sı, rota jetonunuzdaki varış noktalarını ve ara nokta seçeneklerini kullanır. Yol kenarı tercihi veya araç durakları gibi ara nokta seçeneklerini ayarlamak için Routes API isteğinizdeki ara noktalarda sideOfRoad ve vehicleStopover alanlarını kullanın. Başlangıç noktası her zaman cihazın konumudur. Bu nedenle, Routes API isteğinizde başlangıç noktası için ayarladığınız seçenekler geçerli olmaz.