A API Route Overview é um produto da Last Mile Fleet Solution criado no DriverSDK. Com ele, você recupera informações de trajeto de um determinado veículo como uma busca única ou de forma contínua usando um listener para atualizações. A API Route Overview aceita os seguintes tipos de informações:
- Plano de trajeto completo, incluindo locais das paradas de veículos, tempos de viagem e distâncias
- O caminho da polilinha do trajeto entre cada parada.
Este documento descreve as etapas de integração com a API para seu aplicativo.
Pré-requisitos
- Você precisa executar seu app Android usando o canal alfa
do DriverSDK v4.1.0 ou mais recente. O Canal Alfa está disponível
usando
transportation-driver-alpha
para o artifactId do Maven. - A API consome as informações de trajeto fornecidas pelo Fleet Engine pela
API Deliveries. Isso pode ser fornecido pelas APIs no DriverSDK
(
DeliveryDriverApi
) ou diretamente no Fleet Engine.
Etapas de integração
Esta seção aborda as etapas básicas necessárias para integrar seu app de driver para Android à API. Estas instruções têm as seguintes suposições:
- Você tem um app Android já integrado ao SDK do Driver
- Você inicializou o
DeliveryDriverApi
no seu app com um objeto de contexto que pode encontrar.
Para ver mais detalhes, consulte Primeiros passos com o SDK do Driver para Android.
Etapa 0: configuração do trajeto
Pule esta etapa se já tiver configurado o Fleet Engine e criar paradas de veículo e tarefas de entrega.
Para carregar as informações de paradas e tarefas no Fleet Engine, você precisa de um veículo de entrega atribuído a um trajeto válido. Isso ocorre porque a API Route Overview requer rotas válidas para buscar dados. Rotas válidas são compostas por uma série de waypoints e paradas, e uma parada só pode existir se tiver pelo menos uma tarefa associada. Consulte o Guia de integração da API do Fleet Engine para mais informações.
Etapa 1: inicializar a API
Depois de estabelecer um trajeto válido com paradas e tarefas associadas, inicialize a API Route Overview. A inicialização fornece o framework
necessário para a conexão entre o Fleet Engine e a API. A API Route
Overview precisa ser inicializada com o mesmo objeto de contexto usado para
inicializar DeliveryDriverApi
no DriverSDK, já que o objeto se refere ao
mesmo ID do veículo definido anteriormente no objeto DriverContext
. O exemplo
a seguir ilustra como criar uma instância de RouteOverviewApi
.
RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
api = RouteOverviewApi.createInstance(context);
}
Etapa 2: registrar o veículo para eventos de mudança de trajeto
Agora que você inicializou a API, use o objeto VehicleRouteOverview
para interagir com os recursos de visão geral do trajeto. Isso permite que o
aplicativo consuma as informações de trajeto fornecidas durante a configuração.
Use o listener de eventos da API para facilitar as atualizações de eventos e a recuperação de rotas.
Um evento de mudança de trajeto ocorre sempre que o caminho para qualquer uma das paradas atribuídas ao veículo é atualizado, uma parada é reorganizada ou quando o Fleet Engine atualiza as informações de HEC.
vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
// handle route update events
});
Etapa 3: ativar a API
Agora que está tudo pronto para consumir informações de trajeto, ative a API para permitir que ela responda a eventos do veículo. Lembre-se de que a API é inicializada em um estado desativada para evitar o consumo desnecessário de largura de banda da rede.
vehicleRouteOverview.setRouteOverviewEnabled(true);
É possível pausar essas atualizações a qualquer momento chamando o mesmo método com o
valor de false
.
Etapa 4: desenhar o trajeto em um mapa do Google
Depois de receber uma lista de RouteToVehicleStop
s, você pode usá-la no
aplicativo. Por exemplo, você pode desenhar o caminho da polilinha do trajeto em uma instância do Google Maps. O snippet de código a seguir mostra um exemplo que desenha a polilinha do trajeto na visualização de mapa e adiciona marcadores a cada local 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);
}
O resultado é uma visualização semelhante à captura de tela à direita:
Etapa 5: gerar um resumo do trajeto
Se você quiser que seu app emita uma chamada única para recuperar um snapshot das informações do trajeto atual, use o método abaixo para extrair esses dados:
ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();
Você pode fazer isso em vez de se inscrever para atualizações de rota por meio de listeners de eventos.
Etapa 6: limpeza
Se o app não precisar mais da funcionalidade de visão geral do trajeto, faça uma limpeza. A limpeza evita o consumo de memória, processamento e rede desnecessários no aplicativo.
Remover um listener de eventos específico
Remova um listener de eventos quando um listener específico não for mais necessário.
vehicleRouteOverview.removeOnRouteChangedEventListener(listener);
Limpar todos os listeners de eventos
Como parte de sua rotina de limpeza, você pode remover todos os diferentes listeners de eventos registrados de uma só vez.
vehicleRouteOverview.clearEventListeners();
Instância da API Clear Route Overview
Sempre que a visão geral do trajeto não for mais necessária ou o ID do veículo que está sendo monitorado mudar, você poderá chamar essa API para limpar referências internas.
vehicleRouteOverview.clearInstance();