Suivre les expéditions avec la bibliothèque JavaScript Shipment Tracking Library

La bibliothèque de suivi des expéditions JavaScript vous permet de visualiser l'emplacement des véhicules et des lieux d'intérêt suivis dans Fleet Engine. La bibliothèque contient un composant de carte JavaScript qui remplace directement une entité google.maps.Map standard et des composants de données pour se connecter à Fleet Engine. Grâce à cette bibliothèque, vous pouvez proposer une expérience de suivi des livraisons animée et personnalisable à partir de votre application Web.

Composants

La bibliothèque de suivi des expéditions JavaScript fournit des composants permettant de visualiser le véhicule et l'itinéraire au fur et à mesure de sa progression vers une destination, ainsi que des flux de données brutes pour l'heure d'arrivée prévue d'un chauffeur ou la distance restante à parcourir.

Vue plan du suivi des expéditions

Le composant de vue plan permet de visualiser l'emplacement des véhicules et les destinations. Si l'itinéraire d'un véhicule est connu, le composant de vue plan anime ce véhicule à mesure qu'il se déplace sur la voie prévue.

Fournisseur du lieu de livraison

Un fournisseur de services de localisation des livraisons insère des informations de localisation pour les objets suivis dans la carte de suivi des livraisons pour le suivi des livraisons au premier et au dernier kilomètre.

Vous pouvez utiliser le fournisseur de localisation d'expédition pour suivre les éléments suivants:

• Lieu de retrait ou de livraison d'un colis.
• L'emplacement et l'itinéraire du véhicule de livraison

Objets de localisation suivie

Le fournisseur de localisation suit l'emplacement d'objets tels que les véhicules et les destinations.

Emplacement de la destination

La destination est le lieu où se termine un trajet. Pour le suivi des expéditions, il s'agit de l'emplacement de la tâche planifiée.

Emplacement du véhicule

La position du véhicule correspond à sa position suivie. Il peut éventuellement inclure un itinéraire pour le véhicule.

Récupération des jetons d'authentification

Pour contrôler l'accès aux données de localisation stockées dans Fleet Engine, vous devez implémenter sur votre serveur un service de génération de jetons Web JSON (JWT) pour Fleet Engine. Ensuite, implémentez un outil de récupération de jetons d'authentification dans votre application Web, en utilisant la bibliothèque de partage de parcours JavaScript pour authentifier l'accès aux données de localisation.

Options de style

Les styles de repère et de polylignes déterminent l'apparence des objets de localisation suivi sur la carte. Vous pouvez utiliser des options de style personnalisé pour modifier le style par défaut afin qu'il corresponde à celui de votre application Web.

Contrôler la visibilité des lieux suivis

Cette section décrit les commandes de visibilité des objets suivis sur la carte. Ces règles s'appliquent à deux catégories d'objets:

• Repère de position
• Données de la tâche

Visibilité du repère de position

Tous les repères de position pour le point de départ et la destination sont toujours affichés sur la carte. Par exemple, un lieu de livraison est toujours affiché sur la carte, quel que soit l'état de la livraison.

Visibilité des données de tâche

Cette section décrit les règles de visibilité par défaut qui s'appliquent aux données des tâches, telles que la position du véhicule et l'itinéraire restant. Vous pouvez personnaliser de nombreuses tâches, mais pas toutes:

• Tâches non disponibles : vous ne pouvez pas personnaliser la visibilité de ces tâches.
• Tâches actives liées au véhicule : vous pouvez personnaliser ce type de tâches.
• Tâches inactives liées au véhicule : vous ne pouvez pas personnaliser la visibilité de ces tâches.

Tâches liées à l'indisponibilité

S'il y a au moins une tâche d'indisponibilité (par exemple, si le conducteur fait une pause ou si le véhicule est en train de faire le plein) sur l'itinéraire menant à la tâche suivie, le véhicule n'est pas visible. L'heure d'arrivée estimée et le temps d'achèvement estimé de la tâche sont toujours disponibles.

Tâches actives liées au véhicule

L'objet TaskTrackingInfo fournit un certain nombre d'éléments de données qui peuvent être rendus visibles dans la bibliothèque de suivi des expéditions. Par défaut, ces champs sont visibles lorsque la tâche est attribuée au véhicule et lorsque celui-ci se trouve à moins de cinq arrêts de la tâche. La visibilité prend fin lorsque la tâche est terminée ou annulée. Les champs sont les suivants:

• Polylignes d'itinéraire
• Heure d'arrivée estimée
• Durée estimée de la tâche
• Distance en voiture restante jusqu'à la tâche
• Nombre d'arrêts restant
• Emplacement du véhicule

Vous pouvez personnaliser la configuration de la visibilité pour chaque tâche en définissant le paramètre TaskTrackingViewConfig sur une tâche lors de sa création ou de sa mise à jour dans Fleet Engine. Cela crée des règles qui déterminent quand des éléments de données individuels sont disponibles. Ces règles peuvent être basées sur les critères suivants (appelés option de visibilité ci-dessous):

• Nombre d'arrêts restant
• Durée jusqu'à l'heure d'arrivée estimée
• Distance restante en voiture
• Toujours visible
• Jamais visible

Notez que chaque élément de données ne peut être associé qu'à une seule option de visibilité. Il n'est pas possible de combiner des critères à l'aide des opérateurs OR ou AND.

Voici un exemple de personnalisation. Les règles de cette personnalisation sont les suivantes:

• Affichez les polylignes de l'itinéraire si le véhicule compte moins de trois arrêts.
• Affichez l'heure d'arrivée prévue si la distance restante en voiture est inférieure à 5 000 mètres.
• Ne jamais afficher le nombre d'arrêts restants
• Chaque autre champ conserve la visibilité par défaut qui s'affiche lorsque le véhicule se trouve à moins de cinq arrêts de la tâche.

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

Vous pouvez également personnaliser la configuration de visibilité par défaut de votre projet en contactant l'équipe d'assistance.

Polylignes d'itinéraire et règles de visibilité de l'emplacement des véhicules:

Lorsque les polylignes d'itinéraire sont visibles, l'emplacement du véhicule doit également l'être, sinon celui-ci peut être indiqué à la fin des polylignes. Cela signifie que l'option de visibilité des polylignes d'itinéraire ne peut pas être moins restrictive.

Ces règles doivent être suivies pour fournir une combinaison polyligne d'itinéraire / visibilité de l'emplacement du véhicule:

• Lorsque les polylignes de l'itinéraire et l'emplacement des véhicules ont le même type d'option de visibilité:

  • Si l'option de visibilité correspond au nombre d'arrêts restants, à la durée avant l'heure d'arrivée prévue ou à la distance restante en voiture, les polylignes d'itinéraire doivent fournir une valeur inférieure ou égale à la valeur définie pour cette option de visibilité pour l'emplacement du véhicule. Voici un exemple:

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

  • Si les polylignes d'itinéraire ont une option de visibilité toujours visible, la position du véhicule doit également fournir une option de visibilité en permanence.
  • Si l'option de visibilité n'est jamais visible pour la position du véhicule, les polylignes d'itinéraire doivent également fournir une option de visibilité "Jamais visible".

• Lorsque les polylignes d'itinéraire et l'emplacement du véhicule présentent des types d'options de visibilité différents, la position du véhicule n'est visible que si les deux options de visibilité sont remplies.

  Voici un exemple:

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

  Dans cet exemple, l'emplacement du véhicule n'est visible que si le nombre d'arrêts restants est d'au moins 3 ET la distance restante en voiture est d'au moins 3 000 mètres.

Premiers pas avec la bibliothèque de partage de parcours JavaScript

Avant d'utiliser la bibliothèque de partage de parcours JavaScript, assurez-vous de bien utiliser Fleet Engine et d'obtenir une clé API.

Pour suivre une livraison, commencez par créer une revendication d'ID de suivi.

Créer une revendication d'ID de suivi

Pour suivre une livraison à l'aide du fournisseur de services de localisation des expéditions, créez un jeton Web JSON (JWT) avec une revendication d'ID de suivi.

Pour créer la charge utile JWT, ajoutez une revendication supplémentaire dans la section des autorisations avec la clé trackingid. Définissez sa valeur sur l'ID de suivi de la livraison.

L'exemple suivant montre comment créer un jeton pour le suivi par ID de suivi:

{
  "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",
   }
}

Créer un outil de récupération des jetons d'authentification

Vous pouvez créer un outil de récupération de jetons d'authentification pour récupérer un jeton émis avec les revendications appropriées sur vos serveurs à l'aide d'un certificat de compte de service pour votre projet. Il est important de ne générer des jetons que sur vos serveurs et de ne jamais les partager sur aucun client. Sinon, vous compromettrez la sécurité de votre système.

L'extracteur doit renvoyer une structure de données comportant deux champs, entourés d'une promesse:

• Une chaîne token.
• Un nombre expiresInSeconds. Un jeton expire dans ce délai après la récupération.

La bibliothèque de suivi des expéditions JavaScript demande un jeton via l'outil de récupération de jetons d'authentification lorsque l'une des conditions suivantes est remplie:

• Il ne possède pas de jeton valide, par exemple s'il n'a pas appelé l'extracteur lors d'un nouveau chargement de page ou s'il n'a pas renvoyé de jeton.
• Le jeton précédemment récupéré a expiré.
• Le jeton récupéré précédemment est dans la minute qui suit l'expiration.

Sinon, la bibliothèque utilise le jeton toujours valide émis précédemment et n'appelle pas l'extracteur.

L'exemple suivant montre comment créer un outil de récupération de jetons d'authentification:

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

Lors de l'implémentation du point de terminaison côté serveur pour la génération des jetons, tenez compte des points suivants:

• Le point de terminaison doit renvoyer un délai d'expiration pour le jeton. Dans l'exemple ci-dessus, il est exprimé sous la forme data.ExpiresInSeconds.
• L'outil de récupération des jetons d'authentification doit transmettre le délai d'expiration (en secondes, à partir du moment de la récupération) à la bibliothèque, comme illustré dans l'exemple.
• La valeur SERVER_TOKEN_URL dépend de l'implémentation de votre backend. Voici les URL de l'exemple de backend d'application :
  • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
  • https://SERVER_URL/token/fleet_reader

Charger une carte à partir d'un fichier HTML

L'exemple suivant montre comment charger la bibliothèque de suivi des livraisons JavaScript à partir d'une URL spécifiée. Le paramètre de rappel exécute la fonction initMap après le chargement de l'API. L'attribut defer permet au navigateur de continuer à afficher le reste de votre page pendant le chargement de l'API.

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

Suivre un envoi

Cette section explique comment utiliser la bibliothèque de suivi des expéditions JavaScript pour suivre un retrait ou une livraison. Veillez à charger la bibliothèque à partir de la fonction de rappel spécifiée dans le tag de script avant d'exécuter votre code.

Instancier un fournisseur de localisation d'expédition

La bibliothèque de suivi des expéditions JavaScript prédéfinit un fournisseur de zones géographiques pour l'API Fleet Engine Deliveries. Utilisez votre ID de projet et une référence à votre fabrique de jetons pour l'instancier.

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

Initialiser la vue plan

Après avoir chargé la bibliothèque de partage de parcours JavaScript, initialisez la vue de la carte et ajoutez-la à la page HTML. Votre page doit contenir un élément <div> qui contient la vue plan. Dans l'exemple suivant, l'élément <div> est nommé map_canvas.

Pour éviter les conditions de concurrence, définissez l'ID de suivi pour le fournisseur de position dans le rappel appelé après l'initialisation de la carte.

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

ID de suivi

L'ID de suivi fourni au fournisseur de services de localisation peut correspondre à plusieurs tâches (par exemple, une tâche de retrait et de livraison pour le même colis, ou plusieurs échecs de livraison). Une tâche est sélectionnée pour être affichée sur la carte de suivi des expéditions. La tâche à afficher est déterminée comme suit:

1. S'il n'y a qu'une seule tâche de retrait en cours, celle-ci s'affiche. Une erreur est générée s'il existe plusieurs tâches de retrait en cours.
2. S'il n'y a qu'une seule tâche de livraison ouverte, elle s'affiche. Une erreur est générée s'il existe plusieurs tâches de distribution en cours.
3. Si des tâches de livraison sont fermées :
   • S'il n'y a qu'une seule tâche de livraison fermée, elle s'affiche.
   • S'il existe plusieurs tâches de livraison fermées, celle dont le résultat est le plus récent s'affiche.
   • S'il existe plusieurs tâches de distribution fermées, dont aucune n'a de résultat, une erreur est générée.
4. Si des tâches de retrait en magasin sont fermées :
   • S'il n'y a qu'une seule tâche de retrait fermée, elle s'affiche.
   • S'il existe plusieurs tâches de retrait fermées, celle dont l'heure de résultat est la plus récente est affichée.
   • S'il existe plusieurs tâches de retrait fermées, dont aucune n'a de résultat, une erreur est générée.
5. Sinon, aucune tâche ne s'affiche.

Écouter les événements de modification

Vous pouvez récupérer des méta-informations sur une tâche à partir de l'objet d'informations de suivi des tâches à l'aide du fournisseur de localisation. Ces méta-informations incluent l'heure d'arrivée prévue, le nombre d'arrêts restants et la distance restante avant le retrait ou la livraison. Les modifications apportées aux métadonnées déclenchent un événement update. L'exemple suivant montre comment écouter ces événements de modification.

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

Gérer les erreurs

Les erreurs survenant de manière asynchrone lors de la demande d'informations sur la livraison déclenchent des événements error. L'exemple suivant montre comment écouter ces événements afin de gérer les erreurs.

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

Remarque:Veillez à encapsuler les appels de bibliothèque dans des blocs try...catch pour gérer les erreurs imprévues.

Arrêter le suivi

Pour empêcher le fournisseur de localisation de suivre la livraison, supprimez l'ID de suivi du fournisseur de localisation.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

Supprimer le fournisseur de position de la vue plan

L'exemple suivant montre comment supprimer un fournisseur de services de localisation de la vue plan.

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

Personnaliser l'apparence de la carte de base

Pour personnaliser l'apparence du composant de carte, appliquez un style à votre carte à l'aide d'outils cloud ou en définissant des options directement dans le code.

Utiliser les styles de cartes basés dans le cloud

Les styles de cartes basés dans le cloud vous permettent de créer et de modifier des styles de carte pour toutes les applications qui utilisent Google Maps à partir de la console Google Cloud, sans avoir à modifier votre code. Les styles de carte sont enregistrés en tant qu'ID de carte dans votre projet Cloud. Pour appliquer un style à votre carte de suivi des livraisons JavaScript, spécifiez un mapId lorsque vous créez le JourneySharingMapView. Le champ mapId ne peut pas être modifié ni ajouté après l'instanciation de l'JourneySharingMapView. L'exemple suivant montre comment activer un style de carte créé précédemment avec un ID de carte.

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

Utiliser les styles de carte basés sur du code

Une autre façon de personnaliser le style de la carte consiste à définir mapOptions lorsque vous créez le JourneySharingMapView.

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

Utiliser les personnalisations de repère

Avec la bibliothèque de suivi des expéditions JavaScript, vous pouvez personnaliser l'apparence des repères ajoutés à la carte. Pour ce faire, spécifiez les personnalisations des repères, que la bibliothèque de suivi des livraisons applique ensuite avant d'ajouter des repères à la carte et à chaque mise à jour de repère.

La personnalisation la plus simple consiste à spécifier un objet MarkerOptions qui sera appliqué à tous les repères du même type. Les modifications spécifiées dans l'objet sont appliquées après la création de chaque repère, remplaçant toutes les options par défaut.

Une option plus avancée consiste à spécifier une fonction de personnalisation. Les fonctions de personnalisation permettent de styliser les repères en fonction des données et d'ajouter de l'interactivité aux repères, comme la gestion des clics. Plus précisément, le suivi de l'expédition transmet à la fonction de personnalisation les données concernant le type d'objet représenté par le repère: véhicule ou destination. Cela permet ensuite de modifier le style du repère en fonction de l'état actuel de l'élément lui-même (par exemple, le nombre d'arrêts prévus restant jusqu'à la destination). Vous pouvez même joindre des données provenant de sources extérieures à Fleet Engine et styliser le repère en fonction de ces informations.

La bibliothèque Shipment Tracking fournit les paramètres de personnalisation suivants dans FleetEngineShipmentLocationProviderOptions:

• deliveryVehicleMarkerCustomization
• destinationMarkerCustomization

Modifier le style des repères avec MarkerOptions

L'exemple suivant montre comment configurer le style d'un repère de véhicule avec un objet MarkerOptions. Suivez ce schéma pour personnaliser le style d'un repère à l'aide de l'une des personnalisations de repère répertoriées ci-dessus.

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Modifier le style des repères à l'aide des fonctions de personnalisation

L'exemple suivant montre comment configurer le style d'un repère de véhicule. Suivez ce modèle pour personnaliser le style d'un repère à l'aide de l'un des paramètres de personnalisation de repère répertoriés ci-dessus.

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

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

Ajouter la gestion des clics aux repères

L'exemple suivant montre comment ajouter la gestion des clics à un repère de véhicule. Suivez ce modèle pour ajouter la gestion des clics à n'importe quel repère à l'aide de l'un des paramètres de personnalisation de repère répertoriés ci-dessus.

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

Utiliser les personnalisations de polylignes

Avec la bibliothèque de suivi des expéditions, vous pouvez également personnaliser l'apparence de l'itinéraire de livraison sur la carte. La bibliothèque crée un objet google.maps.Polyline pour chaque paire de coordonnées dans le chemin actif ou restant de la livraison. Vous pouvez appliquer un style aux objets Polyline en personnalisant les polylignes. La bibliothèque applique ensuite ces personnalisations dans deux situations: avant d'ajouter les objets à la carte et lorsque les données utilisées pour les objets ont changé.

Comme pour la personnalisation des repères, vous pouvez spécifier un ensemble de PolylineOptions à appliquer à tous les objets Polyline correspondants lorsqu'ils sont créés ou mis à jour.

De même, vous pouvez spécifier une fonction de personnalisation. Les fonctions de personnalisation permettent d'appliquer un style individuel aux objets en fonction des données envoyées par Fleet Engine. La fonction peut modifier le style de chaque objet en fonction de l'état actuel de la livraison (par exemple, en colorant l'objet Polyline d'une couleur plus profonde ou en l'épaississant lorsque le véhicule ralentit). Vous pouvez même effectuer une jointure depuis des sources extérieures à Fleet Engine et styliser l'objet Polyline en fonction de ces informations.

Vous pouvez spécifier les personnalisations à l'aide des paramètres fournis dans FleetEngineShipmentLocationProviderOptions. Vous pouvez personnaliser les différents états du trajet du véhicule (déjà emprunté, en cours de route ou pas encore). Les paramètres sont les suivants:

• takenPolylineCustomization, pour un chemin déjà parcouru
• activePolylineCustomization, pour un parcours actif
• remainingPolylineCustomization, pour un parcours qui n'a pas encore été emprunté.

Modifier le style des objets Polyline à l'aide de PolylineOptions

L'exemple suivant montre comment configurer le style d'un objet Polyline avec PolylineOptions. Suivez ce modèle pour personnaliser le style de n'importe quel objet Polyline à l'aide de l'une des personnalisations de polylignes répertoriées précédemment.

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

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

Modifier le style des objets Polyline à l'aide de fonctions de personnalisation

L'exemple suivant montre comment configurer le style d'un objet Polyline actif. Suivez ce modèle pour personnaliser le style de n'importe quel objet Polyline à l'aide de l'un des paramètres de personnalisation de polyligne énumérés précédemment.

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

Contrôler la visibilité des objets Polyline

Par défaut, tous les objets Polyline sont visibles. Pour rendre un objet Polyline invisible, définissez sa propriété visible:

remainingPolylineCustomization = {visible: false};

remainingPolylineCustomization = {visible: false};

Afficher une InfoWindow pour un véhicule ou un repère de position

Vous pouvez utiliser un InfoWindow pour afficher des informations supplémentaires sur un véhicule ou un repère de position.

L'exemple suivant montre comment créer un InfoWindow et l'associer à un repère de véhicule:

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

Désactiver l'ajustement automatique

Vous pouvez empêcher la carte d'ajuster automatiquement la fenêtre d'affichage au véhicule et à l'itinéraire anticipé en désactivant l'ajustement automatique. L'exemple suivant montre comment désactiver l'ajustement automatique lorsque vous configurez la vue de la carte pour le partage de trajets.

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

Remplacer une carte existante

Vous pouvez utiliser la bibliothèque JavaScript Shipment Tracking Library pour remplacer une carte existante qui inclut des repères ou d'autres personnalisations sans les perdre.

Par exemple, supposons que vous ayez une page Web avec une entité google.maps.Map standard sur laquelle un repère est affiché:

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

Pour ajouter la bibliothèque de partage de parcours JavaScript:

1. Ajoutez le code de la fabrique de jetons d'authentification.
2. Initialisez un fournisseur de localisation dans la fonction initMap().
3. Initialisez la vue plan dans la fonction initMap(). La vue contient la carte.
4. Déplacez votre personnalisation dans la fonction de rappel pour l'initialisation de la vue de la carte.
5. Ajoutez la bibliothèque de localisation au chargeur d'API.

L'exemple suivant montre les modifications à apporter:

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

Si vous avez un colis suivi avec l'ID spécifié près d'Uluru, il s'affichera désormais sur la carte.