API de descripción general de la ruta

La API de Route Overview es un producto de la solución Last Mile Fleet compilado en DriverSDK. Con ella, puedes recuperar información de las rutas para un vehículo determinado, ya sea como una recuperación única o de manera continua usando un objeto de escucha para las actualizaciones. La API de Route Overview admite los siguientes tipos de información:

  • Plan de ruta completo, incluidas las ubicaciones de las paradas de los vehículos, los tiempos de viaje y las distancias
  • Es la trayectoria de la polilínea de la ruta entre cada parada.

En este documento, se describen los pasos de integración con la API para tu aplicación.

Requisitos previos

  • Debes ejecutar tu aplicación para Android con el canal alfa del DriverSDK v4.1.0 o versión posterior. El canal alfa está disponible mediante transportation-driver-alpha para el artifactId de Maven.
  • La API consume información de las rutas que proporciona Fleet Engine a través de la API de Deliveries. Se puede proporcionar a través de las APIs de DriverSDK (DeliveryDriverApi) o directamente a Fleet Engine.

Pasos para la integración

En esta sección, se describen los pasos básicos necesarios para integrar tu app de controlador de Android a la API. Estas instrucciones tienen las siguientes suposiciones:

  • Tienes una app para Android existente que ya se integró con el SDK de Driver.
  • Inicializaste el DeliveryDriverApi en tu app con un objeto de contexto que puedes encontrar.

Si quieres obtener más información, consulta Cómo comenzar a usar el SDK de Driver para Android.

Paso 0: Configuración de la ruta

Puedes omitir este paso si ya configuraste Fleet Engine y puedes crear tareas de entrega y paradas de vehículos.

Para cargar la información de las paradas y las tareas en Fleet Engine, debes asignar un vehículo de entrega a una ruta válida. Esto se debe a que la API de Route Overview requiere rutas válidas para recuperar datos. Las rutas válidas se componen de una serie de puntos de referencia y paradas, y una parada solo puede existir si tiene al menos una tarea asociada. Consulta la guía de integración de la API de Flet Engine para obtener más información.

Paso 1: Inicializa la API

Una vez que estableces una ruta válida con paradas y tareas asociadas, puedes inicializar la API de Route Overview. La inicialización proporciona el framework necesario para la conexión entre Fleet Engine y la API. La API de Route Overview debe inicializarse con el mismo objeto de contexto que usaste para inicializar DeliveryDriverApi en DriverSDK, ya que el objeto hace referencia al mismo ID de vehículo definido antes en tu objeto DriverContext. En el siguiente ejemplo, se muestra cómo crear una instancia de RouteOverviewApi.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Paso 2: Registra el vehículo para los eventos de cambio de ruta

Ahora que inicializaste la API, puedes usar el objeto VehicleRouteOverview para interactuar con las capacidades de descripción general de la ruta. Esto permite que tu aplicación consuma la información de la ruta que proporcionaste durante la configuración de la ruta. Usa el objeto de escucha de eventos de la API para facilitar las actualizaciones de eventos y la recuperación de rutas.

Un evento de cambio de ruta se produce cada vez que se actualiza la ruta a cualquiera de las paradas asignadas al vehículo, se reorganiza una parada o cuando Fleet Engine actualiza la información de la hora de llegada estimada.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Paso 3: Habilita la API

Ahora que estás listo para consumir información de rutas, debes habilitar la API para permitirle responder a los eventos del vehículo. Recuerda que la API se inicializa en estado inhabilitado para evitar el consumo innecesario de ancho de banda de red.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Puedes pausar estas actualizaciones en cualquier momento llamando al mismo método con el valor false.

Paso 4: Dibuja la ruta en un mapa de Google Maps

Una vez que obtengas una lista de RouteToVehicleStop, podrás usarla en tu aplicación. Por ejemplo, puedes dibujar la ruta de la polilínea de la ruta en una instancia de Google Maps. En el siguiente fragmento de código, se muestra un ejemplo en el que se dibuja la polilínea de ruta en la vista de mapa y se agregan marcadores en la parte superior de cada ubicación de parada.

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

Captura de pantalla en la que se muestra una imagen de descripción general de la ruta

Esto da como resultado una vista similar a la captura de pantalla de la derecha:

Paso 5: Obtén un resumen de la ruta

Si deseas que la app emita una llamada única para recuperar una instantánea de la información de la ruta actual, puedes usar el siguiente método para recuperar esos datos:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

Puedes hacerlo en lugar de suscribirte a actualizaciones de rutas a través de objetos de escucha de eventos.

Paso 6: Limpieza

Si tu app ya no necesita la funcionalidad de descripción general de la ruta, debes asegurarte de realizar una limpieza. Esta limpieza evita el consumo innecesario de memoria, procesamiento y red en tu aplicación.

Quita un objeto de escucha de eventos específico

Debes quitar un objeto de escucha de eventos cuando ya no sea necesario uno específico.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Borra todos los objetos de escucha de eventos

Como parte de tu rutina de limpieza, puedes quitar todos los objetos de escucha de eventos diferentes registrados a la vez.

vehicleRouteOverview.clearEventListeners();

Borrar la instancia de la API de descripción general de rutas

Cuando ya no se necesita la descripción general de la ruta o se cambia el ID del vehículo del que se hace seguimiento, puedes llamar a esta API para borrar las referencias internas.

vehicleRouteOverview.clearInstance();