Seguire un viaggio in Android

Seleziona la piattaforma: Android iOS JavaScript

Quando segui un viaggio, la tua app consumer mostra la posizione del veicolo appropriato per il consumatore. Per farlo, l'app deve essere avviata seguire un viaggio, aggiornarne i progressi e smettere di seguire un percorso quando si verifica vengono completate.

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 abbina un consumer a un veicolo, usa JourneySharingSession per iniziare a seguire il viaggio utilizzando la condivisione del percorso.

Il codice di esempio seguente mostra come iniziare la condivisione del percorso dopo il caricamenti di visualizzazioni.

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 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.

  1. 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?,
        ) {
          // ...
        }
    
      // ...
    })
    
  2. 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 la tua app smetta di seguire un percorso quando non è più necessaria, ad esempio quando la corsa è contrassegnata come COMPLETATA dal conducente al backend. Interruzione del percorso la condivisione evita richieste di rete non necessarie a Fleet Engine e impedisce la memoria di fughe di notizie.

Usa JourneySharingSession per smettere di seguire il percorso come mostrato in seguendo il codice campione.

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 segnala errori che si verificano durante la corsa il monitoraggio. I messaggi di errore seguono lo standard di errore di Google Cloud. Per dettagli le definizioni dei messaggi di errore e tutti i codici di errore, consulta Errori di Google Cloud documentazione.

Di seguito sono riportati alcuni errori comuni che possono verificarsi durante il monitoraggio dei viaggi:

HTTP RPC Descrizione
400 INVALID_ARGUMENT Il client ha specificato un nome percorso non valido. Il nome della corsa deve seguire il formato providers/{provider_id}/trips/{trip_id}. La provider_id deve essere l'ID del progetto Cloud di proprietà di il provider 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 il token JWT. è 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 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 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 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 errori di aggiornamento della corsa all'app consumer utilizzando un callback meccanismo di attenzione. Il parametro di callback è un tipo restituito specifico della piattaforma ( TripUpdateError su Android NSError su iOS).

Codici di stato dell'estrazione

Gli errori passati al callback sono in genere errori gRPC e puoi anche estrarre 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 i 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 i 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 riguardano errori di rete o del server e non occorre fare nulla per risolverli. L'SDK consumer viene li recupera.

Codice di statoDescrizione
INTERROTTO Il server ha smesso di inviare la risposta. Questo è causato di solito da un problema con il server.
CANCELLATO Il server ha terminato la risposta in uscita. Questo accade normalmente quando l'app viene inviata in background o quando si verifica una modifica di stato nell'app consumer.
INTERRUPTED
DEADLINE_EXCEEDED Il server ha impiegato troppo tempo per rispondere.
UNAVAILABLE Il server non era disponibile. Questo è causato di solito da una rete problema.

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 recupererà finché non intervieni.

Codice di statoDescrizione
INVALID_ARGUMENT L'app Consumer ha specificato un nome di viaggio non valido. Il nome del viaggio deve seguire il formato providers/{provider_id}/trips/{trip_id}.
NOT_FOUND Il viaggio non è mai stato creato.
PERMISSION_DENIED L'app consumer non ha autorizzazioni sufficienti. Questo errore si verifica quando:
  • L'app consumer non dispone delle autorizzazioni
  • L'SDK consumer non è abilitato per il progetto in Google Cloud Google Cloud.
  • Token JWT mancante o non valido.
  • Il token JWT è firmato con un ID corsa che non corrisponde alla percorso richiesto.
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 si verifica quando il token JWT è firmato senza un ID trip oppure quando il token JWT è scaduto.