Seguire una spedizione

Ora che hai configurato JavaScript Consumer SDK per le attività pianificate, pronto a seguire una spedizione con la tua app consumer. Questo documento tratta le i seguenti passaggi chiave:

  • Inizializza una mappa e visualizza il percorso condiviso
  • Aggiornare e seguire l'avanzamento del viaggio
  • Interrompere la condivisione del viaggio
  • Gestire gli errori

Configurare una mappa

Per seguire un ritiro o una consegna di una spedizione nella tua app web, devi caricare una mappa e crea un'istanza dell'SDK consumer per iniziare a tracciare la spedizione. Puoi caricare una nuova mappa o utilizzarne una esistente. Poi userai il modello di inizializzazione per creare un'istanza dell'SDK consumer in modo che la vista mappa corrisponda posizione dell'elemento monitorato.

Carica una nuova mappa utilizzando l'API Google Maps JavaScript

Per creare una nuova mappa, carica l'API Google Maps JavaScript nell'app web. La l'esempio seguente mostra come caricare l'API Google Maps JavaScript, abilitare il metodo 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 visualizzare il resto dei tuoi durante il caricamento dell'API.

Usa la funzione initMap per creare un'istanza dell'SDK consumer. Ad esempio:

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

Carica una mappa esistente

Puoi anche caricare una mappa esistente creata con l'API Google Maps JavaScript, come quella già in uso.

Ad esempio, supponiamo che tu abbia una pagina web con un google.maps.Map standard su cui viene visualizzato un indicatore, come definito nel seguente codice HTML. Questo mostra la mappa utilizzando 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 per un fornitore della località di spedizione

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

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

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

Mostra il percorso condiviso

Per consentire alla mappa di visualizzare il percorso condiviso, devi inizializzarne il percorso che imposta il frame in cui la mappa corrisponde alla posizione percorso monitorato fornito dall'SDK consumer dopo aver recuperato le informazioni da Fleet Engine.

Suggerimenti:

  1. Verifica che la pagina contenga un elemento &lt;div&gt; che contenga la visualizzazione mappa. Nell'esempio seguente, l'elemento &lt;div&gt; è denominato map_canvas.

  2. Considera le regole di visibilità predefinite che Fleet Engine si applica ai per i vostri viaggi. Puoi anche configurare le regole di visibilità per il veicolo attivo delle attività di spedizione e di interruzioni programmate. Consulta la sezione Personalizzare la visibilità delle attività nella Guida alla configurazione delle attività.

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

Aggiorna l'avanzamento della spedizione

Puoi rilevare gli eventi e aggiornare l'avanzamento della spedizione man mano che un percorso procede. Utilizza il provider di localizzazione per recuperare i metadati dal taskTrackingInfo oggetto. Le modifiche alle meta informazioni attivano un evento di aggiornamento. L'oggetto taskTrackingInfo fornisce le seguenti:

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

L'esempio seguente mostra come ascoltare 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);
});

Criteri di visualizzazione per più attività

L'SDK consumer per le attività pianificate mostra una sola attività per ID monitoraggio su la mappa. Tuttavia, in genere assegni anche un ID monitoraggio a un ID monitoraggio spedizione che rimane associata al bene nel corso del suo percorso. 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 la stessa pacco o più attività di spedizione non riuscite per un pacco.

Per gestire questa situazione, Fleet Engine applica criteri per visualizzare le attività, come mostrato nella tabella seguente.

Criteri delle attività Risultato
Apri le attività di ritiro
Esattamente uno esistente Mostra l'attività
Esistono più Genera errore
Attività di ritiro chiuse
Esattamente uno esistente Mostra l'attività
Esistono più cose (alcune con date di risultato) Mostrare l'attività con l'ora dell'esito più recente
Esistono più cose (nessuna con data/ora dei risultati) Genera errore
Apri le attività di consegna
Esattamente uno esistente Mostra l'attività
Esistono più Genera errore
Attività di consegna chiuse
Esattamente uno esistente Mostra l'attività
Esistono più cose (alcune con date di risultato) Mostrare l'attività con l'ora dell'esito più recente
Esistono più cose (nessuna con data/ora dei risultati) Genera errore

Smettere di seguire una spedizione

Quando un percorso di spedizione viene completato o annullato, la tua app consumer dovrebbe termina la condivisione del percorso rimuovendo l'ID monitoraggio e il fornitore della posizione da la visualizzazione mappa.

Rimuovi l'ID monitoraggio

Per impedire al fornitore della posizione di monitorare la spedizione, rimuovi l'ID monitoraggio del fornitore di servizi di localizzazione. I seguenti esempi mostrano come eseguire questa operazione.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Rimuovere il fornitore di posizione dalla visualizzazione mappa

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Gestire gli errori di monitoraggio della spedizione

L'attivazione degli errori che si verificano in modo asincrono in seguito alla richiesta dei dati di spedizione error. L'esempio seguente mostra come ascoltare 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 alle librerie in blocchi try...catch per gestire gli errori imprevisti.

Passaggi successivi