Cómo seguir un viaje en Android

Cuando sigues un viaje, tu aplicación para consumidores muestra la ubicación del vehículo correspondiente al consumidor. Para ello, tu app debe comenzar a seguir un viaje, actualizar el progreso del viaje y dejar de seguirlo cuando se complete.

En este documento, se explica cómo funciona ese proceso.

Antes de comenzar

Asegúrate de configurar lo siguiente:

• Los servicios de backend para tu aplicación para consumidores están listos, y tus servicios para asignar consumidores a vehículos están operativos.

• Configuraste un mapa para tu app.

Cómo comenzar a seguir un viaje

Cuando tu servidor de backend haga coincidir un consumidor con un vehículo, usa JourneySharingSession para comenzar a seguir el viaje.

En el siguiente código de muestra, se indica cómo comenzar a seguir un viaje después de que se carga la vista.

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

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

Actualiza el progreso del viaje

Para actualizar los detalles del progreso del viaje, como la distancia que debe recorrer el vehículo antes de llegar y la hora estimada de llegada, tu app debe registrar y configurar un objeto de escucha, como se muestra en los siguientes ejemplos.

1. Registra un objeto de escucha en un objeto 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 el objeto de escucha para tu viaje con 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)
   

Cómo dejar de seguir un viaje

Asegúrate de que tu app deje de seguir un viaje cuando ya no sea necesario, como cuando el conductor marca el viaje como COMPLETADO en el backend. Detener el uso compartido del recorrido evita solicitudes de red innecesarias a Fleet Engine y previene las fugas de memoria.

Usa JourneySharingSession para dejar de seguir el viaje, como se muestra en el siguiente código de muestra.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Cómo controlar los errores de viaje

El método onTripRefreshError muestra los errores que se producen durante la supervisión del viaje. Los mensajes de error siguen el estándar de errores de Google Cloud. Para obtener definiciones detalladas de los mensajes de error y todos los códigos de error, consulta la documentación de errores de Google Cloud.

Estos son algunos errores comunes que pueden ocurrir durante la supervisión de viajes:

Cómo controlar los errores del SDK de consumidor

El SDK de consumidor envía errores de actualización de viajes a la aplicación para consumidores con un mecanismo de devolución de llamada. El parámetro de devolución de llamada es un tipo de datos que se devuelve específico de la plataforma (TripUpdateError en Android y NSError en iOS).

Extrae códigos de estado

Los errores que se pasan a la devolución de llamada suelen ser errores de gRPC, y también puedes extraer información adicional de ellos en forma de un código de estado. Para obtener la lista completa de códigos de estado, consulta Códigos de estado y su uso en gRPC.

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

// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
  val code = error.getStatusCode()
}

Interpreta los códigos de estado

Los códigos de estado abarcan dos tipos de errores: los relacionados con el servidor y la red, y los del cliente.

Errores de servidor y de red

Los siguientes códigos de estado corresponden a errores de red o de servidor, y no necesitas realizar ninguna acción para resolverlos. El SDK de consumidor se recupera automáticamente de ellos.

Errores de cliente

Los siguientes códigos de estado son para errores del cliente, y debes tomar medidas para resolverlos. El SDK de consumidor sigue intentando actualizar el viaje hasta que finalices el uso compartido del recorrido, pero no se recuperará hasta que tomes medidas.