API de descripción general de la ruta

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

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

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