Śledź podróż na Androidzie

Podczas śledzenia przejazdu aplikacja dla klienta wyświetla mu lokalizację odpowiedniego pojazdu. Aby to zrobić, aplikacja musi zacząć śledzić podróż, aktualizować postępy w jej trakcie i przestać ją śledzić po jej zakończeniu.

Ten dokument wyjaśnia, jak działa ten proces.

Zanim zaczniesz

Upewnij się, że masz skonfigurowane te elementy:

• Usługi backendu aplikacji dla konsumentów są dostępne, a usługi dopasowywania konsumentów do pojazdów działają.

• W swojej aplikacji masz skonfigurowaną mapę.

Rozpoczęcie śledzenia podróży

Gdy serwer backendu dopasuje klienta do pojazdu, użyj opcji JourneySharingSession, aby rozpocząć śledzenie podróży.

Poniższy przykładowy kod pokazuje, jak rozpocząć śledzenie przejazdu po załadowaniu widoku.

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

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()
  }
}

Aktualizacja postępu podróży

Aby aktualizować szczegóły postępu podróży, takie jak odległość, jaką pojazd musi pokonać przed przybyciem, oraz przewidywany czas przybycia, aplikacja musi zarejestrować i skonfigurować listenera w sposób pokazany w tych przykładach.

1. Zarejestruj detektor zdarzeń w obiekcie 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. Skonfiguruj słuchacza na potrzeby swojej podróży za pomocą 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)
   

Przerwanie obserwowania podróży

Upewnij się, że aplikacja przestaje śledzić przejazd, gdy nie jest już potrzebna, np. gdy przejazd został oznaczony przez kierowcę jako ZAMKNIĘTY. Zatrzymanie udostępniania trasy zapobiega wysyłaniu niepotrzebnych żądań sieciowych do Fleet Engine i zapobiega wyciekom pamięci.

Aby przestać śledzić podróż, użyj elementu JourneySharingSession, jak pokazano w poniższym przykładowym kodzie.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

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

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

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Obsługa błędów dotyczących podróży

Metoda onTripRefreshError wyświetla błędy występujące podczas monitorowania podróży. Komunikaty o błędach są zgodne ze standardem błędów Google Cloud. Szczegółowe definicje komunikatów o błędach i wszystkie kody błędów znajdziesz w dokumentacji Google Cloud dotyczącej błędów.

Oto kilka typowych błędów, które mogą wystąpić podczas monitorowania przejazdu:

Obsługa błędów Consumer SDK

Pakiet Consumer SDK wysyła błędy aktualizacji podróży do aplikacji konsumenta za pomocą mechanizmu wywołania zwrotnego. Parametr wywołania zwrotnego to typ zwracanych danych, który zależy od platformy (TripUpdateErrorna Androidzie i NSErrorna iOS).

Wyodrębnianie kodów stanu

Błędy przekazywane do funkcji wywołania zwrotnego to zwykle błędy gRPC, z których możesz też wyodrębnić dodatkowe informacje w postaci kodu stanu. Pełną listę kodów stanu znajdziesz w artykule Kody stanu i ich użycie w gRPC.

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

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

Interpretowanie kodów stanu

Kody stanu obejmują 2 rodzaje błędów: błędy związane z serwerem i siecią oraz błędy po stronie klienta.

Błędy serwera i sieci

Podane niżej kody stanu dotyczą błędów sieci lub serwera. Nie musisz podejmować żadnych działań, aby je rozwiązać. Pakiet Consumer SDK automatycznie odzyskuje je z tych plików.

Błędy klienta

Poniższe kody stanu dotyczą błędów po stronie klienta. Aby je naprawić, musisz podjąć odpowiednie działania. Pakiet SDK dla konsumentów będzie próbować odświeżyć podróż, dopóki nie zakończysz udostępniania podróży, ale nie odzyska jej stanu, dopóki nie podejmiesz działań.