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 beschrieben:

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

Karte einrichten

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

Neue Karte mit der Google Maps JavaScript API laden

Um eine neue Karte zu erstellen, 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 Karte, die Sie bereits verwenden.

Angenommen, Sie haben eine Webseite mit einer Standard-google.maps.Map-Einheit, auf der eine Markierung wie im folgenden HTML-Code definiert angezeigt wird. Hier sehen Sie Ihre Karte mit derselben initMap-Funktion im Callback am Ende:

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

Standortanbieter für Sendungen instanziieren

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

In diesen Beispielen wird gezeigt, wie der Standortanbieter instanziiert wird.

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

Geteilte Route anzeigen

Um den Fortschritt einer geplanten Aufgabe anzuzeigen, initialisieren Sie die zugehörige Ansicht. Dadurch wird der Frame für die Karte so festgelegt, dass er dem Ort für die verfolgte Route 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, in dem die Kartenansicht angezeigt wird. Im folgenden Beispiel hat das <div>-Element den Namen map_canvas.

  2. Beachten Sie die Standardregeln für die Sichtbarkeit, die Fleet Engine auf verfolgte Fahrten anwendet. Sie können auch Sichtbarkeitsregeln für aktive Aufgaben für Fahrzeuglieferungen und geplante Stopps konfigurieren. Weitere Informationen finden Sie im Leitfaden Aufgaben konfigurieren unter Sichtbarkeit von Aufgaben anpassen.

In diesen Beispielen wird gezeigt, wie eine Kartenansicht initialisiert wird.

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

Lieferfortschritt aktualisieren

Sie können auf Ereignisse warten und den Versandfortschritt aktualisieren, wenn ein Vorgang fortschreitet. Verwenden Sie den Standortanbieter, um Metainformationen aus dem taskTrackingInfo-Objekt abzurufen. Änderungen an den Metainformationen lösen ein Update-Ereignis aus. Das taskTrackingInfo-Objekt bietet Folgendes:

  • ETA
  • Anzahl der verbleibenden Stopps
  • Verbleibende Entfernung bis zur Abholung oder Lieferung

Das folgende Beispiel zeigt, 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

Im Consumer SDK für geplante Aufgaben wird nur eine Aufgabe pro Tracking-ID auf der Karte angezeigt. In der Regel weisen Sie jedoch auch eine Tracking-ID einem bestimmten Versandartikel zu, die während des gesamten Transports 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. mit einer Abholaufgabe, gefolgt von einer Zustellaufgabe für dasselbe Paket, oder mit 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
Abholaufgaben öffnen
Es ist genau ein Element vorhanden. Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Abgeschlossene Abholaufgaben
Es ist genau ein Element vorhanden. Aufgabe anzeigen
Mehrere vorhanden (einige mit Ergebniszeiten) Aufgabe mit dem letzten Ergebniszeitpunkt anzeigen
Mehrere vorhanden (keine mit Ergebniszeitpunkten) Fehler generieren
Lieferaufgaben öffnen
Es ist genau ein Element vorhanden. Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Geschlossene Lieferaufgaben
Es ist genau ein Element vorhanden. Aufgabe anzeigen
Mehrere vorhanden (einige mit Ergebniszeiten) Aufgabe mit dem letzten Ergebniszeitpunkt anzeigen
Mehrere vorhanden (keine mit Ergebniszeitpunkten) Fehler generieren

Sendung nicht mehr verfolgen

Wenn eine Sendung abgeschlossen oder storniert wird, sollte Ihre Verbraucher-App die Sendung nicht mehr verfolgen. Entfernen Sie dazu die Tracking-ID und den Standortanbieter aus der Kartenansicht. 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. Die folgenden Beispiele zeigen, wie das geht.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Standortanbieter aus der Kartenansicht entfernen

Das folgende Beispiel zeigt, wie ein Standortanbieter aus der Kartenansicht entfernt wird.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Fehler bei der Sendungsverfolgung beheben

Fehler, die asynchron beim Anfordern von Versandinformationen auftreten, lösen error-Ereignisse aus. Im folgenden Beispiel sehen Sie, wie Sie auf diese Ereignisse warten, um Fehler zu beheben.

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:Achten Sie darauf, Bibliotheksaufrufe in try...catch-Blöcke einzuschließen, um unerwartete Fehler zu beheben.

Nächste Schritte