Lorsque vous suivez un trajet, votre application grand public affiche l'emplacement du véhicule approprié. 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 qu'il est terminé.
Ce document décrit les étapes clés 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 trajet
- Gérer les erreurs de trajet
Configurer une carte
Pour suivre la collecte ou la livraison d'un colis dans votre application Web, vous devez charger une carte et instancier le SDK Consumer pour commencer à suivre votre parcours. Vous pouvez charger une nouvelle carte ou utiliser une carte existante. Vous utilisez ensuite la fonction d'initialisation pour instancier le SDK Consumer afin que la vue de la 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 Google Maps JavaScript dans votre application Web. L'exemple suivant montre comment charger l'API Google Maps JavaScript, activer le SDK et déclencher la vérification d'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. Cela affiche votre carte à 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 parcours à votre page HTML en procédant comme suit, comme indiqué dans l'exemple suivant :
Ajoutez le code de la fabrique de jetons d'authentification.
Initialisez un fournisseur de position dans la fonction
initMap().Initialisez la vue de la 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 de la carte.
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
Au début d'un trajet, votre application doit instancier un fournisseur de position de trajet, puis initialiser une carte pour commencer à partager la progression du trajet. Pour en savoir plus, consultez les sections suivantes.
Instancier un fournisseur d'emplacements de trajet
Le SDK JavaScript dispose d'un fournisseur de position prédéfini pour l'API Fleet Engine Ridesharing. Utilisez votre ID de 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 Carte
Après avoir chargé le SDK JavaScript, initialisez la vue de la carte et ajoutez-la à la page HTML. Votre page doit contenir un élément <div> qui contient la vue de la carte. L'élément <div> est nommé map_canvas dans l'exemple suivant.
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. Vous pouvez récupérer des métadonnées sur un trajet à partir de l'objet de tâche à l'aide du fournisseur de position. 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étadonnées déclenchent un événement de mise à jour. 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 trajet
À la fin du trajet, vous devez empêcher le fournisseur de position de le suivre. Pour ce faire, supprimez l'ID de trajet et le fournisseur de position. Pour en savoir plus, 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 position.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
Supprimer le fournisseur de position de la vue cartographique
L'exemple suivant montre comment supprimer un fournisseur de position de la vue cartographique.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Gérer les erreurs de trajet
Les erreurs qui surviennent de manière asynchrone lors de la demande d'informations sur un 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);
});