Suivre un envoi

Maintenant que vous avez configuré le SDK JavaScript Consumer pour les tâches planifiées, vous pouvez suivre un colis avec votre application grand public. Ce document couvre les principales étapes de ce processus :

  • Initialiser une carte et afficher le trajet partagé
  • Mettre à jour et suivre la progression du trajet
  • Ne plus suivre un colis
  • Gérer les erreurs de suivi des colis

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 SDK Consumer pour commencer à suivre votre colis. Vous pouvez charger une nouvelle carte ou en utiliser une existante. Ensuite, utilisez la fonction d'initialisation pour instancier le SDK Consumer afin que la vue cartographique corresponde à l'emplacement de l'article 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 de l'initialisation.

  • Le paramètre callback exécute la fonction initMap une fois l'API chargée.
  • 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, par exemple une carte que vous utilisez déjà.

Supposons, par exemple, 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 de colis

Utilisez le fournisseur de localisation de colis, ainsi que le récupérateur de jetons 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 localisation.

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 trajet partagé

Pour afficher la progression d'une tâche planifiée, initialisez sa vue, qui définit le cadre de la carte pour qu'il corresponde à l'emplacement du trajet suivi. La progression est ensuite fournie par le SDK Consumer après avoir obtenu les informations de Fleet Engine.

Astuces :

  1. Assurez-vous que votre page contient un élément <div> qui servira à afficher la vue cartographique. Dans l'exemple suivant, l'élément <div> est nommé map_canvas.

  2. 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 tâches de livraison de véhicules actifs et d'arrêt planifié. Consultez Personnaliser la visibilité des tâches dans le guide Configurer les tâches.

Ces exemples montrent comment initialiser une vue cartographique.

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 du colis

Vous pouvez écouter les événements et mettre à jour la progression du colis au fur et à mesure du trajet. Utilisez le fournisseur de localisation pour récupérer des métadonnées à partir de l'objet taskTrackingInfo. Toute modification des métadonnées déclenche un événement update. L'objet taskTrackingInfo fournit les informations suivantes :

  • ETA
  • Nombre d'arrêts restants
  • Distance restante avant l'enlèvement 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 également un ID de suivi à un bien de livraison spécifique qui reste associé au bien tout au long de son trajet dans votre système. Cela signifie qu'un seul ID de suivi peut être associé à plusieurs tâches, par exemple une tâche d'enlèvement suivie d'une tâche de livraison pour le même colis, ou plusieurs tâches de livraison ayant échoué pour un colis.

Pour gérer cette situation, Fleet Engine applique des critères d'affichage des tâches, indiqués dans le tableau suivant.

Critères de la tâche Résultat
Tâches d'enlèvement ouvertes
Il n'en existe qu'une seule Afficher la tâche
Il en existe plusieurs Générer une erreur
Tâches d'enlèvement fermées
Il n'en existe qu'une seule Afficher la tâche
Il en existe plusieurs (certaines avec des heures de résultat) Afficher la tâche avec l'heure de résultat la plus récente
Il en existe plusieurs (aucune avec des heures de résultat) Générer une erreur
Tâches de livraison ouvertes
Il n'en existe qu'une seule Afficher la tâche
Il en existe plusieurs Générer une erreur
Tâches de livraison fermées
Il n'en existe qu'une seule Afficher la tâche
Il en existe plusieurs (certaines avec des heures de résultat) Afficher la tâche avec l'heure de résultat la plus récente
Il en existe plusieurs (aucune avec des heures de résultat) Générer une erreur

Ne plus suivre un colis

Lorsqu'un trajet de colis est terminé ou annulé, votre application grand public doit cesser de suivre le colis en supprimant l'ID de suivi et le fournisseur de localisation de la vue cartographique. Pour en savoir plus, consultez les sections suivantes.

Supprimer l'ID de suivi

Pour empêcher le fournisseur de localisation de suivre le colis, supprimez l'ID de suivi du fournisseur de localisation. Les exemples suivants montrent comment procéder.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Supprimer le fournisseur de localisation de la vue cartographique

L'exemple suivant montre comment supprimer un fournisseur de localisation de la vue cartographique.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Gérer les erreurs de suivi des colis

Les erreurs qui surviennent de manière asynchrone lors de la demande d'informations sur les colis 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.

Étape suivante