Sendung verfolgen

Nachdem Sie das JavaScript Consumer SDK für geplante Aufgaben eingerichtet haben, können Sie eine Sendung mit Ihrer Consumer-App verfolgen. In diesem Dokument werden die folgenden wichtigen Schritte in diesem Prozess behandelt:

  • Karte initialisieren und gemeinsame Reise anzeigen
  • Reisefortschritt aktualisieren und verfolgen
  • Sendung nicht mehr verfolgen
  • Fehler bei der Sendungsverfolgung behandeln

Karte einrichten

Wenn Sie die Abholung oder Lieferung einer Sendung in Ihrer Web-App verfolgen möchten, müssen Sie eine Karte laden und das Consumer SDK instanziieren, um die Sendung zu verfolgen. Sie können entweder eine neue Karte laden oder eine vorhandene verwenden. Anschließend verwenden Sie die Initialisierungsfunktion, um das Consumer SDK zu instanziieren, damit die Kartenansicht dem Standort des verfolgten Artikels entspricht.

Neue Karte mit der Google Maps JavaScript API laden

Wenn Sie eine neue Karte erstellen möchten, laden Sie die Google Maps JavaScript API in Ihre Web-App. Im folgenden Beispiel wird gezeigt, wie Sie die Google Maps JavaScript API laden, das SDK aktivieren und die Initialisierungsprüfung auslösen.

  • Der Parameter callback führt die Funktion initMap aus, nachdem die API geladen wurde.
  • Mit dem Attribut defer kann der Browser den Rest Ihrer Seite weiter rendern, während die API geladen wird.

Verwenden Sie die Funktion initMap, um das Consumer SDK zu instanziieren. Beispiel:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

Vorhandene Karte laden

Sie können auch eine vorhandene Karte laden, die mit der Google Maps JavaScript API erstellt wurde, z. B. eine, die Sie bereits verwenden.

Angenommen, Sie haben eine Webseite mit einer Standardentität google.maps.Map, auf der eine Markierung gemäß dem folgenden HTML-Code angezeigt wird. Hier wird Ihre Karte mit derselben Funktion initMap im Callback am Ende angezeigt:

    <!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>

Anbieter für Sendungsstandorte instanziieren

Verwenden Sie den Anbieter für Sendungsstandorte zusammen mit dem zuvor definierten Abrufer für Autorisierungstokens, um Daten von Fleet Engine zu empfangen.

In diesen Beispielen wird gezeigt, wie Sie den Standortanbieter instanziieren.

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
  });

Gemeinsame Reise anzeigen

Wenn Sie den Fortschritt einer geplanten Aufgabe anzeigen möchten, initialisieren Sie die Ansicht. Dadurch wird der Rahmen für die Karte so festgelegt, dass er dem Standort der verfolgten Reise entspricht. Der Fortschritt wird dann vom Consumer SDK bereitgestellt, nachdem es die Informationen von Fleet Engine erhalten hat.

Tipps:

  1. Achten Sie darauf, dass Ihre Seite ein <div>-Element enthält, das die Kartenansicht enthält. Im folgenden Beispiel heißt das <div>-Element map_canvas.

  2. Beachten Sie die Standardregeln für die Sichtbarkeit, die Fleet Engine auf verfolgte Reisen anwendet. Sie können auch Regeln für die Sichtbarkeit für aktive Fahrzeugsendungen und geplante Stoppaufgaben konfigurieren. Weitere Informationen finden Sie im Leitfaden Aufgaben konfigurieren unter Aufgabenansicht anpassen.

In diesen Beispielen wird gezeigt, wie Sie eine Kartenansicht initialisieren.

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);
}

Sendungsfortschritt aktualisieren

Sie können auf Ereignisse warten und den Sendungsfortschritt im Laufe der Reise aktualisieren. Verwenden Sie den Standortanbieter, um Metainformationen aus dem Objekt taskTrackingInfo abzurufen. Änderungen an den Metainformationen lösen ein update-Ereignis aus. Das Objekt taskTrackingInfo enthält Folgendes:

  • Voraussichtliche Ankunft
  • Anzahl der verbleibenden Stopps
  • Verbleibende Entfernung vor der Abholung oder Lieferung

Im folgenden Beispiel wird gezeigt, wie Sie auf diese Änderungsereignisse warten.

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);
});

Kriterien für mehrere Aufgaben anzeigen

Das Consumer SDK für geplante Aufgaben zeigt nur eine Aufgabe pro Tracking-ID auf der Karte an. Normalerweise weisen Sie jedoch auch eine Tracking-ID einem bestimmten Versandartikel zu, der während der gesamten Reise in Ihrem System mit dem Artikel verknüpft bleibt. Das bedeutet, dass eine einzelne Tracking-ID mit mehreren Aufgaben verknüpft sein kann, z. B. einer Abholaufgabe, gefolgt von einer Lieferaufgabe für dasselbe Paket, oder mehreren fehlgeschlagenen Versandaufgaben für ein Paket.

Um diese Situation zu bewältigen, wendet Fleet Engine Kriterien für die Anzeige von Aufgaben an, die in der folgenden Tabelle aufgeführt sind.

Aufgabenkriterien Ergebnis
Offene Abholaufgaben
Genau eine vorhanden Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Abgeschlossene Abholaufgaben
Genau eine vorhanden Aufgabe anzeigen
Mehrere vorhanden (einige mit Ergebniszeiten) Aufgabe mit der letzten Ergebniszeit anzeigen
Mehrere vorhanden (keine mit Ergebniszeiten) Fehler generieren
Offene Lieferaufgaben
Genau eine vorhanden Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Abgeschlossene Lieferaufgaben
Genau eine vorhanden Aufgabe anzeigen
Mehrere vorhanden (einige mit Ergebniszeiten) Aufgabe mit der letzten Ergebniszeit anzeigen
Mehrere vorhanden (keine mit Ergebniszeiten) Fehler generieren

Sendung nicht mehr verfolgen

Wenn eine Sendung abgeschlossen oder storniert wird, sollte Ihre Consumer-App die Sendung nicht mehr verfolgen, indem die Tracking-ID und der Standortanbieter aus der Kartenansicht entfernt werden. Details zu diesen Schritten finden Sie in den folgenden Abschnitten.

Tracking-ID entfernen

Wenn Sie verhindern möchten, dass der Standortanbieter die Sendung verfolgt, entfernen Sie die Tracking-ID aus dem Standortanbieter. In den folgenden Beispielen wird gezeigt, wie Sie das tun.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Standortanbieter aus der Kartenansicht entfernen

Im folgenden Beispiel wird gezeigt, wie Sie einen Standortanbieter aus der Kartenansicht entfernen.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Fehler bei der Sendungsverfolgung behandeln

Fehler, die asynchron durch das Anfordern von Sendungsinformationen entstehen, lösen error-Ereignisse aus. Im folgenden Beispiel wird gezeigt, wie Sie auf diese Ereignisse warten, um Fehler zu behandeln.

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);
});

Hinweis:Umschließen Sie Bibliotheksaufrufe immer mit try...catch-Blöcken, um unerwartete Fehler zu behandeln.

Nächste Schritte