Quando segui un viaggio, l'app per i consumatori mostra al consumatore la posizione del veicolo appropriato. Per farlo, l'app deve iniziare a seguire il viaggio, aggiornare l'avanzamento del viaggio durante il viaggio e interrompere la tracciabilità al termine del viaggio.
Questo documento illustra i seguenti passaggi chiave della procedura:
- Configurare una mappa
- Inizializza una mappa e mostra il viaggio condiviso
- Aggiornare e seguire l'avanzamento del viaggio
- Smettere di seguire un viaggio
- Gestire gli errori relativi ai viaggi
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 il tuo percorso. 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>
Sostituire una mappa esistente
Puoi sostituire una mappa esistente che include indicatori o altre personalizzazioni senza perderle.
Ad esempio, se hai una pagina web con un'entità google.maps.Map
standard su cui è mostrato un indicatore, puoi sostituire la mappa e mantenere
l'indicatore. Questa sezione descrive la procedura da seguire.
Per sostituire la mappa e mantenere le personalizzazioni, aggiungi la condivisione del percorso alla tua pagina HTML seguendo questi passaggi, che sono anche numerati nell'esempio che segue:
Aggiungi il codice per la factory del token di autenticazione.
Inizializza un provider di posizione 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 un viaggio con l'ID specificato vicino a Uluru, ora viene visualizzato 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>
Inizializzare una mappa e visualizzare l'avanzamento del viaggio
Quando inizia un viaggio, l'app deve creare un provider di posizione del viaggio e poi inizializzare una mappa per iniziare a condividere l'avanzamento del viaggio. Consulta le sezioni seguenti per esempi.
Crea un'istanza di un provider di posizione del viaggio
L'SDK JavaScript ha un fornitore di servizi di geolocalizzazione predefinito per l'API Fleet Engine Ridesharing. Utilizza l'ID progetto e un riferimento alla tua factory di token per eseguirne l'inizializzazione.
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',
});
Inizializzare la visualizzazione mappa
Dopo aver caricato l'SDK JavaScript, inizializza la visualizzazione della mappa e aggiungila alla pagina HTML. La pagina deve contenere un elemento <div> che contiene la visualizzazione della mappa. L'elemento <div> è denominato map_canvas nell'esempio seguente.
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);
Aggiornare e seguire l'avanzamento del viaggio
L'app deve ascoltare gli eventi e aggiornare l'avanzamento della corsa man mano che il tragitto procede. Puoi recuperare le meta informazioni su un viaggio dall'oggetto della richiesta utilizzando il fornitore di servizi di geolocalizzazione. Le meta informazioni includono l'orario di arrivo stimato e la distanza rimanente prima del ritiro o del reso. Le modifiche alle metainformazioni 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 del viaggio, devi impedire al fornitore di servizi di localizzazione di monitorarlo. Per farlo, rimuovi l'ID viaggio e il provider di posizione. Per esempi, consulta le sezioni seguenti.
Rimuovere l'ID viaggio dal provider di posizione
L'esempio seguente mostra come rimuovere un ID viaggio dal fornitore di servizi di geolocalizzazione.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
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 relativi ai viaggi
Gli errori che si verificano in modo asincrono dalla richiesta di informazioni sui viaggi attivano gli 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);
});