Sendung verfolgen

Nachdem Sie das JavaScript Consumer SDK für geplante Aufgaben eingerichtet haben, können Sie mit Ihrer Verbraucher-App Sendungen verfolgen. In diesem Dokument werden die folgenden wichtigen Schritte dieses Prozesses beschrieben:

  • Karte initialisieren und geteilte Fahrt anzeigen
  • Aktualisieren und Fahrtverlauf verfolgen
  • Sendung nicht mehr verfolgen
  • Fehler bei der Sendungsverfolgung behandeln

Karte einrichten

Wenn Sie den Status einer Sendungsabholung oder -zustellung in Ihrer Webanwendung 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 zu verfolgenden 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 Webanwendung. 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 einem standardmäßigen google.maps.Map-Element, auf dem eine Markierung angezeigt wird, wie im folgenden HTML-Code definiert. So wird Ihre Karte mit derselben initMap-Funktion 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 Versandort erstellen

Verwenden Sie den Lieferortanbieter zusammen mit dem zuvor definierten Autorisierungstoken-Abruf, um mit dem Empfang von Daten von Fleet Engine zu beginnen.

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 Fahrt anzeigen

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

Tipps:

  1. Ihre Seite muss das Element <div> enthalten, das die Kartenansicht enthält. Im folgenden Beispiel heißt das &lt;div&gt;-Element map_canvas.

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

Diese Beispiele zeigen, 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);
}

Versandstatus aktualisieren

Sie können auf Ereignisse warten und den Versandfortschritt während des Bestellvorgangs aktualisieren. Verwenden Sie den Standortanbieter, um Metainformationen vom taskTrackingInfo-Objekt abzurufen. Änderungen an den Metadaten lösen ein Update-Ereignis aus. Das taskTrackingInfo-Objekt bietet Folgendes:

  • ETA
  • Anzahl der verbleibenden Haltestellen
  • Verbleibende Strecke bis zur Abholung oder Lieferung

Das folgende Beispiel zeigt, wie Sie auf diese Änderungsereignisse reagieren.

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 auf der Karte nur eine Aufgabe pro Tracking-ID an. Normalerweise weisen Sie jedoch auch einer bestimmten Sendung eine Tracking-ID zu, die während des gesamten Transports in Ihrem System mit dem Gut verknüpft bleibt. Das bedeutet, dass einer einzelnen Tracking-ID mehrere Aufgaben zugeordnet werden können, z. B. eine Abholaufgabe, gefolgt von einer Zustellaufgabe für dasselbe Paket, oder mehrere fehlgeschlagene Versandaufgaben für ein Paket.

In diesem Fall werden von Fleet Engine Kriterien für die Anzeige von Aufgaben angewendet, die in der folgenden Tabelle aufgeführt sind.

Aufgabenkriterien Ergebnis
Abholaufgaben öffnen
Es gibt genau eine. Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Abgeschlossene Abholaufgaben
Genau eins vorhanden Aufgabe anzeigen
Mehrere vorhanden (teilweise mit Ergebniszeit) Aufgabe mit dem letzten Ergebniszeitpunkt anzeigen
Es gibt mehrere (keine mit Ergebniszeiten) Fehler generieren
Öffnen Sie die Bereitstellungsaufgaben.
Es gibt genau eine. Aufgabe anzeigen
Mehrere vorhanden Fehler generieren
Aufgaben mit geschlossener Zustellung
Genau eins vorhanden Aufgabe anzeigen
Mehrere vorhanden (teilweise mit Ergebniszeit) Aufgabe mit dem letzten Ergebniszeitpunkt anzeigen
Es gibt mehrere (keine mit Ergebniszeiten) Fehler generieren

Sendung nicht mehr verfolgen

Wenn ein Versandvorgang 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 nicht mehr möchten, dass der Standortanbieter die Sendung verfolgt, entfernen Sie die Tracking-ID vom Standortanbieter. Die folgenden Beispiele zeigen, wie das geht.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Standortanbieter aus der Kartenansicht entfernen

Im folgenden Beispiel wird gezeigt, wie ein Standortanbieter aus der Kartenansicht entfernt wird.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Fehler bei der Sendungsverfolgung behandeln

Fehler, die asynchron beim Anfordern von Versandinformationen auftreten, lösen Fehlerereignisse aus. Im folgenden Beispiel wird gezeigt, wie Sie auf diese Ereignisse warten, um Fehler zu verarbeiten.

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: Um unerwartete Fehler zu behandeln, müssen Bibliotheksaufrufe in try...catch-Blöcke eingeschlossen werden.

Nächste Schritte