API Route Overview

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

Captura de tela mostrando uma imagem de uma visão geral do trajeto

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