Sendungen mit der JavaScript Shipment Tracking Library verfolgen

Mit der JavaScript-Bibliothek zur Sendungsverfolgung können Sie die Standorte von Fahrzeugen und relevanten Standorten in Fleet Engine visualisieren. Die Bibliothek enthält eine JavaScript-Kartenkomponente, die ein Drop-in-Ersatz für eine standardmäßige google.maps.Map-Entität sowie Datenkomponenten für die Verbindung mit Fleet Engine ist. Mit der JavaScript-Bibliothek zur Sendungsverfolgung können Sie über Ihre Webanwendung eine anpassbare, animierte Versandverfolgung bereitstellen.

Komponenten

Die JavaScript-Bibliothek für die Sendungsverfolgung bietet Komponenten zur Visualisierung des Fahrzeugs und der Route während des Transports an ein Ziel sowie Rohdatenfeeds für die voraussichtliche Ankunftszeit eines Fahrers oder die verbleibende Strecke.

Kartenansicht für die Sendungsverfolgung

Die Kartenansichtskomponente visualisiert die Position von Fahrzeugen und Zielen. Wenn die Route für ein Fahrzeug bekannt ist, animiert die Kartenansichtskomponente das Fahrzeug, während es sich entlang des vorhergesagten Pfads bewegt.

Lieferortanbieter

Ein Lieferortanbieter fügt Standortinformationen für beobachtete Objekte in die Sendungsverfolgungskarte für die erste und letzte Meile ein.

Mit dem Versandortanbieter können Sie Folgendes verfolgen:

• Der Abhol- oder Lieferort einer Sendung.
• Standort und Route des Lieferfahrzeugs.

Erfasste Standortobjekte

Der Standortanbieter erfasst den Standort von Objekten wie Fahrzeugen und Zielen.

Zielspeicherort

Der Zielort ist der Ort, an dem eine Fahrt endet. Zur Sendungsverfolgung ist dies der Ort der geplanten Aufgabe.

Fahrzeugstandort

Der Fahrzeugstandort ist der beobachtete Standort eines Fahrzeugs. Sie kann optional auch eine Route für das Fahrzeug enthalten.

Authentifizierungstoken-Abruf

Wenn Sie den Zugriff auf die in Fleet Engine gespeicherten Standortdaten steuern möchten, müssen Sie auf Ihrem Server einen Erstellungsdienst für JSON Web Token (JWT) für Fleet Engine implementieren. Implementieren Sie dann einen Authentifizierungstoken-Abruf als Teil Ihrer Webanwendung. Verwenden Sie dabei die JavaScript Journey Sharing Library, um den Zugriff auf die Standortdaten zu authentifizieren.

Stiloptionen

Mit Markierungs- und Polylinienstilen wird das Design der beobachteten Standortobjekte auf der Karte festgelegt. Mit benutzerdefinierten Stiloptionen können Sie den Standardstil so ändern, dass er dem Stil Ihrer Webanwendung entspricht.

Sichtbarkeit von beobachteten Orten steuern

In diesem Abschnitt werden die Steuerelemente für die Sichtbarkeit von erfassten Objekten auf der Karte beschrieben. Diese Regeln gelten für zwei Kategorien von Objekten:

• Standortmarkierung
• Aufgabendaten

Sichtbarkeit der Standortmarkierung

Alle Standortmarkierungen für den Start- und Zielort werden immer auf der Karte angezeigt. Beispielsweise wird ein Lieferort immer auf der Karte angezeigt, unabhängig vom Status der Lieferung.

Sichtbarkeit von Aufgabendaten

In diesem Abschnitt werden die standardmäßigen Sichtbarkeitsregeln beschrieben, die für Aufgabendaten wie Fahrzeugstandort und verbleibende Route gelten. Viele Aufgaben lassen sich anpassen, aber nicht alle:

• Nichtverfügbarkeitsaufgaben: Sie können die Sichtbarkeit dieser Aufgaben nicht anpassen.
• Aktive Fahrzeugaufgaben – Sie können diese Art von Aufgaben anpassen.
• Inaktive Fahrzeugaufgaben: Sie können die Sichtbarkeit für diese Aufgaben nicht anpassen.

Nichtverfügbarkeitsaufgaben

Wenn es auf der Route zur erfassten Aufgabe mindestens eine Aufgabe gibt, die nicht verfügbar ist (z. B. wenn der Fahrer eine Pause macht oder das Fahrzeug aufgetankt wird), ist das Fahrzeug nicht sichtbar. Die geschätzte Ankunftszeit und die geschätzte Zeit für die Aufgabenerledigung sind weiterhin verfügbar.

Aktive Fahrzeugaufgaben

Das TaskTrackingInfo-Objekt bietet eine Reihe von Datenelementen, die in der Sendungsverfolgungsbibliothek sichtbar gemacht werden können. Standardmäßig sind diese Felder sichtbar, wenn die Aufgabe dem Fahrzeug zugewiesen wird und das Fahrzeug maximal fünf Haltestellen von der Aufgabe entfernt ist. Die Sichtbarkeit endet, wenn die Aufgabe abgeschlossen oder abgebrochen wird. Die Felder sind:

• Polylinien der Route
• Voraussichtliche Ankunftszeit
• Geschätzte Zeit für die Erledigung der Aufgaben
• Verbleibende Fahrstrecke zur Aufgabe
• Anzahl der verbleibenden Haltestellen
• Fahrzeugstandort

Sie können die Sichtbarkeitskonfiguration für einzelne Aufgaben anpassen. Legen Sie dazu beim Erstellen oder Aktualisieren der Aufgabe in Fleet Engine den TaskTrackingViewConfig für eine Aufgabe fest. Dadurch werden Regeln für die Verfügbarkeit einzelner Datenelemente erstellt, die auf den folgenden Kriterien (unten als Sichtbarkeitsoption bezeichnet) basieren können:

• Anzahl der verbleibenden Haltestellen
• Dauer bis zur voraussichtlichen Ankunftszeit
• Verbleibende Fahrstrecke
• Immer sichtbar
• Nie sichtbar

Jedes Datenelement kann nur mit einer Sichtbarkeitsoption verknüpft werden. Kriterien können nicht mit ODER oder UND kombiniert werden.

Hier ein Beispiel für eine Anpassung. Für diese Anpassung gelten folgende Regeln:

• Linienzüge der Route anzeigen, wenn sich das Fahrzeug innerhalb von drei Haltestellen befindet.
• Gib die voraussichtliche Ankunftszeit an, wenn die verbleibende Fahrstrecke weniger als 5.000 Meter beträgt.
• Die Anzahl der verbleibenden Haltestellen wird niemals angezeigt.
• Alle anderen Felder behalten die Standardsichtbarkeit und werden angezeigt, wenn sich das Fahrzeug innerhalb von fünf Haltestellen vor der Aufgabe befindet.

"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Sie können die Standardkonfiguration für die Sichtbarkeit für Ihr Projekt auch anpassen. Wenden Sie sich dazu an das Supportteam.

Polylinien der Routen und Sichtbarkeitsregeln für Fahrzeugstandorte:

Wenn Polylinien der Routen sichtbar sind, muss auch der Standort des Fahrzeugs sichtbar sein. Andernfalls kann der Standort des Fahrzeugs am Ende der Polylinien angegeben werden. Daher darf die Sichtbarkeitsoption für Routenlinien nicht weniger einschränkend sein.

Die folgenden Regeln müssen eingehalten werden, damit eine gültige Kombination aus Routenpolygonen und Fahrzeugstandort sichtbar ist:

• Wenn Routenpolygone und Fahrzeugstandort denselben Sichtbarkeitsoptionentyp haben:

  • Wenn als Sichtbarkeitsoption die Anzahl der verbleibenden Haltestellen, die Dauer bis zur voraussichtlichen Ankunftszeit oder die verbleibende Fahrtstrecke angegeben werden soll, muss für die Routenpolygone ein Wert angegeben werden, der kleiner oder gleich dem Wert ist, der für diese Sichtbarkeitsoption für den Fahrzeugstandort festgelegt wurde. Hier ein Beispiel:

  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "vehicleLocationVisibility": {
      "remainingStopCountThreshold": 5
    },
  }
  

  • Wenn bei Polylinien von Routen eine Sichtbarkeitsoption immer sichtbar ist, muss für den Fahrzeugstandort auch eine Sichtbarkeitsoption verfügbar sein, die immer sichtbar ist.
  • Wenn für den Fahrzeugstandort eine Sichtbarkeitsoption festgelegt ist, die nie sichtbar ist, muss die Sichtbarkeit auch für Routenpolygone immer sichtbar sein.

• Wenn Routenpolygone und Fahrzeugstandort unterschiedliche Sichtbarkeitsoptionen haben, ist der Fahrzeugstandort nur sichtbar, wenn beide Sichtbarkeitsoptionen erfüllt sind.

  Hier ein Beispiel:

  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "vehicleLocationVisibility": {
      "remainingDrivingDistanceMetersThreshold": 3000
    },
  }
  

  In diesem Beispiel ist der Fahrzeugstandort nur dann sichtbar, wenn die Anzahl der verbleibenden Haltestellen mindestens 3 beträgt UND die verbleibende Fahrstrecke mindestens 3.000 Meter beträgt.

Einführung in die JavaScript-Bibliothek zum Teilen von Onlinerecherchen

Bevor Sie die JavaScript Journey Sharing Library verwenden, sollten Sie mit Fleet Engine vertraut sein und einen API-Schlüssel anfordern.

Wenn Sie eine Lieferung erfassen möchten, müssen Sie zuerst einen Tracking-ID-Anspruch erheben.

Tracking-ID-Anspruch erheben

Um eine Sendung über den Versandortanbieter zu verfolgen, erstellen Sie ein JSON Web Token (JWT) mit einer Sendungs-ID-Anforderung.

Fügen Sie zum Erstellen der JWT-Nutzlast eine zusätzliche Anforderung mit dem Schlüssel trackingid im Autorisierungsbereich hinzu. Legen Sie als Wert die Sendungsverfolgungs-ID fest.

Das folgende Beispiel zeigt, wie Sie ein Token für das Tracking nach Tracking-ID erstellen:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "trackingid": "tid_54321",
   }
}

Authentifizierungstoken-Abruf erstellen

Sie können einen Authentifizierungstoken-Abruf erstellen, um ein mit den entsprechenden Anforderungen erstelltes Token auf Ihren Servern mithilfe eines Dienstkontozertifikats für Ihr Projekt abzurufen. Es ist wichtig, nur Tokens auf Ihren Servern zu erstellen und Ihre Zertifikate niemals auf Clients freizugeben. Andernfalls gefährden Sie die Sicherheit Ihres Systems.

Der Fetcher muss eine Datenstruktur mit zwei Feldern zurückgeben, die in ein Promise eingeschlossen sind:

• Einen String token.
• Eine Zahl expiresInSeconds. In dieser Zeit läuft ein Token nach dem Abruf ab.

Die JavaScript-Bibliothek zur Sendungsverfolgung fordert über den Authentifizierungstoken-Abruf ein Token an, wenn eine der folgenden Bedingungen zutrifft:

• Sie hat kein gültiges Token, z. B. wenn der Fetcher bei einem neuen Seitenaufbau nicht aufgerufen wurde oder wenn der Fetcher kein Token zurückgegeben hat.
• Das zuvor abgerufene Token ist abgelaufen.
• Das zuvor abgerufene Token läuft innerhalb einer Minute ab.

Andernfalls verwendet die Bibliothek das zuvor ausgestellte, noch gültige Token und ruft den Fetcher nicht auf.

Das folgende Beispiel zeigt, wie ein Authentifizierungstoken-Abruf erstellt wird:

function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

Bei der Implementierung des serverseitigen Endpunkts für die Münzprägung von Tokens ist Folgendes zu beachten:

• Der Endpunkt muss eine Ablaufzeit für das Token zurückgeben. Im obigen Beispiel wird sie als data.ExpiresInSeconds angegeben.
• Der Authentifizierungstoken-Abruf muss die Ablaufzeit (in Sekunden vom Zeitpunkt des Abrufs) an die Bibliothek übergeben, wie im Beispiel gezeigt.
• Die SERVER_TOKEN_URL hängt von Ihrer Back-End-Implementierung ab. Dies sind die URLs für das Beispiel-App-Back-End:
  • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
  • https://SERVER_URL/token/fleet_reader

Karte aus HTML laden

Das folgende Beispiel zeigt, wie die JavaScript-Bibliothek zur Sendungsverfolgung über eine angegebene URL geladen wird. Der callback-Parameter führt die initMap-Funktion aus, nachdem die API geladen wurde. Mit dem Attribut defer kann der Browser den Rest Ihrer Seite weiterhin rendern, während die API geladen wird.

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

Sendung verfolgen

In diesem Abschnitt wird beschrieben, wie du die JavaScript-Bibliothek zur Sendungsverfolgung verwenden kannst, um die Abholung oder Zustellung einer Sendung zu verfolgen. Laden Sie die Bibliothek über die im Skript-Tag angegebene Callback-Funktion, bevor Sie den Code ausführen.

Anbieter für Lieferorte instanziieren

In der JavaScript-Bibliothek für die Sendungsverfolgung ist für die Fleet Engine Deliveries API ein Standortanbieter vordefiniert. Verwenden Sie Ihre Projekt-ID und einen Verweis auf Ihre Token-Factory, um sie zu instanziieren.

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

Kartenansicht initialisieren

Initialisieren Sie nach dem Laden der JavaScript Journey Sharing-Bibliothek die Kartenansicht und fügen Sie sie der HTML-Seite hinzu. Die Seite muss ein <div>-Element enthalten, das die Kartenansicht enthält. Im folgenden Beispiel heißt das <div>-Element map_canvas.

Um Race-Bedingungen zu vermeiden, legen Sie die Tracking-ID für den Standortanbieter im Callback fest, der nach der Initialisierung der Karte aufgerufen wird.

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // 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 will start 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);

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // 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 will start 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);

Tracking-ID

Die dem Standortanbieter bereitgestellte Tracking-ID kann mehreren Aufgaben entsprechen, z. B. einer Abhol- und einer Zustellaufgabe für dasselbe Paket oder mehreren fehlgeschlagenen Zustellversuchen. Eine Aufgabe wurde ausgewählt, die auf der Sendungsverfolgungskarte angezeigt wird. Die anzuzeigende Aufgabe wird wie folgt festgelegt:

1. Wenn genau eine offene Abholaufgabe vorhanden ist, wird sie angezeigt. Bei mehreren offenen Abholaufgaben wird ein Fehler ausgegeben.
2. Wenn es genau eine offene Zustellaufgabe gibt, wird sie angezeigt. Bei mehreren offenen Übermittlungsaufgaben wird ein Fehler ausgegeben.
3. Wenn es geschlossene Zustellaufgaben gibt:
   • Wenn es genau eine abgeschlossene Lieferaufgabe gibt, wird diese angezeigt.
   • Wenn es mehrere geschlossene Lieferaufgaben gibt, wird die letzte Ergebniszeit angezeigt.
   • Wenn es mehrere geschlossene Lieferaufgaben gibt, von denen keine eine Ergebniszeit hat, wird ein Fehler generiert.
4. Wenn es geschlossene Abholaufgaben gibt:
   • Wenn es genau eine abgeschlossene Abholaufgabe gibt, wird diese angezeigt.
   • Wenn es mehrere abgeschlossene Abholaufgaben gibt, wird die mit der letzten Ergebniszeit angezeigt.
   • Wenn mehrere geschlossene Abholaufgaben vorhanden sind, von denen keine eine Ergebniszeit hat, wird ein Fehler generiert.
5. Andernfalls wird keine Aufgabe angezeigt.

Änderungsereignisse beobachten

Metainformationen zu einer Aufgabe können Sie mit dem Standortanbieter aus dem Aufgaben-Tracking-Infoobjekt abrufen. Dazu gehören die voraussichtliche Ankunftszeit, die Anzahl der verbleibenden Haltestellen und die verbleibende Entfernung vor Abholung oder Lieferung. Änderungen an den Metainformationen lösen ein update-Ereignis aus. Das folgende Beispiel zeigt, wie Sie auf diese Änderungsereignisse warten.

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

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

Fehler verarbeiten

Fehler, die asynchron beim Anfordern von Versandinformationen auftreten, lösen error-Ereignisse aus. Das folgende Beispiel zeigt, wie auf diese Ereignisse gewartet wird, um Fehler zu beheben.

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

Hinweis:Bibliotheksaufrufe müssen in try...catch-Blöcken zusammengefasst werden, um unerwartete Fehler zu vermeiden.

Nicht mehr beobachten

Um zu verhindern, dass der Standortanbieter die Sendung verfolgt, entferne die entsprechende ID.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

Standortanbieter aus der Kartenansicht entfernen

Das folgende Beispiel zeigt, wie Sie einen Standortanbieter aus der Kartenansicht entfernen.

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

Design der Basiskarte anpassen

Sie können das Erscheinungsbild der Kartenkomponente anpassen, indem Sie mit cloudbasierten Tools die Karte gestalten oder Optionen direkt im Code festlegen.

Cloudbasiertes Gestalten von Karteninhalten

Mit dem cloudbasierten Kartenstil können Sie über die Google Cloud Console Kartenstile für alle Apps erstellen und bearbeiten, in denen Google Maps verwendet wird, ohne dass Änderungen am Code erforderlich sind. Die Kartenstile werden als Karten-IDs im Cloud-Projekt gespeichert. Wenn Sie einen Stil auf Ihre JavaScript-Karte für die Sendungsverfolgung anwenden möchten, geben Sie beim Erstellen der JourneySharingMapView einen mapId an. Das Feld mapId kann nicht mehr geändert oder hinzugefügt werden, nachdem JourneySharingMapView instanziiert wurde. Im folgenden Beispiel wird gezeigt, wie Sie einen zuvor erstellten Kartenstil mit einer Karten-ID aktivieren.

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

Codebasierte Kartenstile verwenden

Eine weitere Möglichkeit, den Kartenstil anzupassen, besteht darin, mapOptions beim Erstellen des JourneySharingMapView festzulegen.

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

Anpassungen von Markierungen verwenden

Mit der JavaScript-Bibliothek zur Sendungsverfolgung können Sie das Erscheinungsbild von Markierungen anpassen, die der Karte hinzugefügt werden. Dazu legen Sie Anpassungen für Markierungen fest, die die Bibliothek für die Sendungsverfolgung anwendet, bevor sie der Karte und bei jeder Markierungsaktualisierung hinzugefügt wird.

Die einfachste Anpassung besteht darin, ein MarkerOptions-Objekt anzugeben, das auf alle Markierungen desselben Typs angewendet wird. Die im Objekt angegebenen Änderungen werden angewendet, nachdem die jeweilige Markierung erstellt wurde. Dabei werden alle Standardoptionen überschrieben.

Eine erweiterte Option besteht darin, eine Anpassungsfunktion anzugeben. Mit Anpassungsfunktionen können Sie Markierungen auf Grundlage von Daten gestalten und Interaktionen hinzufügen, z. B. die Verarbeitung von Klicks. Insbesondere werden bei der Sendungsverfolgung Daten über den Objekttyp, den die Markierung darstellt, an die Anpassungsfunktion gesendet: Fahrzeug oder Ziel. Der Stil der Markierung kann sich dann basierend auf dem aktuellen Status des Markierungselements ändern, z. B. der Anzahl der geplanten Haltestellen bis zum Ziel. Sie können sogar Daten aus Quellen außerhalb von Fleet Engine zusammenführen und die Markierung basierend auf diesen Informationen gestalten.

Die Bibliothek für die Sendungsverfolgung bietet die folgenden Anpassungsparameter in FleetEngineShipmentLocationProviderOptions:

• deliveryVehicleMarkerCustomization
• destinationMarkerCustomization

Stil von Markierungen mit MarkerOptions ändern

Das folgende Beispiel zeigt, wie Sie den Stil einer Fahrzeugmarkierung mit einem MarkerOptions-Objekt konfigurieren. Folgen Sie diesem Muster, um den Stil einer Markierung mithilfe der oben aufgeführten Anpassungen anzupassen.

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Stil von Markierungen mithilfe von Anpassungsfunktionen ändern

Das folgende Beispiel zeigt, wie Sie den Stil einer Fahrzeugmarkierung konfigurieren. Folgen Sie diesem Muster, um den Stil einer Markierung mithilfe der oben aufgeführten Parameter zur Anpassung der Markierung anzupassen.

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

Markierungen für Klick-Handhabung hinzufügen

Im folgenden Beispiel sehen Sie, wie einer Fahrzeugmarkierung die Klickbehandlung hinzugefügt wird. Folgen Sie diesem Muster, um jeder Markierung mithilfe eines der oben aufgeführten Anpassungsparameter die Klickverarbeitung hinzuzufügen.

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

Polylinienanpassungen verwenden

Mit der Bibliothek für die Sendungsverfolgung können Sie auch das Design der Versandroute auf der Karte anpassen. Die Bibliothek erstellt für jedes Koordinatenpaar im aktiven oder verbleibenden Pfad der Sendung ein google.maps.Polyline-Objekt. Sie können die Polyline-Objekte gestalten, indem Sie Polylinienanpassungen angeben. Die Bibliothek wendet diese Anpassungen dann in zwei Situationen an: vor dem Hinzufügen der Objekte zur Karte und wenn sich die für die Objekte verwendeten Daten geändert haben.

Ähnlich wie bei der Anpassung von Markierungen können Sie einen Satz von PolylineOptions angeben, der auf alle übereinstimmenden Polyline-Objekte angewendet wird, wenn diese erstellt oder aktualisiert werden.

Ebenso können Sie eine Anpassungsfunktion angeben. Anpassungsfunktionen ermöglichen eine individuelle Gestaltung der Objekte basierend auf den von Fleet Engine gesendeten Daten. Die Funktion kann den Stil jedes Objekts basierend auf dem aktuellen Versandstatus ändern. So kann das Polyline-Objekt einen tieferen Farbton eingefärbt oder es dicker gemacht werden, wenn das Fahrzeug langsamer ist. Sie können sogar eine Zusammenführung mit Quellen außerhalb von Fleet Engine durchführen und das Polyline-Objekt anhand dieser Informationen gestalten.

Sie können die Anpassungen mithilfe von Parametern in FleetEngineShipmentLocationProviderOptions angeben. Sie können Anpassungen für verschiedene Pfadzustände der Fahrt des Fahrzeugs vornehmen – also bereits zurückgelegt, aktiv oder noch nicht zurückgelegt. Die Parameter sind:

• takenPolylineCustomization für einen bereits zurückgelegten Pfad
• activePolylineCustomization für einen aktiv bewegenden Pfad
• remainingPolylineCustomization für einen noch nicht zurückgelegten Pfad.

Stil von Polyline-Objekten mit PolylineOptions ändern

Das folgende Beispiel zeigt, wie der Stil für ein Polyline-Objekt mit PolylineOptions konfiguriert wird. Folgen Sie diesem Muster, um den Stil eines Polyline-Objekts mithilfe der zuvor aufgeführten Anpassungen für Polylinien anzupassen.

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

Stil von Polyline-Objekten mithilfe von Anpassungsfunktionen ändern

Das folgende Beispiel zeigt, wie Sie die Gestaltung eines aktiven Polyline-Objekts konfigurieren. Folgen Sie diesem Muster, um den Stil eines Polyline-Objekts mithilfe der zuvor aufgeführten Parameter zur Anpassung von Polylinien anzupassen.

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

Sichtbarkeit von Polyline-Objekten steuern

Standardmäßig sind alle Polyline-Objekte sichtbar. Wenn Sie ein Polyline-Objekt unsichtbar machen möchten, legen Sie dessen Attribut visible fest:

remainingPolylineCustomization = {visible: false};

remainingPolylineCustomization = {visible: false};

InfoWindow für ein Fahrzeug oder eine Standortmarkierung anzeigen

Mit InfoWindow können Sie zusätzliche Informationen zu einem Fahrzeug oder einer Standortmarkierung anzeigen lassen.

Das folgende Beispiel zeigt, wie ein InfoWindow erstellt und an eine Fahrzeugmarkierung angehängt wird:

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Automatische Anpassung deaktivieren

Sie können verhindern, dass der Darstellungsbereich der Karte automatisch an das Fahrzeug und die erwartete Route angepasst wird, indem Sie die automatische Anpassung deaktivieren. Das folgende Beispiel zeigt, wie Sie die automatische Anpassung deaktivieren, wenn Sie die Kartenansicht für die Fahrtfreigabe konfigurieren.

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.   
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Vorhandene Karte ersetzen

Mit der JavaScript-Bibliothek zur Sendungsverfolgung können Sie eine vorhandene Karte ersetzen, die Markierungen oder andere Anpassungen enthält, ohne dass diese Anpassungen verloren gehen.

Angenommen, Sie haben eine Webseite mit einer Standardentität google.maps.Map, auf der eine Markierung angezeigt wird:

<!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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, map: map});
}
    </script>
    <!-- Load the API from the specified URL.
       * The async attribute allows the browser to render the page while the API loads.
       * The key parameter will contain your own API key (which is not needed for this tutorial).
       * 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>

So fügen Sie die Bibliothek zum Teilen von JavaScript-Reisen hinzu:

1. Fügen Sie Code für die Authentifizierungstoken-Factory hinzu.
2. Initialisieren Sie einen Standortanbieter in der Funktion initMap().
3. Initialisieren Sie die Kartenansicht in der Funktion initMap(). Die Ansicht enthält die Karte.
4. Verschieben Sie Ihre Anpassung in die Callback-Funktion zur Initialisierung der Kartenansicht.
5. Fügen Sie dem API-Ladeprogramm die Standortbibliothek hinzu.

Das folgende Beispiel zeigt die erforderlichen Änderungen:

<!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>
let locationProvider;

// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
  // options is a record containing two keys called 
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
      if (!response.ok) {
        throw new Error(response.statusText);
      }
      const data = await response.json();
      return {
        token: data.Token,
        expiresInSeconds: data.ExpiresInSeconds
      };
}

// Initialize and add the map
function initMap() {
  // (2) Initialize location provider.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    YOUR_PROVIDER_ID,
    authTokenFetcher,
  });

  // (3) Initialize map view (which contains the map).
  const mapView = new google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map'),
    locationProviders: [locationProvider],
    // any styling options
  });

  locationProvider.trackingId = TRACKING_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, map: map});
  };

    </script>
    <!-- Load the API from the specified URL
      * The async attribute allows the browser to render the page while the API loads
      * The key parameter will contain your own API key (which is not needed for this tutorial)
      * The callback parameter executes the initMap() function
      *
      * (5) Add the journey sharing library to the API loader.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

Wenn Sie ein verfolgtes Paket mit der angegebenen ID in der Nähe von Uluru haben, wird es jetzt auf der Karte gerendert.