Quando segui un percorso, l'app per utenti finali mostra all'utente la posizione del veicolo appropriato. Per farlo, l'app deve iniziare a seguire il percorso, aggiornare l'avanzamento del percorso durante il tragitto e interrompere il monitoraggio del percorso al termine.
Questo documento illustra i seguenti passaggi chiave di questo processo:
- Configura una mappa
- Inizializza una mappa e visualizza il percorso condiviso
- Aggiorna e segui l'avanzamento della corsa
- Smettere di seguire un viaggio
- Gestisci gli errori relativi alle corse
Configura una mappa
Per seguire il ritiro o la consegna di una spedizione nella tua app web, devi caricare una mappa e creare un'istanza del Consumer SDK per iniziare a monitorare il percorso. Puoi caricare una nuova mappa o utilizzarne una esistente. Poi, utilizza la funzione di inizializzazione per creare un'istanza dell'SDK Consumer in modo che la visualizzazione mappa corrisponda alla posizione dell'elemento monitorato.
Carica una nuova mappa utilizzando l'API 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, attivare 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>
Carica una mappa esistente
Puoi anche caricare una mappa esistente creata dall'API Maps JavaScript, ad esempio una che stai già utilizzando.
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. In questo modo, la mappa viene visualizzata 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>
Sostituisci una mappa esistente
Puoi sostituire una mappa esistente che include indicatori o altre personalizzazioni senza perdere queste ultime.
Ad esempio, se hai una pagina web con un'entità google.maps.Map standard su cui viene mostrato un indicatore, puoi sostituire la mappa e mantenere l'indicatore. Questa sezione descrive i passaggi per farlo.
Per sostituire la mappa e mantenere le personalizzazioni, aggiungi la condivisione del percorso alla tua pagina HTML seguendo questi passaggi, numerati anche nell'esempio seguente:
Aggiungi il codice per la factory del token di autenticazione.
Inizializza un provider di geolocalizzazione nella funzione
initMap().Inizializza la visualizzazione mappa nella funzione
initMap(). La visualizzazione contiene la mappa.Sposta la personalizzazione nella funzione di callback per l'inizializzazione della visualizzazione mappa.
Aggiungi la libreria di località al caricatore dell'API.
L'esempio seguente mostra le modifiche da apportare. Se gestisci una corsa con l'ID specificato vicino a Uluru, ora viene visualizzata sulla mappa:
<!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>
let locationProvider;
// (1) Authentication Token Fetcher
async function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
// Initialize and add the map
function initMap() {
// (2) Initialize location provider.
locationProvider = new google.maps.journeySharing.FleetEngineTripLocationProvider({
projectId: "YOUR_PROVIDER_ID",
authTokenFetcher,
});
// (3) Initialize map view (which contains the map).
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map'),
locationProviders: [locationProvider],
// any styling options
});
locationProvider.tripId = TRIP_ID;
// (4) Add customizations like before.
// 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 async attribute allows the browser to render the page while the API loads
* The key parameter will contain your own API key (which is not needed for this tutorial)
* The callback parameter executes the initMap() function
*
* (5) Add the SDK to the API loader.
-->
<script defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
</script>
</body>
</html>
Inizializza una mappa e visualizza l'avanzamento della corsa
All'inizio di una corsa, l'app deve creare un'istanza di un provider di località della corsa e poi inizializzare una mappa per iniziare a condividere l'avanzamento della corsa. Per alcuni esempi, consulta le sezioni seguenti.
Crea un'istanza di un provider di località per la corsa
L'SDK JavaScript ha un provider di posizione predefinito per l'API Fleet Engine Ridesharing. Utilizza l'ID progetto e un riferimento alla tua token factory per crearne un'istanza.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
Inizializza la visualizzazione mappa
Dopo aver caricato l'SDK JavaScript, inizializza la visualizzazione mappa e aggiungila alla pagina HTML. La pagina deve contenere un elemento <div> che contiene la visualizzazione della mappa. Nell'esempio seguente, l'elemento <div> è denominato map_canvas.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
Aggiorna e segui l'avanzamento della corsa
L'app deve ascoltare gli eventi e aggiornare l'avanzamento della corsa man mano che il percorso procede. Puoi recuperare le meta informazioni su una corsa dall'oggetto dell'attività utilizzando il provider di localizzazione. Le meta informazioni includono l'orario di arrivo stimato e la distanza rimanente prima del ritiro o della consegna. Le modifiche alle meta informazioni attivano un evento di aggiornamento. L'esempio seguente mostra come ascoltare questi eventi di modifica.
JavaScript
locationProvider.addListener('update', e => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
TypeScript
locationProvider.addListener('update', (e:
google.maps.journeySharing.FleetEngineTripLocationProviderUpdateEvent) => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
Smettere di seguire un viaggio
Al termine della corsa, devi impedire al provider di localizzazione di monitorare la corsa. Per farlo, rimuovi l'ID corsa e il provider di geolocalizzazione. Per alcuni esempi, consulta le sezioni seguenti.
Rimuovi l'ID corsa dal provider di geolocalizzazione
L'esempio seguente mostra come rimuovere un ID percorso dal provider di località.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
Rimuovi il fornitore di posizione dalla visualizzazione mappa
L'esempio seguente mostra come rimuovere un provider di località dalla visualizzazione mappa.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Gestisci gli errori relativi alle corse
Gli errori che si verificano in modo asincrono durante la richiesta di informazioni sulla corsa attivano eventi di errore. L'esempio seguente mostra come ascoltare questi eventi per gestire gli errori.
JavaScript
locationProvider.addListener('error', e => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});
TypeScript
locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});