Suivre un trajet sur Android

Lorsque vous suivez un trajet, votre application grand public affiche l'emplacement du véhicule approprié pour le consommateur. Pour ce faire, votre application doit commencer à suivre un trajet, mettre à jour sa progression et arrêter de le suivre une fois qu'il est terminé.

Ce document explique comment ce processus fonctionne.

Avant de commencer

Assurez-vous d'avoir configuré les éléments suivants :

• Les services de backend de votre application grand public sont en place et vos services de mise en relation des consommateurs avec les véhicules sont opérationnels.

• Vous avez configuré une carte pour votre application.

Commencer à suivre un trajet

Lorsque votre serveur backend met en relation un consommateur avec un véhicule, utilisez JourneySharingSession pour commencer à suivre le trajet.

L'exemple de code suivant montre comment commencer à suivre un trajet une fois la vue chargée.

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

Mettre à jour la progression du trajet

Pour mettre à jour les détails de la progression du trajet, tels que la distance que le véhicule doit parcourir avant d'arriver et l'heure d'arrivée prévue, votre application doit enregistrer et configurer un écouteur, comme illustré dans les exemples suivants.

1. Enregistrez un écouteur sur un objet 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. Configurez l'écouteur pour votre trajet à l'aide de 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)
   

Arrêter de suivre un trajet

Assurez-vous que votre application arrête de suivre un trajet lorsqu'il n'est plus nécessaire, par exemple lorsque le trajet est marqué comme TERMINÉ dans le backend par le conducteur. L'arrêt du partage de trajet évite les requêtes réseau inutiles adressées à Fleet Engine et empêche les fuites de mémoire.

Utilisez JourneySharingSession pour arrêter de suivre le trajet, comme illustré dans l'exemple de code suivant.

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

Gérer les erreurs de trajet

La méthode onTripRefreshError met en évidence les erreurs qui se produisent lors de la surveillance du trajet. Les messages d'erreur suivent la norme Google Cloud Error. Pour obtenir des définitions détaillées des messages d'erreur et tous les codes d'erreur, consultez la documentation sur les erreurs Google Cloud.

Voici quelques erreurs courantes qui peuvent se produire lors de la surveillance du trajet :

Gérer les erreurs du SDK consommateur

Le SDK consommateur envoie des erreurs de mise à jour du trajet à l'application grand public à l'aide d'un mécanisme de rappel. Le paramètre de rappel est un type de retour spécifique à la plate-forme ( TripUpdateError sur Android et NSError sur iOS).

Extraire les codes d'état

Les erreurs transmises au rappel sont généralement des erreurs gRPC, et vous pouvez également en extraire des informations supplémentaires sous la forme d'un code d'état. Pour obtenir la liste complète des codes d'état, consultez Codes d'état et leur utilisation dans 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()
}

Interpréter les codes d'état

Les codes d'état couvrent deux types d'erreurs : les erreurs liées au serveur et au réseau, et les erreurs côté client.

Erreurs de serveur et de réseau

Les codes d'état suivants concernent les erreurs de réseau ou de serveur, et vous n'avez aucune action à entreprendre pour les résoudre. Le SDK consommateur les corrige automatiquement.

Erreurs client

Les codes d'état suivants concernent les erreurs client, et vous devez prendre des mesures pour les résoudre. Le SDK consommateur continue de réessayer d'actualiser le trajet jusqu'à ce que vous mettiez fin au partage de trajet, mais il ne récupérera pas tant que vous n'aurez pas pris de mesures.