Quando segui un viaggio, la tua app consumer mostra la posizione del veicolo appropriato per il consumatore. Per farlo, l'app deve iniziare a seguire un viaggio, aggiornarne l'avanzamento e interrompere il monitoraggio al termine.
Questo documento illustra il funzionamento di questa procedura.
Prima di iniziare
Assicurati di aver configurato quanto segue:
I servizi di backend per la tua app per consumatori sono implementati e i tuoi servizi per l'associazione dei consumatori ai veicoli sono operativi.
Hai configurato una mappa per la tua app.
Iniziare a seguire un viaggio
Quando il tuo server di backend associa un consumer a un veicolo, usa
JourneySharingSession per iniziare a seguire il percorso.
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()
}
}
Aggiornare l'avanzamento della corsa
Per aggiornare i dettagli della corsa, ad esempio la distanza necessaria al veicolo prima dell'arrivo e dell'orario di arrivo stimato, la tua app deve Registra e configura un listener 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 il listener per il percorso 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 la tua app smetta di seguire un percorso quando non è più necessaria, ad esempio quando la corsa è contrassegnata come COMPLETATA dal conducente al backend. 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 mostra gli errori che si verificano durante il monitoraggio dei viaggi. I messaggi di errore rispettano 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 percorso non valido. Il nome della corsa deve seguire le
formato providers/{provider_id}/trips/{trip_id}. provider_id deve essere l'ID del progetto cloud di proprietà del fornitore di servizi. |
| 401 | UNAUTHENTICATED | Questo errore viene visualizzato se non sono presenti credenziali di autenticazione valide. Ad esempio, se il token JWT è firmato senza un ID corsa o se è scaduto. |
| 403 | PERMISSION_DENIED | Ricevi questo errore se il client non dispone di autorizzazioni sufficienti (ad esempio, un utente con il ruolo consumer tenta di chiamare updateTrip), se il token JWT non è valido o l'API non è abilitata per il progetto client. Il token JWT potrebbe non essere presente o il token potrebbe 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 di 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 il chiamante imposta più breve della scadenza predefinita del metodo (ovvero, la scadenza richiesta non è sufficiente per consentire al server di elaborare la richiesta). 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 di ritorno specifico della piattaforma (
TripUpdateError su Android e
NSError su iOS).
Estrarre i codici di stato
Gli errori passati al callback sono in genere errori gRPC e puoi anche ricavarne informazioni aggiuntive sotto forma di codice di stato. Per per l'elenco completo dei codici di stato, consulta Codici di stato e loro utilizzo in gRPC.
Java
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
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()
}
Interpretare 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. L'SDK Consumer si riprende automaticamente da questi errori.
| Codice di stato | Descrizione |
|---|---|
| ABORTED | Il server ha smesso di inviare la risposta. In genere, questo problema è causato da un problema del server. |
| CANCELLATO | Il server ha terminato la risposta in uscita. Questa operazione normalmente
si verifica quando
l'app viene inviata in background o quando si verifica un cambiamento di stato App consumer. |
| INTERRUPTED | |
| 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 riguardano gli errori del client e devi intervenire per risolverle. L'SDK consumer continua a riprovare ad aggiornare il percorso finché condivisione del percorso, ma non si ripristina finché non intervieni.
| Codice di stato | Descrizione |
|---|---|
| INVALID_ARGUMENT | L'app Consumer ha specificato un nome di corsa non valido. Il nome della corsa deve seguire il 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 velocità del flusso di traffico supera la limite di velocità. |
| UNAUTHENTICATED | L'autenticazione della richiesta non è riuscita a causa di un token JWT non valido. Questo errore si verifica quando il token JWT è firmato senza un ID corsa o quando il token JWT è scaduto. |