JavaScript Consumer SDK einrichten

Mit dem JavaScript Consumer SDK kann Ihre Nutzer-App den Standort von Fahrzeugen und anderen Orten von Interesse, die in der Fleet Engine erfasst werden, auf einer webbasierten Karte anzeigen. So können Ihre Endnutzer den Fortschritt ihrer Sendungen sehen. In diesem Leitfaden wird davon ausgegangen, dass Sie die Fleet Engine mit dem zugehörigen Google Cloud-Projekt und den API-Schlüsseln eingerichtet haben. Weitere Informationen finden Sie unter Fleet Engine.

So richten Sie das Consumer SDK für JavaScript ein:

  1. Maps JavaScript API aktivieren
  2. Autorisierung einrichten

Maps JavaScript API aktivieren

Aktivieren Sie die Maps JavaScript API in dem Google Cloud Console-Projekt, das Sie für Ihre Fleet Engine-Instanz verwenden. Weitere Informationen finden Sie in der Dokumentation zur Maps JavaScript API unter APIs aktivieren.

Autorisierung einrichten

Die Fleet Engine erfordert die Verwendung von JSON Web Tokens (JWTs) für API-Methodenaufrufe aus weniger vertrauenswürdigen Umgebungen: Smartphones und Browsern.

Ein JWT stammt von Ihrem Server, wird signiert, verschlüsselt und für nachfolgende Serverinteraktionen an den Client übergeben, bis es abläuft oder nicht mehr gültig ist.

Wichtige Details

Ihre Nutzer-App sollte Ihre Endnutzer mit der Rolle delivery_consumer aus Ihrem Google Cloud-Projekt authentifizieren, damit nur nutzerspezifische Informationen zurückgegeben werden. Auf diese Weise werden alle anderen Informationen in den Antworten von Fleet Engine gefiltert und entfernt. Während einer Aufgabe, die die Nichtverfügbarkeit betrifft, werden beispielsweise keine Standortinformationen an einen Endnutzer weitergegeben. Weitere Informationen finden Sie unter Dienstkontorollen für geplante Aufgaben.

Wie funktioniert die Autorisierung?

Die Autorisierung mit Fleet Engine-Daten umfasst sowohl die serverseitige als auch die clientseitige Implementierung.

Serverseitige Autorisierung

Bevor Sie die Authentifizierung und Autorisierung in Ihrer webbasierten Anwendung einrichten, muss Ihr Backend-Server in der Lage sein, JSON Web Tokens für den Zugriff auf die Fleet Engine an Ihre webbasierte Anwendung auszugeben. Ihre webbasierte Anwendung sendet diese JWTs mit ihren Anfragen, damit die Fleet Engine die Anfragen als authentifiziert und autorisiert erkennt, um auf die Daten in der Anfrage zuzugreifen. Eine Anleitung zur serverseitigen JWT-Implementierung finden Sie unter JSON Web Tokens ausstellen im Abschnitt Grundlagen der Fleet Engine.

Beachten Sie insbesondere Folgendes für das JavaScript Consumer SDK zum Verfolgen von Sendungen:

Clientseitige Autorisierung

Wenn Sie das JavaScript Consumer SDK verwenden, wird über einen Autorisierungstoken-Fetcher ein Token vom Server angefordert. Dies geschieht, wenn eine der folgenden Bedingungen erfüllt ist:

  • Es ist kein gültiges Token vorhanden, z. B. wenn das SDK den Fetcher beim Seitenaufbau nicht aufgerufen hat oder wenn der Fetcher kein Token zurückgegeben hat.

  • Das Token ist abgelaufen.

  • Das Token läuft in weniger als einer Minute ab.

Andernfalls verwendet das JavaScript Consumer SDK das zuvor ausgestellte, gültige Token und ruft den Abrufer nicht auf.

Autorisierungstoken-Abrufprogramm erstellen

Erstellen Sie den Autorisierungstoken-Fetcher anhand der folgenden Richtlinien:

  • Der Fetcher muss eine Datenstruktur mit zwei Feldern zurückgeben, die wie folgt in ein Promise-Objekt eingeschlossen sind:

    • Ein String token.

    • Eine Zahl expiresInSeconds. Ein Token läuft nach dieser Zeitspanne nach dem Abrufen ab. Der Authentifizierungstoken-Fetcher muss die Ablaufzeit in Sekunden ab dem Zeitpunkt des Abrufs an die Bibliothek übergeben, wie im Beispiel gezeigt.

  • Der Fetcher sollte eine URL auf Ihrem Server aufrufen, um ein Token abzurufen. Diese URL (SERVER_TOKEN_URL) hängt von Ihrer Backend-Implementierung ab. Die folgende Beispiel-URL ist für das Beispiel-App-Backend auf GitHub:

    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID

Beispiel: Authentifizierungstoken-Abruf erstellen

Die folgenden Beispiele zeigen, wie Sie einen Autorisierungstoken-Fetcher erstellen:

JavaScript

async 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.ExpiresInSeconds,
  };
}

Nächste Schritte