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 per 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 consente di recuperare le informazioni sul percorso per un determinato veicolo, come recupero una tantum o in modo continuo utilizzando un listener per gli aggiornamenti. L'API Route Overview supporta i seguenti tipi di informazioni:

• Piano completo del percorso, inclusi luoghi delle fermate, tempi di percorrenza e distanze.
• Il percorso della polilinea tra ogni fermata.

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

Prerequisiti

• La tua applicazione per Android deve essere in esecuzione utilizzando il canale alpha di DriverSDK versione 4.1.0 o superiore. Il canale alfa è disponibile utilizzando transportation-driver-alpha per l'artefactId Maven.
• L'API utilizza le informazioni sulle route 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 un'app Android esistente già integrata con l'SDK Driver
• Hai inizializzato DeliveryDriverApi nell'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 attività di fermata dei veicoli e consegna.

Per caricare le informazioni su fermate e attività in Fleet Engine, devi avere un veicolo per la consegna assegnato a un percorso valido. Questo perché l'API Route Overview richiede route valide per recuperare i dati. I percorsi validi sono costituiti da una serie di waypoint e fermate e una fermata può esistere solo se è associata ad almeno un'attività. Per ulteriori informazioni, consulta la guida all'integrazione dell'API Fleet Engine.

Passaggio 1: inizializza l'API

Dopo aver stabilito una route valida 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 Overview deve essere inizializzata con lo stesso oggetto di contesto utilizzato per inizializzare DeliveryDriverApi nel DriverSDK, poiché l'oggetto fa riferimento 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 inizializzi l'API Route Overview, questo viene impostato automaticamente su uno stato disabilitato per evitare di consumare larghezza di banda non necessaria mentre completi le parti di 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 all'applicazione di utilizzare le informazioni sul percorso che hai fornito durante la configurazione del percorso. Utilizza il listener di eventi API per facilitare gli aggiornamenti di eventi e il recupero delle route.

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 relative all'orario di arrivo stimato.

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

Passaggio 3 - Abilita l'API

Ora che è tutto pronto per utilizzare le informazioni sul percorso, 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 richiamando lo stesso metodo con il valore false.

Passaggio 4: traccia il percorso su una mappa di Google Maps

Una volta ottenuto un elenco di RouteToVehicleStop, puoi utilizzarlo nella tua applicazione. Ad esempio, puoi tracciare il percorso della polilinea della route 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 nella parte superiore della posizione di ciascuna 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);
}

Il risultato è una visualizzazione simile allo screenshot a destra:

Passaggio 5 - Ottieni uno snapshot della route

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

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

Puoi farlo anziché sottoscrivere gli aggiornamenti del percorso tramite listener di eventi.

Passaggio 6 - Esegui la pulizia

Se la tua app non richiede più la funzionalità di panoramica delle route, assicurati di aver eseguito la pulizia. La pulizia evita il consumo superfluo di memoria, elaborazione e rete nell'applicazione.

Rimuovere un listener di eventi specifico

Devi rimuovere un listener di eventi quando un listener specifico non è più necessario.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Cancella tutti i listener di eventi

Come parte della routine di pulizia puoi rimuovere contemporaneamente tutti i diversi listener di eventi registrati.

vehicleRouteOverview.clearEventListeners();

Cancella istanza API panoramica percorso

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

vehicleRouteOverview.clearInstance();