Lorsque vous suivez un trajet, votre application grand public affiche la position 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 lorsqu'il est terminé.
Ce document explique comment fonctionne ce processus.
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 clients 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 client et 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 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.
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?, ) { // ... } // ... })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 cesse de suivre un trajet lorsqu'il n'est plus nécessaire, par exemple lorsque le conducteur marque le trajet comme TERMINÉ dans le backend. L'arrêt du partage de parcours évite les requêtes réseau inutiles vers Fleet Engine et les fuites de mémoire.
Utilisez JourneySharingSession pour arrêter de suivre le trajet, comme illustré 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 du trajet. Les messages d'erreur respectent 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 du suivi d'un trajet :
| 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}. Le provider_id doit être l'ID du projet Cloud appartenant au fournisseur de services. |
| 401 | UNAUTHENTICATED | Vous recevez cette erreur si aucun identifiant d'authentification n'est valide. Par exemple, si le jeton JWT est signé sans ID de trajet ou s'il a expiré. |
| 403 | PERMISSION_DENIED | Cette erreur s'affiche si le client ne dispose pas des autorisations suffisantes (par exemple, 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 à zéro ou le taux 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 (c'est-à-dire que le délai demandé ne suffit pas au serveur pour traiter la requête) et que la requête n'a pas abouti dans le délai imparti. |
Gérer les erreurs du SDK Consumer
Le SDK Consumer envoie les 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 renvoyé 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 Codes d'état et leur utilisation dans gRPC.
Java
Vous pouvez extraire un code d'état gRPC qui fournit des détails sur l'erreur à partir de l'élément 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 détails sur l'erreur à partir de l'élément 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 réseau ou des erreurs du serveur. Aucune action de votre part n'est requise pour les résoudre. Le SDK Consumer s'en remet automatiquement.
| Code d'état | Description |
|---|---|
| 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'un changement d'état se produit dans l'application grand public. |
| INTERRUPTED | |
| DEADLINE_EXCEEDED | Le serveur a mis trop de temps à répondre. |
| UNAVAILABLE | Le serveur n'était pas disponible. Cela est généralement dû à un problème réseau. |
Erreurs client
Les codes d'état suivants correspondent à des erreurs côté client. Vous devez prendre des mesures pour les résoudre. Le SDK Consumer continue d'essayer d'actualiser le trajet jusqu'à ce que vous arrêtiez le partage du trajet, mais il ne se rétablira pas tant que vous n'aurez pas pris de mesures.
| Code d'état | Description |
|---|---|
| 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 trajet n'a jamais été créé. |
| PERMISSION_DENIED | L'application grand public ne dispose pas des autorisations suffisantes. Cette erreur se produit dans les cas suivants :
|
| RESOURCE_EXHAUSTED | Le quota de ressources est de zéro ou le débit du 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 lorsqu'il a expiré. |