Sendungen mit der JavaScript Shipment Tracking Library verfolgen

Mit der JavaScript Shipment Tracking Library können Sie den Standort von Fahrzeugen und die Standorte von Interesse visualisieren, die in Fleet Engine erfasst werden. Die Bibliothek enthält eine JavaScript-Kartenkomponente, die als Drop-in-Ersatz eine standardmäßige google.maps.Map-Entität und Datenkomponenten zur Verbindung mit Fleet Engine ersetzt. Mit der JavaScript Shipment Tracking Library kannst du über deine Webanwendung eine anpassbare, animierte Sendungsverfolgung anbieten.

Komponenten

Die JavaScript Shipment Tracking Library enthält Komponenten zur Visualisierung des Fahrzeugs und der Route auf dem Weg zu einem Ziel sowie Rohdatenfeeds für die voraussichtliche Ankunftszeit des Fahrers oder die verbleibende Strecke.

Kartenansicht für die Sendungsverfolgung

Mit der Komponente „Kartenansicht“ werden die Position von Fahrzeugen und Ziele visualisiert. Wenn die Route für ein Fahrzeug bekannt ist, animiert die Komponente für die Kartenansicht das Fahrzeug, während es sich auf dem vorhergesagten Weg bewegt.

Lieferortanbieter

Ein Lieferortanbieter fügt für die Sendungsverfolgung auf der ersten und letzten Meile Standortinformationen für verfolgte Objekte in die Karte der Sendungsverfolgung ein.

Mit dem Anbieter des Versandorts können Sie Folgendes verfolgen:

  • Der Abhol- oder Lieferort einer Sendung.
  • Der Standort und die 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. Für die Sendungsverfolgung ist dies der Ort der geplanten Aufgabe.

Fahrzeugstandort

Der Fahrzeugstandort ist der nachverfolgte Standort eines Fahrzeugs. Optional kann eine Route für das Fahrzeug angegeben werden.

Abruf von Authentifizierungstokens

Wenn Sie den Zugriff auf die in Fleet Engine gespeicherten Standortdaten steuern möchten, müssen Sie auf Ihrem Server einen JWT-Minting-Dienst (JSON Web Token) für Fleet Engine implementieren. Implementiere dann einen Abruf von Authentifizierungstokens als Teil deiner Webanwendung mithilfe der JavaScript Journey Sharing Library, um den Zugriff auf die Standortdaten zu authentifizieren.

Stiloptionen

Markierungs- und Polylinienstile bestimmen das Design der erfassten Standortobjekte auf der Karte. Mit benutzerdefinierten Stiloptionen können Sie den Standardstil so ändern, dass er zum Stil Ihrer Webanwendung passt.

Sichtbarkeit von beobachteten Orten festlegen

In diesem Abschnitt werden die Sichtbarkeitseinstellungen für beobachtete Objekte auf der Karte beschrieben. Diese Regeln gelten für zwei Objektkategorien:

  • Standortmarkierung
  • Aufgabendaten

Sichtbarkeit der Standortmarkierung

Alle Standortmarkierungen für Start- und Zielort werden immer auf der Karte angezeigt. Beispielsweise wird auf der Karte immer der Lieferort einer Sendung angezeigt, unabhängig vom Lieferstatus.

Sichtbarkeit von Aufgabendaten

In diesem Abschnitt werden die Standardregeln für die Sichtbarkeit beschrieben, die für Aufgabendaten wie den Fahrzeugstandort und die verbleibende Route gelten. Sie können viele, aber nicht alle Aufgaben anpassen:

  • Nicht verfügbare Aufgaben: Sie können die Sichtbarkeit für diese 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.

Nicht verfügbare Aufgaben

Wenn auf der Route zur erfassten Aufgabe mindestens eine Nichtverfügbarkeitsaufgabe besteht (z. B. wenn der Fahrer eine Pause macht oder das Fahrzeug betankt wird), ist das Fahrzeug nicht sichtbar. Die voraussichtliche Ankunftszeit und die geschätzte Fertigstellungszeit der Aufgabe sind weiterhin verfügbar.

Aktive Fahrzeugaufgaben

Das TaskTrackingInfo-Objekt bietet eine Reihe von Datenelementen, die in der Shipment Tracking Library sichtbar gemacht werden können. Standardmäßig sind diese Felder sichtbar, wenn die Aufgabe dem Fahrzeug zugewiesen wird und wenn sich das Fahrzeug nicht mehr als fünf Haltestellen von der Aufgabe entfernt befindet. Die Sichtbarkeit endet, wenn die Aufgabe abgeschlossen oder abgebrochen wird. Es gibt folgende Felder:

  • Polylinien für Routen
  • Geschätzte Ankunftszeit
  • Geschätzte Fertigstellungszeit für Aufgaben
  • Verbleibende Fahrstrecke zur Aufgabe
  • Anzahl der verbleibenden Haltestellen
  • Fahrzeugstandort

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

  • Anzahl der verbleibenden Haltestellen
  • Reisedauer 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.

Im Folgenden finden Sie ein Beispiel für die Anpassung. Für diese Anpassung gelten folgende Regeln:

  • Polylinien der Route anzeigen, wenn sich das Fahrzeug innerhalb von drei Haltestellen befindet.
  • Voraussichtliche Ankunftszeit anzeigen, wenn die verbleibende Fahrstrecke kürzer als 5.000 Meter ist.
  • Die Anzahl der verbleibenden Haltestellen nie anzeigen.
  • Jedes andere Feld behält die Standardsichtbarkeit bei, die angezeigt wird, wenn sich das Fahrzeug innerhalb von 5 Haltestellen von der Aufgabe befindet.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Wenn Sie die standardmäßige Sichtbarkeitskonfiguration für Ihr Projekt anpassen möchten, wenden Sie sich an das Supportteam.

Polylinien für Routen und Sichtbarkeitsregeln für Fahrzeugstandorte:

Wenn Polylinien einer Route sichtbar sind, muss auch der Fahrzeugstandort sichtbar sein. Andernfalls kann der Fahrzeugstandort durch das Ende von Polylinien angegeben werden. Das bedeutet, dass die Sichtbarkeitsoption für Polylinien nicht weniger restriktiv sein kann.

Damit eine gültige Kombination aus Polylinien und Fahrzeugstandorten sichtbar ist, müssen die folgenden Regeln eingehalten werden:

  • Wenn Polylinien für Routen und der Fahrzeugstandort denselben Sichtbarkeitsoptionstyp haben:

    • Wenn als Sichtbarkeitsoption die Anzahl der Haltestellen, die Dauer bis zur voraussichtlichen Ankunftszeit oder die verbleibende Fahrstrecke festgelegt ist, muss für Polylinien der Route ein Wert angegeben werden, der kleiner oder gleich dem Wert ist, der für diese Sichtbarkeitsoption für den Fahrzeugstandort festgelegt ist. Hier ein Beispiel:
    "taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
    • Wenn die Sichtbarkeitsoption für Polylinien der Route immer sichtbar ist, muss für den Fahrzeugstandort auch eine immer sichtbare Sichtbarkeitsoption zur Verfügung stehen.
    • Wenn für den Fahrzeugstandort die Sichtbarkeitsoption „Nie sichtbar“ festgelegt ist, muss für Polylinien der Route auch die Option „Nie sichtbar“ verfügbar sein.

  • Wenn Polylinien für Routen und Fahrzeugstandort unterschiedliche Sichtbarkeitsoptionstypen 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 sichtbar, wenn die Anzahl der verbleibenden Haltestellen mindestens 3 beträgt UND die verbleibende Fahrstrecke mindestens 3.000 Meter beträgt.

Erste Schritte mit der JavaScript Journey Sharing Library

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

Wenn du eine Lieferung verfolgen möchtest, musst du zuerst einen Anspruch auf die Tracking-ID erheben.

Tracking-ID-Anspruch erstellen

Wenn Sie eine Sendung über den Anbieter von Lieferorten verfolgen möchten, erstellen Sie ein JSON Web Token (JWT) mit einer Tracking-ID-Anforderung.

Fügen Sie zum Erstellen der JWT-Nutzlast im Autorisierungsabschnitt eine zusätzliche Anforderung mit dem Schlüssel trackingid 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",
   }
}

Abruf von Authentifizierungstokens erstellen

Sie können einen Abruf von Authentifizierungstokens erstellen, um mithilfe eines Dienstkontozertifikats für Ihr Projekt ein Token mit den entsprechenden Anforderungen auf Ihren Servern abzurufen. Es ist wichtig, nur Tokens auf Ihren Servern zu erstellen und Ihre Zertifikate nie auf Clients zu teilen. 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. Ein Token läuft in dieser Zeit nach dem Abruf ab.

Die JavaScript Shipment Tracking Library fordert über den Abruf von Authentifizierungstokens ein Token an, wenn eine der folgenden Bedingungen zutrifft:

  • Sie verfügt über kein gültiges Token, z. B. wenn der Fetcher bei einem neuen Seitenaufbau nicht aufgerufen wurde oder der Fetcher nicht mit einem 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 ausgegebene, noch gültige Token und ruft den Fetcher nicht auf.

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

JavaScript

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

TypeScript

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

Beachten Sie beim Implementieren des serverseitigen Endpunkts zum Erstellen der Tokens Folgendes:

  • Der Endpunkt muss eine Ablaufzeit für das Token zurückgeben. Im obigen Beispiel wird dies als data.ExpiresInSeconds angegeben.
  • Der Abruf von Authentifizierungstokens muss die Ablaufzeit (in Sekunden ab dem Zeitpunkt des Abrufs) wie im Beispiel gezeigt an die Bibliothek übergeben.
  • SERVER_TOKEN_URL hängt von Ihrer Back-End-Implementierung ab. Dies sind die URLs für das Back-End der Beispielanwendung:
    • 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 für die Sendungsverfolgung von einer angegebenen URL geladen wird. Der Parameter callback führt die Funktion initMap aus, nachdem die API geladen wurde. Mit dem Attribut defer kann der Browser den Rest der Seite weiter 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 mithilfe der JavaScript Shipment Tracking Library die Abholung oder Lieferung einer Sendung verfolgen kannst. Laden Sie die Bibliothek aus der im Skript-Tag angegebenen Callback-Funktion, bevor Sie den Code ausführen.

Anbieter von Versandorten instanziieren

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

JavaScript

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

TypeScript

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 Bibliothek für das Teilen der Reise die Kartenansicht und fügen Sie sie der HTML-Seite hinzu. Ihre Seite sollte ein <div>-Element enthalten, das die Kartenansicht enthält. Im folgenden Beispiel heißt das <div>-Element map_canvas.

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

JavaScript

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

TypeScript

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 an den 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 Karte der Sendungsverfolgung angezeigt werden soll. Die anzuzeigende Aufgabe wird wie folgt festgelegt:

  1. Wenn genau eine Abholaufgabe offen ist, wird sie angezeigt. Wenn mehrere offene Abholaufgaben vorhanden sind, wird ein Fehler generiert.
  2. Wenn genau eine offene Lieferaufgabe vorhanden ist, wird sie angezeigt. Wenn mehrere Aufgaben offen sind, wird ein Fehler generiert.
  3. Bei geschlossenen Lieferaufgaben:
    • Wenn genau eine geschlossene Lieferaufgabe vorhanden ist, wird sie angezeigt.
    • Wenn es mehrere geschlossene Lieferaufgaben gibt, wird die mit dem letzten Endergebnis angezeigt.
    • Wenn es mehrere geschlossene Lieferaufgaben gibt, von denen keine eine Ergebniszeit hat, wird ein Fehler generiert.
  4. Wenn Abholaufgaben geschlossen sind:
    • Wenn es genau eine geschlossene Abholaufgabe gibt, wird sie angezeigt.
    • Wenn es mehrere geschlossene Abholaufgaben gibt, wird die mit dem letzten Endergebnis angezeigt.
    • Wenn es mehrere geschlossene Abholaufgaben gibt, von denen keine eine Ergebniszeit hat, wird ein Fehler generiert.
  5. Andernfalls wird keine Aufgabe angezeigt.

Auf Änderungsereignisse warten

Mithilfe des Standortanbieters können Sie Metainformationen zu einer Aufgabe aus dem Objekt mit den Tracking-Informationen für die Aufgabe abrufen. Die Metainformationen enthalten die voraussichtliche Ankunftszeit, die Anzahl der verbleibenden Haltestellen und die verbleibende Strecke vor dem Abholen oder der Zustellung. Änderungen an den Metainformationen lösen ein update-Ereignis aus. 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);
});

Fehler verarbeiten

Fehler, die asynchron durch das Anfordern von Versandinformationen auftreten, lösen error-Ereignisse aus. Das folgende Beispiel zeigt, wie auf diese Ereignisse gewartet wird, 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:Bibliothekaufrufe müssen in try...catch-Blöcken umschlossen werden, um unerwartete Fehler zu vermeiden.

Nicht mehr beobachten

Wenn Sie verhindern möchten, dass der Standortanbieter die Sendung verfolgt, entfernen Sie die Tracking-ID vom Standortanbieter.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Standortanbieter aus der Kartenansicht entfernen

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Design der Basiskarte anpassen

Wenn Sie das Erscheinungsbild der Kartenkomponente anpassen möchten, können Sie mit cloudbasierten Tools Ihre Karte gestalten oder Optionen direkt im Code festlegen.

Cloudbasiertes Gestalten von Karteninhalten verwenden

Mit dem cloudbasierten Gestalten von Karteninhalten können Sie über die Google Cloud Console Kartenstile für alle Apps, in denen Google Maps verwendet wird, erstellen und bearbeiten, ohne dass Änderungen am Code erforderlich sind. Die Kartenstile werden als Karten-IDs in Ihrem Cloud-Projekt gespeichert. Wenn du einen Stil auf deine JavaScript-Karte für die Sendungsverfolgung anwenden möchtest, musst du beim Erstellen der JourneySharingMapView einen mapId angeben. 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.

JavaScript

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

TypeScript

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

Codebasiertes Gestalten von Karteninhalten verwenden

Eine weitere Möglichkeit zum Anpassen des Kartenstils besteht darin, mapOptions festzulegen, wenn Sie die JourneySharingMapView erstellen.

JavaScript

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

TypeScript

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

Benutzerdefinierte Markierungen verwenden

Mit der JavaScript Shipment Tracking Library kannst du das Aussehen und das Verhalten von Markierungen anpassen, die der Karte hinzugefügt wurden. Dazu musst du Markierungsanpassungen festlegen, die dann in der Versandverfolgungsbibliothek angewendet werden, bevor und bei jeder Markierungsaktualisierung der Karte Markierungen hinzugefügt werden.

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 einzelnen Markierungen erstellt wurden. Dabei werden alle Standardoptionen überschrieben.

Eine erweiterte Option besteht darin, eine Anpassungsfunktion anzugeben. Mithilfe von Anpassungsfunktionen können Sie Markierungen basierend auf Daten gestalten und den Markierungen interaktive Elemente hinzufügen, z. B. den Umgang mit Klicks. Insbesondere werden bei der Sendungsverfolgung Daten zu dem Objekttyp, den die Markierung repräsentiert: Fahrzeug oder Ziel, an die Anpassungsfunktion übergeben. Dann kann sich der Stil der Markierung an den aktuellen Status des Markierungselements anpassen, z. B. die Anzahl der verbleibenden 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 Versandverfolgungsbibliothek bietet die folgenden Anpassungsparameter in FleetEngineShipmentLocationProviderOptions:

Den Stil von Markierungen mit MarkerOptions ändern

Im folgenden Beispiel wird gezeigt, wie Sie den Stil einer Fahrzeugmarkierung mit einem MarkerOptions-Objekt konfigurieren. Folgen Sie diesem Muster, um den Stil einer beliebigen Markierung mithilfe einer der oben aufgeführten Anpassungen anzupassen.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Den 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 anzupassen.

JavaScript

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

TypeScript

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

Click Handling zu Markierungen

Das folgende Beispiel zeigt, wie Sie einer Fahrzeugmarkierung Click Handling hinzufügen. Folgen Sie diesem Muster, um mithilfe der oben aufgeführten Parameter zur Anpassung von Markierungen einer Markierung Klickbehandlung hinzuzufügen.

JavaScript

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

TypeScript

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

Polylinienanpassungen verwenden

Mit der Shipment Tracking Library kannst du auch die Darstellung der Route der Sendung 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. Diese Anpassungen werden dann in zwei Situationen angewendet: bevor die Objekte zur Karte hinzugefügt werden und wenn sich die für die Objekte verwendeten Daten geändert haben.

Ähnlich wie bei der Anpassung von Markierungen können Sie eine Gruppe von PolylineOptions angeben, die beim Erstellen oder Aktualisieren auf alle übereinstimmenden Polyline-Objekte angewendet wird.

Ebenso können Sie eine Anpassungsfunktion angeben. Anpassungsfunktionen ermöglichen eine individuelle Gestaltung der Objekte auf der Grundlage von Daten, die von Fleet Engine gesendet werden. Die Funktion kann den Stil jedes Objekts basierend auf dem aktuellen Status der Sendung ändern. Zum Beispiel kann das Polyline-Objekt in einer tieferen Schattierung eingefärbt werden oder es wird dicker, wenn das Fahrzeug langsamer fährt. Sie können sogar einen Join aus Quellen außerhalb von Fleet Engine durchführen und das Polyline-Objekt basierend auf diesen Informationen gestalten.

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

Stil von Polyline-Objekten mit PolylineOptions ändern

Das folgende Beispiel zeigt, wie Sie den Stil für ein Polyline-Objekt mit PolylineOptions konfigurieren. Folgen Sie diesem Muster, um den Stil eines Polyline-Objekts mit einer der zuvor aufgeführten Polylinienanpassungen anzupassen.

JavaScript

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

TypeScript

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

Den Stil von Polyline-Objekten mithilfe von Anpassungsfunktionen ändern

Das folgende Beispiel zeigt, wie Sie das Gestalten eines aktiven Polyline-Objekts konfigurieren. Folgen Sie diesem Muster, um den Stil eines beliebigen Polyline-Objekts mithilfe der oben aufgeführten Parameter zur Anpassung der Polylinie anzupassen.

JavaScript

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

TypeScript

// 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. Um ein Polyline-Objekt unsichtbar zu machen, legen Sie dessen Attribut visible fest:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

InfoWindow für eine Fahrzeug- oder Standortmarkierung anzeigen

Mit einem InfoWindow lassen sich zusätzliche Informationen zu einem Fahrzeug oder einer Standortmarkierung anzeigen.

Das folgende Beispiel zeigt, wie Sie ein InfoWindow erstellen und an eine Fahrzeugmarkierung anhängen:

JavaScript

// 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();

TypeScript

// 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 mit dem Teilen der Reise konfigurieren.

JavaScript

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

TypeScript

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

Sie können die JavaScript-Bibliothek für die Sendungsverfolgung verwenden, um eine vorhandene Karte mit Markierungen oder anderen Anpassungen zu ersetzen, ohne dass diese 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 für das 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 initMap()-Funktion. Die Ansicht enthält die Karte.
  4. Verschieben Sie Ihre Anpassungen in die Callback-Funktion für die 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.