Ora che hai configurato l'SDK consumer JavaScript per le attività pianificate, puoi seguire una spedizione con la tua app consumer. Questo documento illustra i seguenti passaggi chiave di questa procedura:
- Inizializzare una mappa e visualizzare il viaggio condiviso
- Aggiornare e seguire l'avanzamento del viaggio
- 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 dell'SDK Consumer per iniziare a monitorare la spedizione. Puoi caricare una nuova mappa o utilizzarne una esistente. Poi utilizzi la funzione di inizializzazione per creare un'istanza dell'SDK Consumer in modo che la visualizzazione mappa corrisponda alla posizione dell'elemento monitorato.
Caricare una nuova mappa utilizzando l'API Google Maps JavaScript
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
callbackesegue la funzioneinitMapdopo il caricamento dell'API. - L'attributo
deferconsente 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 dell'SDK Consumer. 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, come una già in uso.
Ad esempio, supponiamo di avere una pagina web con un'entità google.maps.Map
standard su cui viene mostrato un indicatore come definito nel seguente codice HTML. Questa mappa mostra 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>
Crea un'istanza di un provider di posizione della spedizione
Utilizza il fornitore della posizione della spedizione, insieme al recupero del token di autorizzazione che hai definito in precedenza, per iniziare a ricevere dati da Fleet Engine.
Questi esempi mostrano come creare un'istanza del provider 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
});
Visualizza 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 percorso monitorato. L'avanzamento viene fornito dall'SDK consumer dopo che ha ricevuto le informazioni da Fleet Engine.
Suggerimenti:
Assicurati che la pagina contenga un elemento <div> che contenga la visualizzazione della mappa. Nell'esempio seguente, l'elemento <div> è denominato
map_canvas.Tieni presente le regole di visibilità predefinite applicate da Fleet Engine ai tragitti monitorati. Puoi anche configurare regole di visibilità per le attività di spedizione e di fermata programmata dei veicoli attivi. Consulta Personalizzare la visibilità delle attività nella guida Configurare le 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);
}
Aggiornare l'avanzamento della spedizione
Puoi rilevare gli eventi e aggiornare l'avanzamento della spedizione man mano che un percorso procede. Utilizza il fornitore di servizi di geolocalizzazione per recuperare i metadati dall'oggetto
taskTrackingInfo. Le modifiche alle meta informazioni attivano un evento di aggiornamento. L'oggetto taskTrackingInfo fornisce quanto segue:
- ETA
- Numero di fermate rimanenti
- Distanza rimanente prima del ritiro o della consegna
Il seguente esempio 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);
});
Visualizzare i criteri per più attività
L'SDK Consumer per le attività pianificate mostra una sola attività per ID monitoraggio sulla mappa. Tuttavia, in genere assegni anche un ID monitoraggio a un determinato bene della spedizione che rimane associato al bene durante il suo percorso nel tuo sistema. Ciò significa che un singolo ID tracciabilità 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à, riportati nella tabella seguente.
| Criteri delle attività | Risultato |
|---|---|
| Aprire le attività di ritiro | |
| Esiste esattamente uno | Mostra l'attività |
| Esistono più | Genera errore |
| Attività di ritiro chiuse | |
| Esiste esattamente uno | Mostrare l'attività |
| Esistono più risultati (alcuni con orari di esito) | Mostrare l'attività con l'ora dell'esito più recente |
| Esistono più risultati (nessuno con orari di esito) | Genera errore |
| Aprire le attività di importazione | |
| Esiste esattamente uno | Mostra l'attività |
| Esistono più | Genera errore |
| Attività di importazione chiuse | |
| Esiste esattamente uno | Mostrare l'attività |
| Esistono più risultati (alcuni con orari di esito) | Mostrare l'attività con l'ora dell'esito più recente |
| Esistono più risultati (nessuno con orari di esito) | Genera errore |
Interrompere il monitoraggio di una spedizione
Quando un percorso di spedizione è completato o viene annullato, l'app per i consumatori deve interrompere il monitoraggio di una spedizione rimuovendo l'ID tracciamento e il fornitore di servizi di geolocalizzazione dalla visualizzazione della mappa. Per maggiori dettagli, consulta le sezioni seguenti.
Rimuovi l'ID monitoraggio
Per impedire al fornitore di servizi di localizzazione di monitorare la spedizione, rimuovi l'ID tracciamento dal fornitore di servizi di localizzazione. Gli esempi riportati di seguito mostrano come eseguire questa operazione.
JavaScript
locationProvider.trackingId = '';
TypeScript
locationProvider.trackingId = '';
Rimuovere il fornitore di servizi di geolocalizzazione dalla visualizzazione mappa
L'esempio seguente mostra come rimuovere un fornitore di servizi di geolocalizzazione 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 dalla richiesta di informazioni sulla spedizione attivano gli eventi 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.