Merencanakan rute

Terkadang, Anda mungkin ingin merencanakan rute yang disediakan aplikasi Anda kepada pengguna. Menggunakan token rute dari Routes API, Routes Preferred API, atau Route Optimization API dapat membantu Anda menentukan dua hal untuk rute yang direncanakan:

• Polyline untuk rute

• Tujuan rute Anda

Misalnya, berikut beberapa contoh tujuan pemilihan rute yang mungkin Anda miliki:

• Meminimalkan waktu pengiriman: Bisnis pengiriman makanan mungkin ingin meminimalkan waktu yang diperlukan untuk mengirimkan makanan.

• Meminimalkan waktu perjalanan atau konsumsi bahan bakar: Bisnis logistik mungkin ingin meningkatkan efisiensi pengemudi dan mengurangi biaya bahan bakar.

• Meminimalkan waktu ke tujuan: Operasi pengiriman layanan mungkin ingin meminimalkan waktu yang diperlukan untuk mengarahkan operator ke permintaan tugas.

• Menurunkan biaya dan meningkatkan keselamatan: Bisnis transportasi online mungkin ingin menemukan rute yang lebih murah bagi penumpang dan menghindari area tertentu karena alasan keselamatan.

Untuk mengetahui informasi selengkapnya tentang cara merencanakan rute menggunakan token rute, lihat Mendapatkan token rute di Routes API dan Polyline Transisi dan Token Rute di Route Optimization API.

Alasan menggunakan token rute untuk tujuan rute

Dengan token rute dari Routes API, Routes Preferred API, atau Route Optimization API, Anda memiliki kontrol lebih besar atas rute yang disediakan:

• Rencanakan rute terlebih dahulu untuk digunakan Navigation SDK.

• Pilih rute terbaik untuk digunakan Navigation SDK. Jika Anda meminta token rute saat membuat rute di Routes API, Anda akan mendapatkan token rute untuk setiap rute yang dibuat. Kemudian, Anda dapat memilih token untuk rute yang ingin digunakan saat meneruskannya ke Navigation SDK.

• Perkirakan harga di awal, termasuk perkiraan untuk PWT dan jarak. Meskipun biaya dan waktu sebenarnya mungkin bervariasi, estimasi ini mengurangi kesenjangan antara biaya rute yang diharapkan dan yang sebenarnya.

• Tentukan tujuan rute yang lebih lanjut, seperti rute ramah lingkungan atau rute terpendek.

Cara kerja token rute

Anda dapat menggunakan Routes API, Routes Preferred API, atau Route Optimization API untuk merencanakan rute menggunakan tujuan rute. Anda dapat meneruskan token rute yang ditampilkan dari salah satu API ini ke Navigation SDK untuk memandu cara merutekan kendaraan Anda.

Berikut yang terjadi saat Anda meminta dan menggunakan token rute:

1. Routes API, Routes Preferred API, atau Route Optimization API menampilkan token rute terenkripsi yang mencakup polyline rute dan tujuan rute.

2. Anda meneruskan token rute ke Navigation SDK.

3. Navigation SDK memulai navigasi pada rute yang Anda rencanakan, meskipun rute yang lebih cepat tersedia.

4. Selama perjalanan, jika kondisi lalu lintas atau jalan berubah, atau jika kendaraan keluar dari rute yang direncanakan, Navigation SDK akan menghitung rute baru yang mengikuti tujuan rute dan opsi pemilihan rute yang ditetapkan dalam token rute Anda.

Proses ini memaksimalkan seberapa dekat rute sebenarnya dengan rute yang Anda rencanakan.

Alasan rute yang direncanakan mungkin tidak diikuti secara persis

Navigasi dimulai pada rute yang direncanakan, tetapi rute sebenarnya dapat berbeda dari rute tersebut dalam situasi seperti berikut:

• Kendaraan memulai perjalanan dari titik awal yang direncanakan.
• Kondisi lalu lintas atau jalan berubah selama perjalanan.
• Kendaraan keluar dari rute yang direncanakan.

Perbedaan ini dapat memengaruhi jarak, perkiraan waktu tiba, dan kualitas perjalanan penting lainnya yang Anda rencanakan.

Merencanakan rute menggunakan token rute

Anda dapat merencanakan rute dengan membuat token rute, lalu meneruskannya ke Navigation SDK, seperti yang dijelaskan dalam langkah-langkah berikut:

Langkah 1: Buat token rute menggunakan Routes API, Routes Preferred API, atau Route Optimization API

1. Minta token rute dengan salah satu metode berikut:

   • Routes API: computeRoutes. Untuk mengetahui informasi selengkapnya tentang cara meminta token rute di Routes API, lihat Menghitung rute dan Mendapatkan token rute.

   • Routes Preferred API: computeCustomRoutes. Untuk informasi selengkapnya tentang cara meminta token rute di Routes Preferred API, lihat Merencanakan rute.

   • Route Optimization API: optimizeTours atau batchOptimizeTours. Untuk mengetahui informasi selengkapnya tentang cara meminta token rute di Route Optimization API, lihat Polyline Transisi dan Token Rute.

2. Siapkan permintaan Routes API atau Routes Preferred API Anda untuk memenuhi persyaratan penggunaan token rute:

   • Tetapkan travelMode ke DRIVE atau TWO_WHEELER.
   • Tetapkan routingPreference ke TRAFFIC_AWARE atau TRAFFIC_AWARE_OPTIMAL.
   • Jangan gunakan titik jalan Via.

Langkah 2: Teruskan token rute ke Navigation SDK

1. Menyimpan token rute: Di Navigation SDK, siapkan string untuk menyimpan token rute. Contoh:

   let routeToken = "route token returned by Routes API"
   

   Contoh token rute yang ditampilkan:

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

2. Teruskan token rute ke Navigation SDK menggunakan metode setDestinationsWithToken:completionHandler: dari mapView.navigator. Navigation SDK mendapatkan tujuan dan opsi pemilihan rute dari token rute, sehingga Anda tidak perlu meneruskan titik jalan.

   Mode perjalanan yang ditetapkan di aplikasi Anda, seperti mapView.travelMode, harus berupa salah satu nilai berikut:

   • .driving (GMSNavigationTravelModeDriving): Mengemudi. Ini adalah nilai default, sehingga sebagian besar aplikasi tidak perlu mengubahnya.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): Kendaraan roda dua.

   Mode transportasi lainnya akan membuat permintaan gagal dengan .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Dengan salah satu nilai yang didukung, rute akan menggunakan mode transportasi di token rute Anda. Misalnya, jika aplikasi Anda menggunakan mode mengemudi dan token rute Anda adalah untuk rute kendaraan roda dua, Navigation SDK akan menyediakan rute kendaraan roda dua. Untuk mengonfirmasi mode perjalanan yang digunakan rute, periksa resolvedParameters.travelMode. Untuk mengetahui informasi selengkapnya, lihat Opsi pemilihan rute yang diselesaikan.

3. Periksa status rute di pengendali penyelesaian Anda. Setelah Navigation SDK selesai menghitung rute, SDK ini akan meneruskan GMSNavigationRouteDescription ke pengendali penyelesaian Anda. Jika menemukan rute dari lokasi kendaraan ke tujuan dalam token rute Anda, routeStatus deskripsi rute adalah .OK (GMSRouteStatusOK), dan Anda dapat memulai panduan. Jika tidak, pengendali penyelesaian Anda juga akan menerima NSError yang menjelaskan kegagalan. Contoh:

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

Memeriksa apakah Navigation SDK menerapkan token rute Anda

Status rute .OK berarti Navigation SDK menemukan rute, tetapi belum tentu rute yang Anda rencanakan. Untuk memeriksa apakah rute sesuai dengan rute yang Anda rencanakan, ikuti langkah-langkah berikut di pengendali penyelesaian:

1. Pastikan routeStatus deskripsi rute adalah .OK. Navigation SDK memberikan detail token rute hanya jika menemukan rute. Untuk mengetahui informasi selengkapnya, lihat Langkah 2.

2. Dapatkan routeTokenExecutionDetails deskripsi rute, objek yang sesuai dengan protokol GMSNavigationRouteTokenExecutionDetails. Jika server tidak memberikan detail token rute, properti ini adalah nil.

3. Periksa properti tokenExecutionStatus dari detail eksekusi. Jika berwarna .tokenSuccessfullyApplied, rute tersebut cocok dengan rute yang Anda rencanakan. Status lainnya berarti rute mungkin berbeda dari rute yang Anda rencanakan. Untuk mengetahui informasi selengkapnya tentang setiap status, lihat Nilai status eksekusi token.

4. Opsional: Jika statusnya .tokenSuccessfullyApplied, periksa properti resolvedParameters dari detail eksekusi yang sama untuk melihat opsi pemilihan rute yang digunakan rute, seperti apakah rute tersebut menghindari jalan tol. Untuk mengetahui informasi selengkapnya, lihat Opsi pemilihan rute yang diselesaikan.

Nilai status eksekusi token

Jika routeStatus adalah .OK, Anda dapat memulai panduan dengan status eksekusi token apa pun. Status ini memberi tahu Anda apakah rute mengikuti rute yang Anda rencanakan.

Jika rute tidak harus mengikuti rute yang Anda rencanakan dan rute yang tepat penting, misalnya, karena Anda menggunakannya untuk menghitung harga, catat statusnya atau minta token rute baru dari lokasi kendaraan saat ini.

Opsi pemilihan rute yang diselesaikan

resolvedParameters adalah objek yang sesuai dengan protokol GMSNavigationRouteTokenResolvedParameters, atau nil jika opsi pemilihan rute tidak tersedia. Tag tersebut memiliki properti berikut:

• travelMode: Mode perjalanan yang digunakan rute, seperti .driving (GMSNavigationTravelModeDriving). Navigation SDK juga melaporkan .driving saat rute menggunakan mode perjalanan yang tidak memiliki nilai yang cocok, atau saat mode perjalanan tidak tersedia.
• avoidTolls: Apakah rute menghindari jalan tol.
• avoidHighways: Apakah rute menghindari jalan raya.
• avoidFerries: Apakah rute menghindari kapal feri.
• avoidTunnels: Apakah rute dihitung untuk menghindari terowongan jika memungkinkan.
• avoidVignettes: Negara tempat rute dihitung untuk menghindari vinyet tol jika memungkinkan, sebagai kode wilayah dua huruf CLDR Unicode, seperti CH untuk Swiss.
• rerouteStrategy: Strategi yang digunakan backend pemilihan rute untuk menghitung rute baru selama perjalanan. Strategi mencakup .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), yang menggunakan parameter pemilihan rute dalam token rute Anda untuk menghitung rute baru.

Jika status eksekusi token bukan .tokenSuccessfullyApplied, Navigation SDK hanya akan melaporkan travelMode, avoidTolls, avoidHighways, dan avoidFerries. Properti lainnya memiliki nilai default, meskipun Anda meminta untuk menghindari terowongan atau vinyet tol saat meminta token rute: avoidTunnels adalah false (NO), avoidVignettes kosong, dan rerouteStrategy adalah .unknown (GMSNavigationRerouteStrategyUnknown).

Contoh

Contoh kode berikut menunjukkan cara merencanakan rute menggunakan token rute, memeriksa apakah Navigation SDK menerapkan token, dan memulai panduan.

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

Skenario multi-perhentian

Anda dapat mengonfigurasi maksimum 25 titik jalan.

Navigation SDK tidak otomatis melanjutkan ke tujuan berikutnya. Saat kendaraan tiba di titik jalan, panggil continueToNextDestinationWithCompletion: untuk memulai leg perjalanan berikutnya. Hal ini juga berlaku untuk token rute yang memiliki titik jalan perantara. Saat Anda melanjutkan ke tujuan berikutnya, Navigation SDK akan terus mengikuti rute dari token rute Anda, bukan merencanakan rute baru.

Cara token rute dan Navigation SDK berinteraksi

Berikut cara Navigation SDK menangani rute yang Anda rencanakan:

• Mengganti tujuan yang ditetapkan sebelumnya.

• Menggunakan lokasi awal kendaraan.

• Menyesuaikan dengan kondisi jalan dan lalu lintas. Lihat Alasan rute yang direncanakan mungkin tidak diikuti secara persis.

• Menggunakan opsi pemilihan rute yang ditetapkan dalam token rute Anda, bukan setelan berikut di aplikasi Anda, termasuk saat menghitung rute baru selama perjalanan:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • Mode perjalanan yang ditetapkan di aplikasi Anda

• Mengikuti setelan ini saat menghitung atau menyesuaikan rute:

  • Tujuan rute dari token rute Anda, seperti rute hemat energi atau rute terpendek. Jika harus menyesuaikan rute, Navigation SDK akan menggunakan tujuan rute yang Anda tentukan saat meminta token rute.
  • Opsi terkait titik jalan dari token rute Anda, seperti preferensi sisi jalan.