API обзора маршрутов — это продукт решения последней мили для парка транспортных средств, созданный на основе DriverSDK. С его помощью вы можете получать информацию о маршруте для данного транспортного средства либо однократно, либо постоянно, используя прослушиватель обновлений. API обзора маршрутов поддерживает следующие виды информации:
- Полный план маршрута, включая места остановок транспортных средств, время в пути, расстояния
- Полилиния маршрута между каждой остановкой.
В этом документе описаны шаги интеграции с API для вашего приложения.
Предварительные условия
- Вы должны запускать приложение Android, используя альфа- канал DriverSDK v4.1.0 или выше . Альфа-канал доступен с помощью
transportation-driver-alpha
для идентификатора артефакта Maven. - API использует информацию о маршруте, предоставленную Fleet Engine через API доставки. Это можно предоставить либо через API в DriverSDK (
DeliveryDriverApi
), либо непосредственно в Fleet Engine.
Этапы интеграции
В этом разделе описаны основные шаги, необходимые для интеграции вашего приложения-драйвера Android с API. Эти инструкции имеют следующие предположения:
- У вас есть приложение для Android, которое уже интегрировано с Driver SDK.
- Вы инициализировали
DeliveryDriverApi
в своем приложении с помощью объекта контекста, который вы можете найти.
Подробности см. в разделе «Начало работы с Driver SDK для Android» .
Шаг 0 — Настройка маршрута
Вы можете пропустить этот шаг, если вы уже настроили Fleet Engine и можете создавать остановки транспортных средств и задачи доставки.
Чтобы загрузить информацию об остановке и задании в Fleet Engine, вам понадобится средство доставки, назначенное действительному маршруту. Это связано с тем, что API обзора маршрутов требует действительных маршрутов для получения данных. Действительные маршруты состоят из ряда путевых точек и остановок, а остановка может существовать только в том случае, если с ней связана хотя бы одна связанная задача. Дополнительную информацию см. в руководстве по интеграции API Fleet Engine .
Шаг 1. Инициализируйте API
После того как вы создадите действительный маршрут со связанными остановками и задачами, вы сможете инициализировать API обзора маршрута. Инициализация обеспечивает основу, необходимую для соединения между Fleet Engine и API. API обзора маршрутов следует инициализировать с тем же объектом контекста, который вы использовали для инициализации DeliveryDriverApi
в DriverSDK, поскольку этот объект ссылается на тот же идентификатор транспортного средства, определенный ранее в вашем объекте DriverContext
. В следующем примере показано, как создать экземпляр RouteOverviewApi
.
RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
api = RouteOverviewApi.createInstance(context);
}
Шаг 2. Зарегистрируйте транспортное средство для событий изменения маршрута.
Теперь, когда вы инициализировали API, вы можете использовать объект VehicleRouteOverview
для взаимодействия с возможностями обзора маршрута. Это позволяет вашему приложению использовать информацию о маршруте, которую вы предоставили во время настройки маршрута. Используйте прослушиватель событий API для облегчения обновления событий и получения маршрутов.
Событие изменения маршрута происходит всякий раз, когда обновляется путь к любой из остановок, назначенных транспортному средству, перестановка остановки или когда Fleet Engine обновляет информацию о расчетном времени прибытия.
vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
// handle route update events
});
Шаг 3. Включите API
Теперь, когда вы готовы использовать информацию о маршруте, вам необходимо включить API, чтобы он мог реагировать на события транспортного средства. Помните, что API инициализируется в отключенном состоянии, чтобы избежать ненужного потребления пропускной способности сети.
VehicleRouteOverview.setRouteOverviewEnabled(истина);
Вы можете приостановить эти обновления в любое время, вызвав тот же метод со значением false
.
Шаг 4. Нарисуйте маршрут на карте Google.
Получив список RouteToVehicleStop
, вы можете использовать его в своем приложении. Например, вы можете нарисовать полилинию маршрута в экземпляре Google Map. В следующем фрагменте кода показан пример, который рисует полилинию маршрута на карте и добавляет маркеры поверх каждого местоположения остановки.
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);
}
В результате появится вид, аналогичный показанному на снимке экрана справа:
Шаг 5. Получите снимок маршрута
Если вы хотите, чтобы ваше приложение выполняло однократный вызов для получения снимка текущей информации о маршруте, вы можете использовать следующий метод для получения этих данных:
ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();
Вы можете сделать это вместо подписки на обновления маршрутов через прослушиватели событий.
Шаг 6 – Очистка
Если вашему приложению больше не нужна функция обзора маршрутов, вам следует убедиться, что вы все очистили. Выполнение очистки позволяет избежать ненужного потребления памяти, обработки и сети в вашем приложении.
Удаление определенного прослушивателя событий
Вам следует удалить прослушиватель событий, когда конкретный прослушиватель больше не нужен.
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
Очистить все прослушиватели событий
В рамках процедуры очистки вы можете одновременно удалить все зарегистрированные прослушиватели событий.
vehicleRouteOverview.clearEventListeners();
Очистить экземпляр API обзора маршрутов
Всякий раз, когда обзор маршрута больше не нужен или идентификатор отслеживаемого транспортного средства изменился, вы можете вызвать этот API, чтобы очистить внутренние ссылки.
vehicleRouteOverview.clearInstance();