Merencanakan rute

Terkadang, Anda mungkin ingin merencanakan rute yang disediakan aplikasi Anda kepada pengguna. Menggunakan token rute dari Routes 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.

Penting: Rute yang dilalui pengemudi dapat berbeda dari rute yang Anda rencanakan. Perubahan kondisi lalu lintas atau jalan, kendaraan yang keluar dari rute yang direncanakan, atau beralih ke rute yang lebih cepat dapat mengubah rute selama perjalanan. Setiap kali Navigation SDK menghitung rute baru, SDK ini akan menggunakan opsi pemilihan rute yang ditetapkan dalam token rute Anda, seperti menghindari jalan tol.

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

Tips: Token rute ditujukan untuk satu tempat asal dan tujuan tertentu serta pada waktu tertentu. Anda harus membuat permintaan Routes API atau Route Optimization API baru untuk mendapatkan token rute baru.

Cara kerja token rute

Anda dapat menggunakan Routes 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 atau Route Optimization API menampilkan token rute terenkripsi yang menyertakan 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.

Tips: Sebagai praktik terbaik, selalu minta token rute baru setiap kali Anda menetapkan tujuan di Navigation SDK, dan rencanakan beberapa variasi untuk menghindari dampak apa pun terhadap bisnis Anda.

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

   • 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 API Routes 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.

Catatan: Anda dapat menentukan nilai asal dan tujuan yang akurat, seperti pintu masuk, dok muatan, atau area penjemputan yang ditentukan, dalam token rute menggunakan token titik navigasi.

Langkah 2: Teruskan token rute ke Navigation SDK

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

   String 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 Navigator.setDestinationsWithToken. Navigation SDK mendapatkan tujuan dan opsi pemilihan rute dari token rute, sehingga Anda tidak perlu meneruskan titik jalan atau mode perjalanan.

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

   Catatan: Jika aplikasi Anda menggunakan Navigation SDK versi sebelum 8.1, gunakan metode setDestinations yang tidak digunakan lagi yang menggunakan CustomRoutesOptions, dan teruskan titik jalan tujuan yang sama dengan yang Anda gunakan untuk membuat token rute.

3. Periksa status rute di callback Anda. Setelah Navigation SDK selesai menghitung rute, SDK ini akan meneruskan RouteDescription ke callback Anda. Jika menemukan rute dari lokasi kendaraan ke tujuan dalam token rute Anda, RouteDescription.getRouteStatus akan menampilkan Navigator.RouteStatus.OK, dan Anda dapat memulai panduan. Contoh:

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

Catatan: Jika Anda perlu melakukan perjalanan dengan rute yang sama lagi, minta token rute baru.

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 cocok dengan rute yang Anda rencanakan, ikuti langkah-langkah berikut dalam callback:

1. Pastikan RouteDescription.getRouteStatus menampilkan Navigator.RouteStatus.OK. Navigation SDK memberikan detail token rute hanya jika menemukan rute. Untuk mengetahui informasi selengkapnya, lihat Langkah 2.

2. Panggil RouteDescription.getRouteTokenExecutionDetails untuk mendapatkan objek RouteTokenExecutionDetails. Jika server tidak memberikan detail token rute, metode ini akan menampilkan null.

3. Panggil getTokenExecutionStatus pada objek RouteTokenExecutionDetails. Jika menampilkan TOKEN_SUCCESSFULLY_APPLIED, rute tersebut cocok dengan rute yang Anda rencanakan. Status lainnya berarti rute mungkin berbeda dari rute yang Anda rencanakan. Untuk informasi selengkapnya tentang setiap status, lihat Nilai status eksekusi token.

4. Opsional: Jika statusnya adalah TOKEN_SUCCESSFULLY_APPLIED, panggil getResolvedParameters pada objek RouteTokenExecutionDetails yang sama untuk memeriksa 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 status rute adalah OK, Anda dapat memulai panduan dengan status eksekusi token apa pun. Status ini memberi tahu Anda apakah rute mengikuti rute yang Anda rencanakan.

Status	Mengikuti rute yang Anda rencanakan	Deskripsi
TOKEN_SUCCESSFULLY_APPLIED	Ya	Navigation SDK menerapkan token rute Anda.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	Belum tentu	Navigation SDK tidak dapat membuat ulang rute yang Anda rencanakan karena lokasi dalam permintaan rute berjarak lebih dari 25 meter dari lokasi yang cocok di token rute Anda. Dengan setDestinationsWithToken, ini berarti perangkat berada lebih dari 25 meter dari titik awal di token rute Anda. Rute tetap mengarah ke tujuan Anda, tetapi Navigation SDK tidak dapat mengonfirmasi bahwa rute tersebut menggunakan opsi pemilihan rute dari token rute Anda, seperti menghindari jalan tol.
TOKEN_IGNORED_OTHER	Belum tentu	Navigation SDK tidak dapat membuat ulang rute yang Anda rencanakan karena alasan lain, misalnya, karena jalan pada rute yang Anda rencanakan ditutup. Rute tetap mengarah ke tujuan Anda, tetapi Navigation SDK tidak dapat mengonfirmasi bahwa rute tersebut menggunakan opsi pemilihan rute dari token rute Anda, seperti menghindari jalan tol.
NO_TOKEN_PROVIDED	Tidak berlaku	Permintaan rute tidak menyertakan token rute.
UNKNOWN	Tidak diketahui	Statusnya tidak diketahui.

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

getResolvedParameters menampilkan objek RouteTokenResolvedParameters, atau null jika opsi pemilihan rute tidak tersedia. RouteTokenResolvedParameters memiliki metode berikut:

• getTravelMode: Mode transportasi yang digunakan rute, seperti RoutingOptions.TravelMode.DRIVING. Navigation SDK juga melaporkan RoutingOptions.TravelMode.DRIVING saat rute menggunakan mode perjalanan yang tidak memiliki nilai yang cocok, atau saat mode perjalanan tidak tersedia.
• getAvoidTolls: Apakah rute menghindari jalan tol.
• getAvoidHighways: Apakah rute menghindari jalan raya.
• getAvoidFerries: Apakah rute menghindari kapal feri.

Contoh

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

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

Catatan: Anda dapat mengonfigurasi maksimum 25 titik jalan.

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:

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

Catatan: Dengan setDestinationsWithToken, Anda tidak meneruskan titik jalan, sehingga Navigation SDK menggunakan tujuan dan opsi titik jalan dari token rute Anda. Untuk menetapkan opsi titik jalan, seperti preferensi sisi jalan atau pemberhentian kendaraan, gunakan kolom sideOfRoad dan vehicleStopover pada titik jalan dalam permintaan Routes API Anda. Asalnya selalu lokasi perangkat, sehingga opsi yang Anda tetapkan pada asal dalam permintaan Routes API tidak berlaku.