Mengikuti perjalanan di Android

Pilih platform: Android iOS JavaScript

Saat Anda mengikuti perjalanan, aplikasi konsumen Anda akan menampilkan lokasi kendaraan yang sesuai untuk konsumen. Untuk melakukannya, aplikasi harus dimulai mengikuti perjalanan, memperbarui progres perjalanan, dan berhenti mengikuti perjalanan saat selesai.

Dokumen ini membahas cara kerja proses tersebut.

Sebelum memulai

Pastikan Anda telah menyiapkan hal-hal berikut:

  • Layanan backend untuk aplikasi konsumen sudah tersedia dan layanan Anda untuk mencocokkan konsumen dengan kendaraan bersifat operasional.

  • Anda telah menyiapkan peta untuk aplikasi.

Mulai mengikuti perjalanan

Saat server backend Anda mencocokkan konsumen dengan kendaraan, gunakan JourneySharingSession untuk mulai mengikuti perjalanan menggunakan fitur berbagi perjalanan.

Kode contoh berikut menunjukkan cara memulai {i>user sharing<i} setelah pemuatan tampilan.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    String tripName = ...;
    TripModelManager tripModelManager = consumerApi.getTripModelManager();
    TripModel tripModel = tripModelManager.getTripModel(tripName);

    // Create a JourneySharingSession instance based on the TripModel.
    JourneySharingSession session = JourneySharingSession.createInstance(tripModel);

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session);

    // Register for trip update events.
    tripModel.registerTripCallback(new TripModelCallback() {
      @Override
      public void onTripETAToNextWaypointUpdated(
          TripInfo tripInfo, @Nullable Long timestampMillis) {
        // ...
      }

      @Override
      public void onTripActiveRouteRemainingDistanceUpdated(
          TripInfo tripInfo, @Nullable Integer distanceMeters) {
        // ...
      }

      // ...
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    val tripName = "tripName"
    val tripModelManager = consumerApi.getTripModelManager()
    val tripModel = tripModelManager.getTripModel(tripName)

    // Create a JourneySharingSession instance based on the TripModel.
    val session = JourneySharingSession.createInstance(tripModel)

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session)

    // Register for trip update events.
    tripModel.registerTripCallback(
      object : TripModelCallback() {
        override fun onTripETAToNextWaypointUpdated(
          tripInfo: TripInfo,
          timestampMillis: Long?,
        ) {
          // ...
        }

        override fun onTripActiveRouteRemainingDistanceUpdated(
          tripInfo: TripInfo,
          distanceMeters: Int?,
        ) {
          // ...
        }

      // ...
    })
  }

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Perbarui progres perjalanan

Untuk memperbarui detail progres perjalanan, seperti jarak yang harus ditempuh kendaraan perjalanan sebelum kedatangan dan perkiraan waktu tiba, aplikasi Anda harus mendaftarkan dan mengonfigurasi pemroses seperti yang ditunjukkan pada contoh berikut.

  1. Daftarkan pemroses di objek TripModel.

    Java

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
    String tripName = ...;
    TripModelManager tripModelManager = consumerApi.getTripModelManager();
    TripModel tripModel = tripModelManager.getTripModel(tripName);
    
    // Create a JourneySharingSession instance based on the TripModel.
    JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
    
    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session);
    
    // Register for trip update events.
    tripModel.registerTripCallback(new TripModelCallback() {
    @Override
    public void onTripETAToNextWaypointUpdated(
            TripInfo tripInfo, @Nullable Long timestampMillis) {
          // ...
    }
    
    @Override
    public void onTripActiveRouteRemainingDistanceUpdated(
            TripInfo tripInfo, @Nullable Integer distanceMeters) {
          // ...
    }
    
    // ...
    });
    

    Kotlin

    // Create a TripModel instance for listening to updates to the trip specified by this trip name.
    val tripName = "tripName"
    val tripModelManager = consumerApi.getTripModelManager()
    val tripModel = tripModelManager.getTripModel(tripName)
    
    // Create a JourneySharingSession instance based on the TripModel.
    val session = JourneySharingSession.createInstance(tripModel)
    
    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session)
    
    // Register for trip update events.
    tripModel.registerTripCallback(
      object : TripModelCallback() {
        override fun onTripETAToNextWaypointUpdated(
          tripInfo: TripInfo,
          timestampMillis: Long?,
        ) {
          // ...
        }
    
        override fun onTripActiveRouteRemainingDistanceUpdated(
          tripInfo: TripInfo,
          distanceMeters: Int?,
        ) {
          // ...
        }
    
      // ...
    })
    
  2. Konfigurasi pemroses untuk perjalanan Anda menggunakan TripModelOptions.

    Java

    // Set refresh interval to 2 seconds.
    TripModelOptions tripOptions =
          TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
    tripModel.setTripModelOptions(tripOptions);
    

    Kotlin

    // Set refresh interval to 2 seconds.
    val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
    tripModel.setTripModelOptions(tripOptions)
    

Berhenti mengikuti perjalanan

Pastikan aplikasi Anda berhenti mengikuti perjalanan saat tidak lagi diperlukan, seperti seperti saat perjalanan ditandai SELESAI di bagian latar belakang oleh pengemudi. Menghentikan perjalanan berbagi menghindari permintaan jaringan yang tidak perlu ke Fleet Engine dan mencegah memori kebocoran informasi.

Gunakan JourneySharingSession untuk berhenti mengikuti perjalanan seperti yang ditunjukkan di kode contoh berikut ini.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Menangani error perjalanan

Metode onTripRefreshError menampilkan error yang terjadi selama perjalanan pemantauan model. Pesan error mengikuti standar Error Google Cloud. Untuk detail definisi pesan error dan semua kode error, lihat artikel Error Google Cloud dokumentasi tambahan.

Berikut beberapa error umum yang dapat terjadi selama pemantauan perjalanan:

HTTP PPK Deskripsi
400 INVALID_ARGUMENT Klien menentukan nama perjalanan yang tidak valid. Nama perjalanan harus mengikuti format providers/{provider_id}/trips/{trip_id}. provider_id harus berupa ID Project Cloud yang dimiliki oleh penyedia layanan.
401 TIDAK DIAUTENTIKASI Anda menerima error ini jika tidak ada kredensial autentikasi yang valid. Misalnya, jika token JWT ditandatangani tanpa ID perjalanan atau token JWT masa berlakunya telah berakhir.
403 PERMISSION_DENIED Anda menerima error ini jika klien tidak memiliki izin yang memadai (misalnya, pengguna dengan peran konsumen mencoba memanggil updateTrip), jika token JWT tidak valid, atau API tidak diaktifkan untuk project klien. Token JWT mungkin tidak ada atau token ditandatangani dengan ID perjalanan yang tidak cocok dengan ID perjalanan yang diminta.
429 RESOURCE_EXHAUSTED Kuota resource nol atau rasio traffic melebihi batas.
503 UNAVAILABLE Layanan tidak tersedia. Biasanya server mati.
504 DEADLINE_EXCEEDED Batas waktu permintaan terlampaui. Error ini hanya terjadi jika pemanggil menyetel yang lebih pendek dari batas waktu {i>default<i} metode (yaitu, batas waktu yang diminta tidak cukup bagi server untuk memproses permintaan) dan permintaan tidak selesai dalam batas waktu yang ditentukan.

Menangani Error SDK Konsumen

Consumer SDK mengirim error update perjalanan ke aplikasi konsumen menggunakan callback mekanisme atensi. Parameter callback adalah jenis nilai yang ditampilkan khusus platform ( TripUpdateError di Android, dan NSError di iOS).

Mengekstrak kode status

Error yang diteruskan ke callback biasanya merupakan error gRPC, dan Anda juga dapat mengekstrak informasi tambahan dari mereka dalam bentuk kode status. Untuk mengetahui daftar lengkap kode status, lihat Kode status dan penggunaannya di gRPC.

Java

Anda dapat mengekstrak kode status gRPC yang memberikan detail tentang error dari TripUpdateError yang ditampilkan dari onTripUpdateError().

// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
  Status.Code code = error.getStatusCode();
}

Kotlin

Anda dapat mengekstrak kode status gRPC yang memberikan detail tentang error dari TripUpdateError yang ditampilkan dari onTripUpdateError().

// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
  val code = error.getStatusCode()
}

Menafsirkan kode status

Kode status mencakup dua jenis kesalahan: kesalahan server dan jaringan, dan {i>client-side<i}.

Error server dan jaringan

Kode status berikut ditujukan untuk kesalahan jaringan atau server, dan Anda tidak perlu mengambil tindakan apa pun untuk menyelesaikannya. Consumer SDK secara otomatis pulih dari serangan tersebut.

Kode StatusDeskripsi
ABORTED Server berhenti mengirim respons. Hal ini biasanya disebabkan oleh masalah server.
DIBATALKAN Server menghentikan respons keluar. Hal ini biasanya terjadi ketika
aplikasi dikirim ke latar belakang, atau saat ada perubahan status pada
Aplikasi konsumen.
INTERRUPTED
DEADLINE_EXCEEDED Server membutuhkan waktu terlalu lama untuk merespons.
UNAVAILABLE Server tidak tersedia. Hal ini biasanya disebabkan oleh masalah jaringan.

Error klien

Kode status berikut ditujukan untuk error klien, dan Anda harus mengambil tindakan untuk menyelesaikannya. Consumer SDK terus mencoba memuat ulang perjalanan hingga Anda berbagi perjalanan akhir, tetapi hal ini tidak akan dipulihkan sampai Anda mengambil tindakan.

Kode StatusDeskripsi
INVALID_ARGUMENT Aplikasi Konsumen menentukan nama perjalanan yang tidak valid; Nama perjalanan harus ikuti format providers/{provider_id}/trips/{trip_id}.
NOT_FOUND Perjalanan tidak pernah dibuat.
PERMISSION_DENIED Aplikasi Konsumen tidak memiliki izin yang memadai. Error ini terjadi saat:
  • Aplikasi Konsumen tidak memiliki izin
  • Consumer SDK tidak diaktifkan untuk project di Konsol Google Cloud.
  • Token JWT tidak ada atau tidak valid.
  • Token JWT ditandatangani dengan ID perjalanan yang tidak cocok dengan perjalanan yang diminta.
RESOURCE_EXHAUSTED Kuota resource nol, atau laju aliran traffic melebihi batas kecepatan.
TIDAK DIAUTENTIKASI Autentikasi permintaan gagal karena token JWT tidak valid. Error ini terjadi saat token JWT ditandatangani tanpa ID perjalanan, atau saat token JWT telah berakhir masa berlakunya.