Suivre un trajet sur Android

Sélectionnez une plate-forme : Android iOS JavaScript

Lorsque vous suivez un trajet, votre application grand public affiche l'emplacement du véhicule approprié. Pour ce faire, votre application doit commencer à suivre un trajet, mettre à jour la progression du trajet et arrêter de suivre un trajet lorsqu'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 correspondance des consommateurs avec des véhicules sont opérationnels.

  • Vous avez configuré une carte pour votre application.

Suivre un trajet

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

L'exemple de code suivant montre comment commencer à suivre un trajet après le chargement de la vue.

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

Mettre à jour la progression du trajet

Pour mettre à jour les informations sur la progression du trajet, telles que la distance que le véhicule doit parcourir avant l'arrivée et l'heure d'arrivée estimée, votre application doit enregistrer et configurer un écouteur, comme indiqué 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 de 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)

Ne plus suivre un trajet

Assurez-vous que votre application cesse 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. Arrêter le partage de trajets évite les requêtes réseau inutiles envoyées à Fleet Engine et empêche les fuites de mémoire.

Utilisez JourneySharingSession pour arrêter le suivi du trajet, comme indiqué dans l'exemple de code suivant.

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

Gérer les erreurs de trajet

La méthode onTripRefreshError affiche les erreurs qui se produisent lors de la surveillance des trajets. Les messages d'erreur respectent la norme Google Cloud. Pour obtenir des définitions détaillées des messages d'erreur et de 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 des trajets :

HTTP RPC Description
400 INVALID_ARGUMENT Le client a spécifié un nom de trajet non valide. Le nom du trajet doit respecter le format providers/{provider_id}/trips/{trip_id}. provider_id doit être l'ID du projet Cloud appartenant au fournisseur de services.
401 UNAUTHENTICATED Cette erreur s'affiche si aucun identifiant d'authentification valide n'est disponible. Par exemple, si le jeton JWT est signé sans ID de trajet ou si le jeton JWT a expiré.
403 PERMISSION_DENIED Vous recevez cette erreur si le client ne dispose pas d'autorisations suffisantes (par exemple, si un utilisateur disposant du rôle de consommateur tente d'appeler updateTrip), si le jeton JWT n'est pas valide ou si l'API n'est pas activée pour le projet client. Le jeton JWT est peut-être manquant ou signé avec un ID de trajet qui ne correspond pas à l'ID de trajet demandé.
429 RESOURCE_EXHAUSTED Le quota de ressources est nul ou le débit de trafic dépasse la limite.
503 UNAVAILABLE Service indisponible. Généralement, le serveur est inactif.
504 DEADLINE_EXCEEDED Délai de requête dépassé. Cette erreur ne se produit que si l'appelant définit un délai plus court que le délai par défaut de la méthode (le délai demandé ne suffit pas pour que le serveur traite la demande) et si la requête ne s'est pas terminée dans le délai.

Gérer les erreurs du SDK client

Le SDK Consumer envoie des erreurs de mise à jour de 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. 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 la section Codes d'état et utilisation dans gRPC.

Java

Vous pouvez extraire un code d'état gRPC qui fournit des informations sur l'erreur à partir de l'TripUpdateError renvoyé par onTripUpdateError().

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

Kotlin

Vous pouvez extraire un code d'état gRPC qui fournit des informations sur l'erreur à partir de l'TripUpdateError renvoyé par onTripUpdateError().

// 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 correspondent à des erreurs de réseau ou de serveur. Aucune action de votre part n'est requise pour les résoudre. Le SDK Consumer les récupère automatiquement.

Code d'étatDescription
ABORTED Le serveur a cessé d'envoyer la réponse. Cela est généralement dû à un problème de serveur.
ANNULÉ Le serveur a mis fin à la réponse sortante. Cela se produit généralement lorsque l'application est envoyée en arrière-plan ou lorsqu'il y a un changement d'état dans l'application consommateur
.
INTERRUPTED
DEADLINE_EXCEEDED Le serveur a mis trop de temps à répondre.
UNAVAILABLE Le serveur n'était pas disponible. Ce problème est généralement dû à un problème réseau.

Erreurs client

Les codes d'état suivants correspondent à des erreurs client. Vous devez prendre des mesures pour les résoudre. Le SDK Consumer continue de tenter de mettre à jour le trajet jusqu'à ce que vous arrêtiez le partage du trajet, mais il ne sera pas récupéré tant que vous ne l'aurez pas fait.

Code d'étatDescription
INVALID_ARGUMENT L'application grand public a spécifié un nom de trajet non valide. Le nom du trajet doit respecter le format providers/{provider_id}/trips/{trip_id}.
NOT_FOUND Le voyage n'a jamais été créé.
PERMISSION_DENIED L'application grand public ne dispose pas d'autorisations suffisantes. Cette erreur se produit dans les cas suivants :
  • L'application grand public ne dispose pas d'autorisations
  • Le SDK Consumer n'est pas activé pour le projet dans la console Google Cloud.
  • Le jeton JWT est manquant ou non valide.
  • Le jeton JWT est signé avec un ID de trajet qui ne correspond pas au trajet demandé.
RESOURCE_EXHAUSTED Le quota de ressources est nul ou le débit de trafic dépasse la limite de vitesse.
UNAUTHENTICATED L'authentification de la requête a échoué en raison d'un jeton JWT non valide. Cette erreur se produit lorsque le jeton JWT est signé sans ID de trajet ou lorsque le jeton JWT a expiré.