Configurer le SDK JavaScript Consumer

Grâce au SDK Consumer JavaScript, votre application grand public peut afficher sur une carte Web la position des véhicules et d'autres lieux d'intérêt suivis dans Fleet Engine. Cela permet à vos clients de suivre l'avancement de leurs livraisons. Ce guide suppose que vous avez configuré Fleet Engine avec le projet Google Cloud et les clés API associés. Pour en savoir plus, consultez Fleet Engine.

Pour configurer le SDK Consumer JavaScript, procédez comme suit :

  1. Activez l'API Maps JavaScript.
  2. Configurer les autorisations.

Activer l'API Maps JavaScript

Activez l'API Maps JavaScript dans le projet de la console Google Cloud que vous utilisez pour votre instance Fleet Engine. Pour en savoir plus, consultez Activer des API dans la documentation de l'API Maps JavaScript.

Configurer les autorisations

Fleet Engine nécessite l'utilisation de jetons Web JSON (JWT) pour les appels de méthode d'API depuis des environnements peu fiables : smartphones et navigateurs.

Un jeton JWT provient de votre serveur. Il est signé, chiffré et transmis au client pour les interactions ultérieures avec le serveur jusqu'à ce qu'il expire ou ne soit plus valide.

Informations essentielles

Votre application grand public doit authentifier vos utilisateurs finaux avec le rôle delivery_consumer de votre projet Google Cloud pour ne renvoyer que des informations spécifiques au consommateur. De cette façon, Fleet Engine filtre et masque toutes les autres informations dans les réponses. Par exemple, lors d'une tâche d'indisponibilité, aucune information de localisation n'est partagée avec un utilisateur final. Consultez Rôles de compte de service pour les tâches planifiées.

Comment fonctionne l'autorisation ?

L'autorisation avec les données Fleet Engine implique une mise en œuvre côté serveur et côté client.

Autorisation côté serveur

Avant de configurer l'authentification et l'autorisation dans votre application Web, votre serveur backend doit pouvoir émettre des jetons Web JSON pour votre application Web afin d'accéder à Fleet Engine. Votre application Web envoie ces jetons JWT avec ses requêtes afin que Fleet Engine les reconnaisse comme authentifiées et autorisées à accéder aux données de la requête. Pour savoir comment implémenter des jetons Web JSON côté serveur, consultez Émettre des jetons Web JSON sous Principes de base de Fleet Engine.

En particulier, tenez compte des points suivants concernant le SDK Consumer JavaScript pour le suivi des envois :

Autorisation côté client

Lorsque vous utilisez le SDK Consumer pour JavaScript, il demande un jeton au serveur à l'aide d'un récupérateur de jetons d'autorisation. Cela se produit lorsque l'une des conditions suivantes est remplie :

  • Aucun jeton valide n'existe, par exemple lorsque le SDK n'a pas appelé l'outil de récupération lors d'un nouveau chargement de page ou lorsque l'outil de récupération n'a pas renvoyé de jeton.

  • Le jeton est arrivé à expiration.

  • Le jeton expire dans une minute.

Sinon, le SDK Consumer JavaScript utilise le jeton valide précédemment émis et n'appelle pas l'outil de récupération.

Créer un récupérateur de jetons d'autorisation

Créez votre outil de récupération de jetons d'autorisation en suivant ces consignes :

  • L'outil de récupération doit renvoyer une structure de données avec deux champs, encapsulée dans un Promise comme suit :

    • Une chaîne token.

    • Un nombre expiresInSeconds. Un jeton expire après ce délai après la récupération. L'outil de récupération de jetons d'authentification doit transmettre le délai d'expiration en secondes, de la récupération à la bibliothèque, comme illustré dans l'exemple.

  • L'outil de récupération doit appeler une URL sur votre serveur pour récupérer un jeton. Cette URL (SERVER_TOKEN_URL) dépend de l'implémentation de votre backend. L'exemple d'URL suivant correspond au backend de l'application exemple sur GitHub :

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

Exemple : Créer un récupérateur de jeton d'authentification

Les exemples suivants montrent comment créer un récupérateur de jetons d'autorisation :

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

Étape suivante