Lorsque vous suivez un trajet, votre application grand public affiche l'emplacement du véhicule concerné pour le consommateur. Pour ce faire, votre application doit commencer à suivre le trajet, mettre à jour la progression du trajet pendant le trajet et arrêter de suivre le trajet une fois celui-ci terminé.
Ce document couvre les principales étapes de ce processus :
- Configurer une carte
- Initialiser une carte et afficher le trajet partagé
- Mettre à jour et suivre la progression du trajet
- Ne plus suivre un voyage
- Gérer les erreurs liées aux trajets
Configurer une carte
Pour suivre l'enlèvement ou la livraison d'un colis dans votre application Web, vous devez charger une carte et instancier le Consumer SDK pour commencer à suivre votre trajet. Vous pouvez charger une nouvelle carte ou en utiliser une existante. Vous utilisez ensuite la fonction d'initialisation pour instancier le SDK Consumer afin que la vue de carte corresponde à l'emplacement de l'élément suivi.
Charger une nouvelle carte à l'aide de l'API Google Maps JavaScript
Pour créer une carte, chargez l'API Maps JavaScript dans votre application Web. L'exemple suivant montre comment charger l'API Maps JavaScript, activer le SDK et déclencher la vérification de l'initialisation.
- Le paramètre
callbackexécute la fonctioninitMapune fois l'API chargée. - L'attribut
deferpermet au navigateur de continuer à afficher le reste de la page pendant que l'API charge.
Utilisez la fonction initMap pour instancier le SDK Consumer. Exemple :
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>
Charger une carte existante
Vous pouvez également charger une carte existante créée par l'API Maps JavaScript, par exemple une carte que vous utilisez déjà.
Par exemple, supposons que vous disposiez d'une page Web avec une entité google.maps.Map standard sur laquelle un repère est affiché, comme défini dans le code HTML suivant. Votre carte s'affiche à l'aide de la même fonction initMap dans le rappel à la fin :
<!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>
Remplacer une carte existante
Vous pouvez remplacer une carte existante qui inclut des repères ou d'autres personnalisations sans perdre ces personnalisations.
Par exemple, si vous avez une page Web avec une entité google.maps.Map standard sur laquelle un repère est affiché, vous pouvez remplacer la carte et conserver le repère. Cette section décrit la procédure à suivre.
Pour remplacer la carte et conserver les personnalisations, ajoutez le partage de trajet à votre page HTML en suivant ces étapes, qui sont également numérotées dans l'exemple ci-dessous :
Ajoutez le code pour la fabrique de jetons d'authentification.
Initialisez un fournisseur de localisation dans la fonction
initMap().Initialisez la vue de carte dans la fonction
initMap(). La vue contient la carte.Déplacez votre personnalisation dans la fonction de rappel pour l'initialisation de la vue Plan.
Ajoutez la bibliothèque de localisation au chargeur d'API.
L'exemple suivant montre les modifications à apporter. Si vous effectuez un trajet avec l'ID spécifié à proximité d'Uluru, il s'affiche désormais sur la carte :
<!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>
Initialiser une carte et afficher la progression du trajet
Lorsqu'un trajet commence, votre application doit instancier un fournisseur de localisation de trajet, puis initialiser une carte pour commencer à partager la progression du trajet. Pour obtenir des exemples, consultez les sections suivantes.
Instancier un fournisseur de localisation de trajet
Le SDK JavaScript dispose d'un fournisseur de localisation prédéfini pour l'API Fleet Engine Ridesharing. Utilisez l'ID de votre projet et une référence à votre fabrique de jetons pour l'instancier.
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',
});
Initialiser la vue Plan
Après avoir chargé le SDK JavaScript, initialisez la vue de carte et ajoutez-la à la page HTML. Votre page doit contenir un élément <div> qui contient la vue de la carte. Dans l'exemple suivant, l'élément <div> est nommé 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);
Mettre à jour et suivre la progression du trajet
Votre application doit écouter les événements et mettre à jour la progression du trajet au fur et à mesure de son déroulement. Vous pouvez récupérer des métadonnées sur un trajet à partir de l'objet de tâche à l'aide du fournisseur de localisation. Les métadonnées incluent l'heure d'arrivée prévue et la distance restante avant la prise en charge ou la dépose. Les modifications apportées aux méta-informations déclenchent un événement update. L'exemple suivant montre comment écouter ces événements de modification.
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);
});
Ne plus suivre un voyage
Une fois le trajet terminé, vous devez empêcher le fournisseur de localisation de le suivre. Pour ce faire, supprimez l'ID du trajet et le fournisseur de localisation. Pour obtenir des exemples, consultez les sections suivantes.
Supprimer l'ID de trajet du fournisseur de données de localisation
L'exemple suivant montre comment supprimer un ID de trajet du fournisseur de localisation.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
Supprimer le fournisseur de localisation de la vue de carte
L'exemple suivant montre comment supprimer un fournisseur de localisation de la vue de carte.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Gérer les erreurs liées aux trajets
Les erreurs qui surviennent de manière asynchrone lors de la demande d'informations sur le trajet déclenchent des événements d'erreur. L'exemple suivant montre comment écouter ces événements pour gérer les erreurs.
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);
});
Étape suivante
Appliquer un style à une carte