API Route Overview

A API Route Overview é um produto da Last Mile Fleet Solution criado no DriverSDK. Com ela, você pode recuperar informações de trajeto para um determinado veículo como uma busca única ou continuamente usando um listener para atualizações. A API Route Overview é compatível com os seguintes tipos de informação:

  • Plano de trajeto completo, incluindo locais de parada dos 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

  • Execute o 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 informações de rota fornecidas pelo Fleet Engine pela API Deliveries. Isso pode ser fornecido pelas APIs no DriverSDK (DeliveryDriverApi) ou diretamente ao Fleet Engine.

Etapas de integração

Esta seção aborda as etapas básicas necessárias para integrar seu app de driver do Android à API. Essas instruções têm as seguintes premissas:

  • Você tem um app Android que já foi integrado ao SDK do Driver.
  • Inicializou o DeliveryDriverApi no app com um objeto de contexto que pode ser encontrado

Consulte Primeiros passos com o SDK do Driver para Android para saber mais.

Etapa 0: configuração do trajeto

É possível pular esta etapa se você já configurou o Fleet Engine e pode criar paradas de veículos e tarefas de entrega.

Para carregar as informações de parada e tarefa no Fleet Engine, você precisa de um veículo de entrega atribuído a uma rota válida. Isso ocorre porque a API Route Overview exige rotas válidas para buscar dados. Os trajetos válidos são compostos 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 Fleet Engine para mais informações.

Etapa 1: inicializar a API

Depois de estabelecer uma rota válida com paradas e tarefas associadas, você pode inicializar 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 de 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: registre o veículo para eventos de mudança de trajeto

Agora que a API foi inicializada, use o objeto VehicleRouteOverview para interagir com os recursos de visão geral da rota. Isso permite que seu aplicativo consuma as informações de trajeto fornecidas durante a configuração dele. 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 do 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 conseguir uma lista de RouteToVehicleStops, você poderá 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 em 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);
}

Captura de tela mostrando uma visão geral do trajeto

Isso resulta em uma visualização semelhante à captura de tela à direita:

Etapa 5: receber um snapshot do trajeto

Caso queira que seu app emita uma chamada única para recuperar um snapshot das informações do trajeto atual, use o seguinte método para recuperar esses dados:

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

Você pode fazer isso em vez de se inscrever para rotear atualizações por meio de listeners de eventos.

Etapa 6: limpeza

Se o app não precisar mais da funcionalidade de visão geral do trajeto, verifique se você fez a limpeza. Isso evita o consumo desnecessário de memória, processamento e rede 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 da rotina de limpeza, você pode remover todos os listeners de eventos diferentes registrados de uma vez.

vehicleRouteOverview.clearEventListeners();

Limpar instância da API 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 rastreado for alterado, você poderá chamar essa API para limpar as referências internas.

vehicleRouteOverview.clearInstance();