Seguire una spedizione

Ora che hai configurato JavaScript Consumer SDK per le attività pianificate, puoi seguire una spedizione con la tua app per utenti finali. Questo documento illustra i seguenti passaggi chiave di questo processo:

  • Inizializzare una mappa e visualizzare il viaggio condiviso
  • Aggiornare e seguire l'avanzamento del percorso
  • Interrompere il monitoraggio di una spedizione
  • Gestire gli errori di monitoraggio della spedizione

Configurare una mappa

Per seguire il ritiro o la consegna di una spedizione nella tua app web, devi caricare una mappa e creare un'istanza di Consumer SDK per iniziare a monitorare la spedizione. Puoi caricare una nuova mappa o utilizzarne una esistente. Poi, utilizza la funzione di inizializzazione per creare un'istanza di Consumer SDK in modo che la visualizzazione mappa corrisponda alla posizione dell'articolo monitorato.

Caricare una nuova mappa utilizzando l'API Maps JavaScript di Google

Per creare una nuova mappa, carica l'API Maps JavaScript nella tua app web. L'esempio seguente mostra come caricare l'API Maps JavaScript, abilitare l'SDK e attivare il controllo di inizializzazione.

  • Il parametro callback esegue la funzione initMap dopo il caricamento dell'API.
  • L'attributo defer consente al browser di continuare a eseguire il rendering del resto della pagina durante il caricamento dell'API.

Utilizza la funzione initMap per creare un'istanza di Consumer SDK. Ad esempio:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

Caricare una mappa esistente

Puoi anche caricare una mappa esistente creata dall'API Maps JavaScript di Google, ad esempio una che utilizzi già.

Supponiamo, ad esempio, di avere una pagina web con un'entità google.maps.Map standard su cui viene mostratore un indicatore come definito nel seguente codice HTML. Di seguito è riportata la mappa che utilizza la stessa funzione initMap nel callback alla fine:

    <!DOCTYPE html>
    <html>
      <head>
        <style>
           /* Set the size of the div element that contains the map */
          #map {
            height: 400px;  /* The height is 400 pixels */
            width: 100%;  /* The width is the width of the web page */
           }
        </style>
      </head>
      <body>
        <h3>My Google Maps Demo</h3>
        <!--The div element for the map -->
        <div id="map"></div>
        <script>
        // Initialize and add the map
        function initMap() {
          // The location of Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // The map, initially centered at Mountain View, CA.
          var map = new google.maps.Map(document.getElementById('map'));
          map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});

          // The marker, now positioned at Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * The callback parameter executes the initMap() function.
        -->
        <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
        </script>
      </body>
    </html>

Creare un'istanza di un fornitore di posizioni di spedizione

Utilizza il fornitore di posizioni di spedizione, insieme al recuperatore di token di autorizzazione che hai definito in precedenza, per iniziare a ricevere dati da Fleet Engine.

Questi esempi mostrano come creare un'istanza del fornitore di posizioni.

JavaScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

TypeScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Visualizzare il viaggio condiviso

Per visualizzare l'avanzamento di un'attività pianificata, inizializza la relativa visualizzazione, che imposta il frame della mappa in modo che corrisponda alla posizione del viaggio monitorato. L'avanzamento viene quindi fornito da Consumer SDK dopo aver ricevuto le informazioni da Fleet Engine.

Suggerimenti:

  1. Assicurati che la pagina contenga un elemento <div> che contenga la visualizzazione mappa. Nell'esempio seguente, l'elemento <div> è denominato map_canvas.

  2. Tieni presente le regole di visibilità predefinite che Fleet Engine applica ai viaggi monitorati. Puoi anche configurare le regole di visibilità per le attività di spedizione dei veicoli attivi e di fermata pianificata. Consulta Personalizzare la visibilità delle attività nella Configurare le attività guida.

Questi esempi mostrano come inizializzare una visualizzazione mappa.

JavaScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

TypeScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // Any undefined styling options will use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

Aggiornare l'avanzamento della spedizione

Puoi rimanere in ascolto degli eventi e aggiornare l'avanzamento della spedizione man mano che il viaggio procede. Utilizza il fornitore di posizioni per recuperare i metadati dall'oggetto taskTrackingInfo. Le modifiche ai metadati attivano un evento update. L'oggetto taskTrackingInfo fornisce quanto segue:

  • ETA
  • Numero di fermate rimanenti
  • Distanza rimanente prima del ritiro o della consegna

L'esempio seguente mostra come rilevare questi eventi di modifica.

JavaScript

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

Visualizzare i criteri per più attività

Consumer SDK per le attività pianificate mostra una sola attività per ID monitoraggio sulla mappa. Tuttavia, in genere assegni anche un ID monitoraggio a una merce di spedizione specifica che rimane associata alla merce durante il viaggio nel tuo sistema. Ciò significa che un singolo ID monitoraggio potrebbe essere associato a più attività, ad esempio un'attività di ritiro seguita da un'attività di consegna per lo stesso pacco o più attività di spedizione non riuscite per un pacco.

Per gestire questa situazione, Fleet Engine applica i criteri per la visualizzazione delle attività, mostrati nella tabella seguente.

Criteri delle attività Risultato
Attività di ritiro aperte
Ne esiste esattamente una Mostra l'attività
Ne esistono più di una Genera errore
Attività di ritiro chiuse
Ne esiste esattamente una Mostra l'attività
Ne esistono più di una (alcune con orari di risultato) Mostra l'attività con l'orario di risultato più recente
Ne esistono più di una (nessuna con orari di risultato) Genera errore
Attività di consegna aperte
Ne esiste esattamente una Mostra l'attività
Ne esistono più di una Genera errore
Attività di consegna chiuse
Ne esiste esattamente una Mostra l'attività
Ne esistono più di una (alcune con orari di risultato) Mostra l'attività con l'orario di risultato più recente
Ne esistono più di una (nessuna con orari di risultato) Genera errore

Interrompere il monitoraggio di una spedizione

Quando un viaggio di spedizione viene completato o annullato, l'app per utenti finali deve interrompere il monitoraggio di una spedizione rimuovendo l'ID monitoraggio e il fornitore di posizioni dalla visualizzazione mappa. Per maggiori dettagli, vedi le sezioni seguenti.

Rimuovere l'ID monitoraggio

Per impedire al fornitore di posizioni di monitorare la spedizione, rimuovi l'ID monitoraggio dal fornitore di posizioni. Gli esempi seguenti mostrano come eseguire questa operazione.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Rimuovere il fornitore di posizioni dalla visualizzazione mappa

L'esempio seguente mostra come rimuovere un fornitore di posizioni dalla visualizzazione mappa.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Gestire gli errori di monitoraggio della spedizione

Gli errori che si verificano in modo asincrono durante la richiesta di informazioni sulla spedizione attivano eventi error. L'esempio seguente mostra come rilevare questi eventi per gestire gli errori.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

Nota:assicurati di racchiudere le chiamate alla libreria nei blocchi try...catch per gestire gli errori imprevisti.

Passaggi successivi