Quando segui un viaggio, la tua app consumer mostra al consumatore la posizione del veicolo appropriato. Per farlo, l'app deve iniziare a seguire un viaggio, aggiornarne l'avanzamento e interrompere il monitoraggio al termine.
Questo documento illustra il funzionamento della procedura.
Prima di iniziare
Assicurati di aver configurato quanto segue:
I servizi di backend per la tua app consumer sono attivi e i servizi per abbinare i consumatori ai veicoli sono operativi.
Hai configurato una mappa per la tua app.
Iniziare a seguire un viaggio
Quando il server di backend associa un consumatore a un veicolo, utilizza
JourneySharingSession per iniziare a seguire il viaggio.
Il seguente codice di esempio mostra come iniziare a seguire un viaggio dopo il caricamento della visualizzazione.
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()
}
}
Aggiorna la tua posizione
Per aggiornare i dettagli sull'avanzamento del viaggio, ad esempio la distanza che il veicolo deve percorrere prima dell'arrivo e l'orario di arrivo stimato, l'app deve registrare e configurare un ascoltatore come mostrato negli esempi seguenti.
Registra un listener su un oggetto
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?, ) { // ... } // ... })Configura l'ascoltatore per il tuo viaggio utilizzando
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)
Smettere di seguire un viaggio
Assicurati che l'app interrompa il monitoraggio di una corsa quando non è più necessaria, ad esempio quando la corsa viene contrassegnata come COMPLETA nel backend dal conducente. Interrompere la condivisione del percorso evita richieste di rete non necessarie a Fleet Engine e previene le fughe di memoria.
Utilizza JourneySharingSession per interrompere il monitoraggio del viaggio, come mostrato nel seguente codice di esempio.
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()
}
}
Gestire gli errori di blocco
Il metodo onTripRefreshError restituisce gli errori che si verificano durante il monitoraggio
delle corse. I messaggi di errore seguono lo standard di errore di Google Cloud. Per definizioni dettagliate dei messaggi di errore e per tutti i codici di errore, consulta la documentazione relativa agli errori di Google Cloud.
Di seguito sono riportati alcuni errori comuni che possono verificarsi durante il monitoraggio delle corse:
| HTTP | RPC | Descrizione |
|---|---|---|
| 400 | INVALID_ARGUMENT | Il client ha specificato un nome di viaggio non valido. Il nome della corsa deve essere nel formato providers/{provider_id}/trips/{trip_id}. provider_id deve essere l'ID del progetto Cloud di proprietà del fornitore di servizi. |
| 401 | NON AUTENTICATO | Questo errore viene visualizzato se non esistono credenziali di autenticazione valide. Ad esempio, se il token JWT è firmato senza un ID corsa o se è scaduto. |
| 403 | PERMISSION_DENIED | Questo errore viene visualizzato se il client non dispone delle autorizzazioni sufficienti (ad esempio, un utente con il ruolo Consumer tenta di chiamare updateTrip), se il token JWT non è valido o se l'API non è abilitata per il progetto client. Il token JWT potrebbe mancare o essere firmato con un ID corsa che non corrisponde all'ID corsa richiesto. |
| 429 | RESOURCE_EXHAUSTED | La quota di risorse è pari a zero o la frequenza del traffico supera il limite. |
| 503 | UNAVAILABLE | Servizio non disponibile. In genere il server non è attivo. |
| 504 | DEADLINE_EXCEEDED | Scadenza richiesta superata. Questo errore si verifica solo se chi chiama imposta una scadenza più breve di quella predefinita del metodo (ovvero la scadenza richiesta non è sufficiente per l'elaborazione della richiesta da parte del server) e la richiesta non è stata completata entro la scadenza. |
Gestire gli errori dell'SDK consumer
L'SDK Consumer invia gli errori di aggiornamento dei viaggi all'app consumer utilizzando un meccanismo di callback. Il parametro di callback è un tipo restituito specifico della piattaforma (
TripUpdateError
su Android e
NSError
su iOS).
Codici di stato dell'estrazione
Gli errori passati al callback sono in genere errori gRPC dai quali puoi anche estrarre ulteriori informazioni sotto forma di codice di stato. Per l'elenco completo dei codici di stato, consulta Codici di stato e relativo utilizzo in gRPC.
Java
Puoi estrarre un codice di stato gRPC che fornisce i dettagli sull'errore dall'TripUpdateError restituito da onTripUpdateError().
// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
Status.Code code = error.getStatusCode();
}
Kotlin
Puoi estrarre un codice di stato gRPC che fornisce dettagli sull'errore
da TripUpdateError restituito da onTripUpdateError().
// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
val code = error.getStatusCode()
}
Interpreta i codici di stato
I codici di stato coprono due tipi di errori: errori relativi al server e alla rete ed errori lato client.
Errori del server e della rete
I seguenti codici di stato si riferiscono a errori di rete o del server e non è necessario intraprendere alcuna azione per risolverli. dall'SDK consumer viene recuperato automaticamente.
| Codice di stato | Descrizione |
|---|---|
| INTERROTTO | Il server ha smesso di inviare la risposta. Normalmente questo è causato da un problema del server. |
| CANCELLATO | Il server ha terminato la risposta in uscita. Questo accade normalmente quando l'app viene inviata in background o quando si verifica un cambiamento di stato nell'app consumer . |
| INTERROTTO | |
| DEADLINE_EXCEEDED | Il server ha impiegato troppo tempo per rispondere. |
| UNAVAILABLE | Il server non era disponibile. In genere questo problema è causato da un problema di rete. |
Errori client
I seguenti codici di stato si riferiscono a errori del client e devi intervenire per risolverli. L'SDK consumer continua a riprovare ad aggiornare il percorso fino al termine della condivisione, ma il recupero non verrà ripristinato finché non intervieni.
| Codice di stato | Descrizione |
|---|---|
| INVALID_ARGUMENT | L'app consumer ha specificato un nome della corsa non valido. Il nome della corsa deve
essere nel formato providers/{provider_id}/trips/{trip_id}.
|
| NOT_FOUND | Il viaggio non è mai stato creato. |
| PERMISSION_DENIED | L'app Consumer non dispone di autorizzazioni sufficienti. Questo errore si verifica quando:
|
| RESOURCE_EXHAUSTED | La quota di risorse è pari a zero o la frequenza del flusso di traffico supera il limite di velocità. |
| NON AUTENTICATO | La richiesta non è riuscita a eseguire l'autenticazione a causa di un token JWT non valido. Questo errore si verifica quando il token JWT viene firmato senza un ID di viaggio o quando il token JWT è scaduto. |