Maintenant que vous avez configuré le SDK client JavaScript pour les tâches planifiées, vous êtes prêt à suivre une livraison avec votre application grand public. Ce document décrit les étapes clés de ce processus:
- Initialiser une carte et afficher le parcours partagé
- Mettre à jour et suivre la progression du trajet
- Ne plus suivre un envoi
- Gérer les erreurs de suivi de livraison
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 colis. 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
callback
exécute la fonctioninitMap
après le chargement de l'API. - L'attribut
defer
permet 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 Google Maps JavaScript, telle qu'une carte que vous avez déjà utilisée.
Par exemple, supposons que vous ayez 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>
Instancier un fournisseur de localisation d'expédition
Utilisez le fournisseur de localisation de l'envoi, ainsi que le récupérateur de jeton d'autorisation que vous avez défini précédemment, pour commencer à recevoir des données de Fleet Engine.
Ces exemples montrent comment instancier le fournisseur de position.
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
});
Afficher le parcours partagé
Pour afficher la progression d'une tâche planifiée, initialisez sa vue, ce qui fait correspondre le cadre de la carte à l'emplacement du trajet suivi. La progression est ensuite fournie par le SDK client après avoir obtenu les informations de Fleet Engine.
Astuces :
Assurez-vous que votre page contient un élément <div> qui contient la vue plan. Dans l'exemple suivant, l'élément <div> est nommé
map_canvas
.Tenez compte des règles de visibilité par défaut que Fleet Engine applique aux trajets suivis. Vous pouvez également configurer des règles de visibilité pour les expéditions de véhicules actives et les tâches d'arrêt planifiées. Consultez Personnaliser la visibilité des tâches dans le guide Configurer les tâches.
Ces exemples montrent comment initialiser une vue de carte.
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);
}
Mettre à jour la progression de l'expédition
Vous pouvez écouter les événements et mettre à jour la progression de l'expédition au fur et à mesure du parcours. Utilisez le fournisseur de position pour récupérer les métadonnées de l'objet taskTrackingInfo
. Les modifications apportées aux méta-informations déclenchent un événement update. L'objet taskTrackingInfo
fournit les éléments suivants:
- ETA
- Nombre d'arrêts restants
- Distance restante avant le retrait ou la livraison
L'exemple suivant montre comment écouter ces événements de modification.
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);
});
Afficher les critères pour plusieurs tâches
Le SDK Consumer pour les tâches planifiées n'affiche qu'une seule tâche par ID de suivi sur la carte. Toutefois, vous attribuez généralement un ID de suivi à un bien expédié spécifique qui reste associé au bien tout au long de son parcours dans votre système. Cela signifie qu'un même ID de suivi peut être associé à plusieurs tâches, comme une tâche de retrait suivie d'une tâche de livraison pour le même colis ou plusieurs tâches d'expédition ayant échoué pour un colis.
Pour gérer cette situation, Fleet Engine applique les critères d'affichage des tâches indiqués dans le tableau suivant.
Critères de la tâche | Résultat |
---|---|
Ouvrir les tâches de retrait | |
Il n'en existe qu'un seul | Afficher la tâche |
Plusieurs existent | Générer une erreur |
Tâches de récupération terminées | |
Une seule réponse existe | Afficher la tâche |
Plusieurs existent (certains avec des délais de résultat) | Afficher la tâche avec l'heure de résultat le plus récent |
Plusieurs existent (aucun avec l'heure du résultat) | Générer une erreur |
Ouvrir les tâches de livraison | |
Une seule réponse existe | Afficher la tâche |
Plusieurs existent | Générer une erreur |
Tâches de diffusion terminées | |
Une seule réponse existe | Afficher la tâche |
Plusieurs existent (certains avec des délais de résultat) | Afficher la tâche avec l'heure de résultat le plus récent |
Plusieurs existent (aucun avec l'heure du résultat) | Générer une erreur |
Ne plus suivre un envoi
Lorsqu'un parcours d'expédition est terminé ou annulé, votre application grand public doit cesser de suivre l'expédition en supprimant l'ID de suivi et le fournisseur de position de la vue cartographique. Pour en savoir plus, consultez les sections suivantes.
Supprimer l'ID de suivi
Pour empêcher le fournisseur de position de suivre l'envoi, supprimez l'ID de suivi du fournisseur de position. Les exemples suivants montrent comment procéder.
JavaScript
locationProvider.trackingId = '';
TypeScript
locationProvider.trackingId = '';
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 suivi des envois
Les erreurs survenant de manière asynchrone lors de la demande d'informations sur la livraison déclenchent des événements error. L'exemple suivant montre comment écouter ces événements pour gérer les erreurs.
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);
});
Remarque : Veillez à encapsuler les appels de bibliothèque dans des blocs try...catch
pour gérer les erreurs imprévues.