Configura l'SDK consumer JavaScript

Con l'SDK JavaScript Consumer, la tua app consumer può mostrare la posizione dei veicoli e altre località di interesse monitorate su Fleet Engine su una mappa basata sul web. In questo modo, i tuoi utenti consumatori possono vedere l'avanzamento delle spedizioni. Questa guida presuppone che tu abbia configurato Fleet Engine con le chiavi API e il progetto Google Cloud associati. Per maggiori dettagli, consulta Fleet Engine.

Per configurare l'SDK Consumer JavaScript, segui questi passaggi:

  1. Abilita l'API Maps JavaScript.
  2. Configura le autorizzazioni.

Attivare l'API Maps JavaScript

Attiva l'API JavaScript di Maps nel progetto della console Google Cloud che utilizzi per l'istanza di Fleet Engine. Per maggiori dettagli, consulta Attivare le API nella documentazione dell'API Maps JavaScript.

Configura l'autorizzazione

Per le chiamate ai metodi dell'API da ambienti con un livello di attendibilità basso, Fleet Engine richiede l'utilizzo di token web JSON (JWT) firmati da un account di servizio appropriato. Gli ambienti con un livello di attendibilità basso includono smartphone e browser. Un JWT viene generato sul tuo server, che è un ambiente completamente attendibile. Il JWT viene firmato, criptato e trasmesso al client per le successive interazioni con il server finché non scade o non è più valido.

Il tuo backend deve autenticarsi e autorizzare Fleet Engine utilizzando i meccanismi standard delle credenziali predefinite dell'applicazione. Assicurati di utilizzare JWT firmati da un account di servizio appropriato. Per un elenco di ruoli per l'account di servizio, vedi i ruoli dell'account di servizio di Fleet Engine nell'articolo Nozioni di base di Fleet Engine.

L'app consumer deve autenticare gli utenti finali con il ruolo delivery_consumer del progetto Google Cloud per restituire solo informazioni specifiche del consumer. In questo modo, Fleet Engine filtra e oscura tutte le altre informazioni nelle risposte. Ad esempio, durante un'attività di mancata disponibilità, non vengono condivise informazioni sulla posizione con un utente finale. Consulta Ruoli dell'account di servizio per le attività pianificate.

Al contrario, il backend deve autenticarsi e autorizzarsi in Fleet Engine utilizzando i meccanismi standard delle credenziali predefinite dell'applicazione.

Come funziona l'autorizzazione?

L'autorizzazione con i dati di Fleet Engine prevede l'implementazione sia lato server sia lato client.

Autorizzazione lato server

Prima di configurare l'autenticazione e l'autorizzazione nella tua applicazione web, il server di backend deve essere in grado di emettere token web JSON per l'accesso a Fleet Engine. L'applicazione web invia questi JWT con le sue richieste in modo che Fleet Engine le riconosca come autenticate e autorizzate ad accedere ai dati al loro interno. Per istruzioni sull'implementazione di JWT lato server, vedi Pubblicare token web JSON JSON in Fleet Engine Essentials.

In particolare, tieni presente quanto segue per l'SDK JavaScript consumer per il monitoraggio delle spedizioni:

Autorizzazione lato client

Quando utilizzi l'SDK Consumer JavaScript, questo richiede un token dal server utilizzando un recupero del token di autorizzazione. Ciò avviene quando una delle seguenti condizioni è vera:

  • Non esistono token validi, ad esempio se l'SDK non ha chiamato il fetcher in un nuovo caricamento pagina o quando il fetcher non ha restituito un token.

  • Il token è scaduto.

  • Il token sta per scadere entro un minuto.

In caso contrario, l'SDK consumer JavaScript utilizza il token valido emesso in precedenza e non chiama il recuperatore.

Crea un recuperatore di token di autorizzazione

Crea il tuo recuperatore del token di autorizzazione seguendo queste linee guida:

  • Il fetcher deve restituire una struttura di dati con due campi, aggregati in un Promise come segue:

    • Una stringa token.

    • Un numero expiresInSeconds. Un token scade in questo lasso di tempo dopo il recupero. Il fetcher del token di autenticazione deve passare la scadenza in secondi, dal momento del recupero alla libreria, come mostrato nell'esempio.

  • Il gatherer deve chiamare un URL sul tuo server per recuperare un token. Questo URL, ovvero SERVER_TOKEN_URL, dipende dall'implementazione del backend. Il seguente URL di esempio è per il backend dell'app di esempio su GitHub:

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

Esempio: creare un fetcher di token di autenticazione

Gli esempi riportati di seguito mostrano come creare un recuperatore di token di autorizzazione:

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

Passaggi successivi