API Route Panoramica

Questo prodotto o questa funzionalità è sperimentale (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le offerte pre-GA sono coperte dai Termini di servizio specifici di Google Maps Platform. Per maggiori informazioni, consulta le descrizioni della fase di lancio.

Importante: l'API Route Overview è attualmente disponibile solo su Android.

L'API Route Overview è un prodotto Last Mile Fleet Solution basato su DriverSDK. che ti consente di recuperare le informazioni sul percorso per un determinato veicolo, come recupero una tantum o continuativa, utilizzando un listener per gli aggiornamenti. L'API Route Overview supporta i seguenti tipi di informazioni:

• Piano completo del percorso, inclusi la posizione delle fermate dei veicoli, i tempi di percorrenza e le distanze
• Il percorso della polilinea tra ogni fermata.

Questo documento descrive i passaggi per l'integrazione con l'API per la tua applicazione.

Prerequisiti

• Devi eseguire l'applicazione Android utilizzando il canale alpha di DriverSDK 4.1.0 o versioni successive. Il canale alpha è disponibile utilizzando transportation-driver-alpha per l'ID artefatto Maven.
• L'API utilizza le informazioni sul percorso fornite da Fleet Engine tramite l'API Deliveries. Può essere fornito tramite le API su DriverSDK (DeliveryDriverApi) o direttamente a Fleet Engine.

Passaggi per l'integrazione

Questa sezione illustra i passaggi di base necessari per integrare la tua app driver Android con l'API. Queste istruzioni si basano sui seguenti presupposti:

• Hai già un'app per Android che è già integrata con l'SDK Driver
• Hai inizializzato DeliveryDriverApi nella tua app con un oggetto di contesto che puoi trovare

Per maggiori dettagli, consulta la guida introduttiva all'SDK Driver per Android.

Passaggio 0 - Configurazione del percorso

Puoi saltare questo passaggio se hai già configurato Fleet Engine e puoi creare soste e attività di consegna dei veicoli.

Per caricare le informazioni su fermate e attività su Fleet Engine, devi avere un veicolo per le consegne assegnato a un percorso valido. Questo perché l'API Route Overview richiede route valide per recuperare i dati. Le route valide sono composte da una serie di tappe e fermate e una fermata può esistere solo se ha almeno un'attività associata. Per ulteriori informazioni, consulta la guida all'integrazione delle API Fleet Engine.

Passaggio 1 - Inizializza l'API

Dopo aver stabilito un percorso valido con fermate e attività associate, puoi inizializzare l'API Route Overview. L'inizializzazione fornisce il framework necessario per la connessione tra Fleet Engine e l'API. L'API Route Panoramica deve essere inizializzata con lo stesso oggetto di contesto che hai utilizzato per inizializzare DeliveryDriverApi in DriverSDK, poiché l'oggetto si riferisce allo stesso ID veicolo definito in precedenza nell'oggetto DriverContext. L'esempio seguente illustra come creare un'istanza di RouteOverviewApi.

RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

Nota: quando inizializza l'API Route Overview, questa viene automaticamente impostata su uno stato disabilitato per evitare di consumare larghezza di banda non necessaria durante il completamento della configurazione.

Passaggio 2: registra il veicolo per gli eventi di cambio di percorso

Ora che hai inizializzato l'API, puoi utilizzare l'oggetto VehicleRouteOverview per interagire con le funzionalità di panoramica delle route. Ciò consente alla tua applicazione di utilizzare le informazioni sulle route fornite durante la configurazione delle route. Utilizza il listener di eventi dell'API per facilitare gli aggiornamenti degli eventi e il recupero del percorso.

Un evento di modifica del percorso si verifica ogni volta che il percorso verso una delle fermate assegnate al veicolo viene aggiornato, una fermata viene riorganizzata o quando Fleet Engine aggiorna le informazioni sull'orario di arrivo stimato.

vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

Passaggio 3 - Abilita l'API

Ora che è tutto pronto per utilizzare le informazioni sulle route, devi abilitare l'API per consentirle di rispondere agli eventi del veicolo. Ricorda che l'API è inizializzata in stato disabilitata per evitare un consumo non necessario di larghezza di banda di rete.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Puoi mettere in pausa questi aggiornamenti in qualsiasi momento chiamando lo stesso metodo con il valore false.

Passaggio 4: traccia il percorso su una mappa di Google

Una volta ottenuto un elenco di RouteToVehicleStop, puoi utilizzarlo nella tua applicazione. Ad esempio, puoi tracciare il percorso della polilinea di percorso in un'istanza di Google Maps. Il seguente snippet di codice mostra un esempio che traccia la polilinea del percorso nella visualizzazione mappa e aggiunge indicatori in cima a ogni posizione della fermata.

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

Viene visualizzata una visualizzazione simile a quella dello screenshot a destra:

Passaggio 5 - Ottieni un'istantanea della route

Se vuoi che l'app effettui una chiamata una tantum per recuperare uno snapshot delle informazioni di route attuali, puoi utilizzare il seguente metodo per recuperare i dati:

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

Puoi farlo invece di iscriverti agli aggiornamenti del percorso tramite i listener di eventi.

Passaggio 6 - Pulisci

Se la tua app non ha più bisogno della funzionalità di panoramica del percorso, devi assicurarti di aver eseguito la pulizia. La pulizia evita il consumo di memoria, elaborazione e rete inutili nell'applicazione.

Rimuovere un listener di eventi specifico

Quando un listener di eventi specifico non è più necessario, devi rimuovere un listener di eventi.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Cancella tutti i listener di eventi

Nell'ambito della tua routine di pulizia, puoi rimuovere tutti i diversi listener di eventi registrati contemporaneamente.

vehicleRouteOverview.clearEventListeners();

Cancella istanza API Route Overview

Ogni volta che la panoramica del percorso non è più necessaria o l'ID del veicolo monitorato è cambiato, puoi chiamare questa API per cancellare i riferimenti interni.

vehicleRouteOverview.clearInstance();