La API de Route Overview es un producto de Last Mile Fleet Solution integrado en el DriverSDK. Con él, puedes recuperar información de rutas para un vehículo determinado, ya sea como una recuperación única o de forma continua con un objeto de escucha para 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, la duración del viaje y las distancias
- Ruta de 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 4.1.0 o una versión posterior. El canal alfa está disponible mediante
transportation-driver-alpha
para el artifactId de Maven. - La API consume la información de ruta que proporciona Fleet Engine a través de la API de Deliveries. Esto 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 para Android con 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.
Consulta Cómo comenzar a utilizar el SDK de Driver para Android para obtener más detalles.
Paso 0: Configuración de la ruta
Puedes omitir este paso si ya configuraste Fleet Engine y puedes crear paradas de vehículos y tareas de entrega.
Para cargar la información de paradas y tareas en Fleet Engine, necesitas un vehículo de entrega asignado 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 Fleet 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 el 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 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 ocurre cada vez que se actualiza la ruta a cualquiera de las paradas asignadas al vehículo, se reordena 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 ya puedes consumir información de rutas, debes habilitar la API para permitir que responda a los eventos de vehículos. Recuerda que la API se inicializa en un estado inhabilitada para evitar el consumo innecesario de ancho de banda de la red.
vehicleRouteOverview.setRouteOverviewEnabled(true);
Puedes pausar estas actualizaciones en cualquier momento llamando al mismo método con el valor de 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 polilínea para 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 la ruta en la vista de mapa y se agregan marcadores sobre la ubicación de cada 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);
}
Esto da como resultado una vista similar a la de la captura de pantalla que se muestra a la derecha:
Paso 5: Obtén una instantánea de la ruta
Si quieres que tu app realice 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 hacer esto en lugar de suscribirte a actualizaciones de ruta 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, asegúrate de realizar una limpieza. Esta limpieza evita memoria, procesamiento y consumo de red innecesarios en tu aplicación.
Cómo quitar un objeto de escucha de eventos específico
Debes quitar un objeto de escucha de eventos cuando ya no sea necesario un objeto de escucha específico.
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
Borrar todos los objetos de escucha de eventos
Como parte de la 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 Route Overview
Cuando ya no se necesite la descripción general de la ruta o haya cambiado el ID del vehículo del que se está realizando el seguimiento, puedes llamar a esta API para borrar las referencias internas.
vehicleRouteOverview.clearInstance();