Tracciare le spedizioni con la libreria di monitoraggio della spedizione JavaScript

La libreria JavaScript Shipment Tracking Library consente di visualizzare la posizione dei veicoli e le località di interesse monitorati in Fleet Engine. La libreria contiene un componente di mappa JavaScript che sostituisce direttamente un'entità google.maps.Map e componenti di dati standard da connettere a Fleet Engine. Con la libreria JavaScript Shipment Tracking Library, puoi fornire un'esperienza di monitoraggio della spedizione animata e personalizzabile dalla tua applicazione web.

Componenti

La libreria JavaScript per il monitoraggio delle spedizioni fornisce componenti per la visualizzazione del veicolo e del percorso man mano che prosegue verso una destinazione, nonché feed di dati non elaborati per l'orario di arrivo stimato di un conducente o la distanza restante da percorrere.

Visualizzazione mappa per il monitoraggio delle spedizioni

Il componente visualizzazione mappa mostra la posizione dei veicoli e delle destinazioni. Se il percorso di un veicolo è noto, il componente Visualizzazione mappa anima il veicolo mentre si sposta lungo il percorso previsto.

Fornitore località di spedizione

Un fornitore della località di spedizione inserisce le informazioni sulla posizione degli oggetti monitorati nella mappa di monitoraggio della spedizione per monitorare la spedizione del primo e dell'ultimo miglio.

Puoi utilizzare il fornitore della località di spedizione per tracciare:

  • Il luogo di ritiro o consegna di una spedizione.
  • La posizione e il percorso del veicolo per la consegna.

Oggetti posizione monitorati

Il fornitore della posizione monitora la posizione di oggetti come veicoli e destinazioni.

Località di destinazione

La località di destinazione è il luogo in cui finisce un viaggio. Per il monitoraggio della spedizione, è il luogo dell'attività pianificata.

Posizione del veicolo

La posizione del veicolo è quella tracciata di un veicolo. Inoltre, può includere un percorso per il veicolo.

Recupero token di autenticazione

Per controllare l'accesso ai dati sulle località archiviati in Fleet Engine, devi implementare un servizio di minting di token web JSON (JWT) per Fleet Engine sul tuo server. Quindi implementa un fetcher di token di autenticazione come parte della tua applicazione web, utilizzando la libreria di condivisione del percorso JavaScript per autenticare l'accesso ai dati sulla posizione.

Opzioni per lo stile

Gli stili di indicatori e polilinee determinano l'aspetto e il design degli oggetti posizione tracciati sulla mappa. Puoi utilizzare le opzioni di stile personalizzate per modificare lo stile predefinito in modo che corrisponda a quello della tua applicazione web.

Controlla la visibilità delle località monitorate

Questa sezione descrive i controlli di visibilità per gli oggetti monitorati sulla mappa. Queste regole si applicano a due categorie di oggetti:

  • Indicatore di posizione
  • Dati attività

Visibilità indicatore di posizione

Tutti gli indicatori di posizione per l'origine e la destinazione sono sempre visualizzati sulla mappa. Ad esempio, la località di consegna di una spedizione viene sempre mostrata sulla mappa, indipendentemente dallo stato della consegna.

Visibilità dei dati delle attività

Questa sezione descrive le regole di visibilità predefinite che si applicano ai dati delle attività, come la posizione del veicolo e il percorso rimanente. Puoi personalizzare molte attività, ma non tutte:

  • Attività non disponibili: non puoi personalizzare la visibilità per queste attività.
  • Attività con veicoli attivi: puoi personalizzare questo tipo di attività.
  • Attività inattive con veicolo: non puoi personalizzare la visibilità per queste attività.

Attività non disponibili

Se almeno un'attività non è disponibile (ad esempio, se il conducente fa una pausa o è in corso il rifornimento del veicolo) lungo il percorso che conduce all'attività monitorata, il veicolo non è visibile. L'ora di arrivo prevista e l'ora di completamento dell'attività stimata sono ancora disponibili.

Attività con veicoli attivi

L'oggetto TaskTrackingInfo fornisce una serie di elementi di dati che possono essere resi visibili all'interno della libreria di monitoraggio delle spedizioni. Per impostazione predefinita, questi campi sono visibili quando l'attività viene assegnata al veicolo e quando quest'ultimo si trova entro 5 fermate dall'attività. La visibilità termina quando l'attività viene completata o annullata. I campi sono i seguenti:

  • Polilinee del percorso
  • Orario di arrivo previsto
  • Tempo stimato per il completamento dell'attività
  • Distanza in auto rimanente dall'attività
  • Numero di fermate rimanenti
  • Posizione del veicolo

Puoi personalizzare la configurazione della visibilità in base all'attività impostando TaskTrackingViewConfig su un'attività durante la creazione o l'aggiornamento dell'attività in Fleet Engine. Ciò crea regole relative alla disponibilità di singoli elementi di dati, che possono essere basate sui seguenti criteri (indicati come opzione di visibilità di seguito):

  • Numero di fermate rimanenti
  • Durata fino all'ora di arrivo prevista
  • Distanza in auto rimanente
  • Sempre visibile
  • Mai visibile

Tieni presente che ogni elemento di dati può essere associato a una sola opzione di visibilità. Non è possibile combinare i criteri utilizzando OR o AND.

Di seguito è riportato un esempio di personalizzazione. Le regole della personalizzazione sono:

  • Mostra le polilinee del percorso se il veicolo si trova a meno di 3 fermate.
  • Mostra l'orario di arrivo stimato se la distanza percorsa rimanente è inferiore a 5000 metri.
  • Non mostrare mai il numero di fermate rimanenti.
  • Ogni altro campo mantiene la visibilità predefinita mostrata quando il veicolo si trova entro 5 fermate dall'attività.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Puoi anche personalizzare la configurazione predefinita della visibilità per il tuo progetto contattando il team di assistenza.

Polilinee del percorso e regole di visibilità della posizione dei veicoli:

Quando sono visibili le polilinee del percorso, deve essere visibile anche la posizione del veicolo; in caso contrario, la posizione del veicolo può essere indicata dalle estremità delle polilinee. Ciò significa che le polilinee delle route non possono avere un'opzione di visibilità meno restrittiva.

Per fornire una combinazione valida di polilinee del percorso / visibilità della posizione del veicolo, è necessario seguire queste regole:

  • Quando le polilinee del percorso e la posizione del veicolo hanno lo stesso tipo di opzione di visibilità:

    • Se l'opzione di visibilità rimane il numero di fermate, la durata fino all'orario di arrivo stimato o la distanza di guida rimanente, le polilinee del percorso devono fornire un valore inferiore o uguale al valore impostato per questa opzione di visibilità per la posizione del veicolo. Ecco un esempio:
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • Se le polilinee del percorso hanno un'opzione di visibilità sempre visibile, anche la posizione del veicolo deve fornire un'opzione di visibilità sempre visibile.
    • Se la posizione del veicolo non ha un'opzione di visibilità mai visibile, anche le polilinee del percorso devono fornire un'opzione di visibilità mai visibile.
  • Quando le polilinee del percorso e la posizione del veicolo hanno tipi di opzioni di visibilità diversi, la posizione del veicolo è visibile solo quando sono soddisfatte entrambe le opzioni di visibilità.

    Ecco un esempio:

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

    In questo esempio, la posizione del veicolo è visibile solo se il numero di fermate rimanenti è di almeno 3 E la distanza percorsa rimanente è di almeno 3000 metri.

Iniziare a utilizzare la libreria di condivisione dei percorsi JavaScript

Prima di utilizzare la libreria di condivisione dei percorsi JavaScript, assicurati di conoscere Fleet Engine e come ottenere una chiave API.

Per monitorare una consegna, crea prima una rivendicazione dell'ID monitoraggio.

Crea una rivendicazione dell'ID monitoraggio

Per tracciare una spedizione utilizzando il fornitore della località di spedizione, crea un token JWT (JSON Web Token) con una rivendicazione dell'ID monitoraggio.

Per creare il payload JWT, aggiungi un'altra attestazione nella sezione dell'autorizzazione con la chiave trackingid. Imposta il suo valore sull'ID monitoraggio della spedizione.

L'esempio seguente mostra come creare un token per il monitoraggio in base all'ID monitoraggio:

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

Creare un fetcher di token di autenticazione

Puoi creare un fetcher di token di autenticazione per recuperare un token creato con le attestazioni appropriate sui tuoi server utilizzando un certificato dell'account di servizio per il tuo progetto. È importante generare solo token sui server e non condividere mai i certificati su alcun client. In caso contrario, si compromette la sicurezza del sistema.

Il fetcher deve restituire una struttura di dati con due campi, aggregati in una promessa:

  • Una stringa token.
  • Un numero expiresInSeconds. Un token scade dopo questo intervallo di tempo dopo il recupero.

La libreria JavaScript Shipment Tracking richiede un token tramite il fetcher di token di autenticazione quando si verifica una delle seguenti condizioni:

  • Non ha un token valido, ad esempio se non ha chiamato il fetcher su un nuovo caricamento della pagina o quando il fetcher non ha restituito un token.
  • Il token recuperato in precedenza è scaduto.
  • Il token recuperato in precedenza è trascorso entro un minuto dalla scadenza.

In caso contrario, la libreria utilizza il token ancora valido emesso in precedenza e non chiama il fetcher.

L'esempio seguente mostra come creare un fetcher di token di autenticazione:

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

Quando implementi l'endpoint lato server per il mining dei token, tieni presente quanto segue:

  • L'endpoint deve restituire una data di scadenza per il token; nell'esempio precedente, è specificato come data.ExpiresInSeconds.
  • Il fetcher del token di autenticazione deve passare la data di scadenza (in secondi, dal momento del recupero) alla libreria, come mostrato nell'esempio.
  • SERVER_TOKEN_URL dipende dall'implementazione del backend; questi sono gli URL per il backend dell'app di esempio:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

Carica una mappa da HTML

L'esempio seguente mostra come caricare la libreria JavaScript Shipment Tracking da un URL specificato. Il parametro callback esegue la funzione initMap dopo il caricamento dell'API. L'attributo defer consente al browser di continuare a eseguire il rendering del resto della pagina durante il caricamento dell'API.

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

Seguire una spedizione

Questa sezione mostra come utilizzare la libreria JavaScript Shipment Tracking Library per seguire il ritiro o la consegna di una spedizione. Assicurati di caricare la libreria dalla funzione di callback specificata nel tag script prima di eseguire il codice.

Crea l'istanza di un fornitore della località di spedizione

La libreria JavaScript Shipment Tracking Library predefinisce un fornitore di località per l'API Fleet Engine Deliveries. Utilizza il tuo ID progetto e un riferimento alla fabbrica di token per creare un'istanza.

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

Inizializzare la visualizzazione mappa

Dopo aver caricato la libreria di condivisione del percorso JavaScript, inizializza la visualizzazione mappa e aggiungila alla pagina HTML. La pagina deve contenere un elemento <div> contenente la visualizzazione mappa. Nell'esempio seguente, l'elemento <div> è denominato map_canvas.

Per evitare le condizioni di gara, imposta l'ID monitoraggio per il provider di posizione nel callback che viene richiamato dopo l'inizializzazione della mappa.

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

ID monitoraggio

L'ID monitoraggio fornito al fornitore della posizione può corrispondere a diverse attività, ad esempio un'attività di ritiro e consegna per lo stesso pacco oppure diversi tentativi di consegna non riusciti. Viene selezionata un'attività da mostrare sulla mappa di monitoraggio delle spedizioni. L'attività da mostrare è determinata come segue:

  1. Se è presente esattamente un'attività di ritiro aperta, viene visualizzata. Se sono presenti più attività di ritiro aperte, viene generato un errore.
  2. Viene visualizzata se è presente esattamente un'attività di consegna aperta. Se sono presenti più attività di consegna aperte, viene generato un errore.
  3. Se sono presenti attività di consegna chiuse:
    • Viene visualizzata se è presente esattamente un'attività di consegna chiusa.
    • Se ci sono più attività di pubblicazione chiuse, viene mostrata quella con la data di risultato più recente.
    • Se sono presenti più attività di consegna chiuse, nessuna delle quali ha una data/ora esito, viene generato un errore.
  4. Se ci sono attività di ritiro chiuse:
    • Viene visualizzata se c'è esattamente un'attività di ritiro chiusa.
    • Se ci sono più attività di ritiro chiuse, viene visualizzata quella con l'orario di risultato più recente.
    • Se sono presenti più attività di ritiro chiuse, nessuna delle quali ha un'ora dei risultati, viene generato un errore.
  5. In caso contrario, non viene visualizzata alcuna attività.

Ascoltare gli eventi di modifica

Puoi recuperare le meta informazioni su un'attività dall'oggetto informazioni sul monitoraggio attività utilizzando il provider di posizione. Le meta informazioni includono l'orario di arrivo stimato, il numero di tappe rimanenti e la distanza rimanente prima del ritiro o della consegna. Le modifiche alle meta-informazioni attivano un evento update. L'esempio seguente mostra come ascoltare questi eventi di modifica.

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

Gestire gli errori

Gli errori derivanti in modo asincrono dalla richiesta di informazioni di spedizione attivano eventi error. L'esempio seguente mostra come rimanere in ascolto di questi eventi per gestire gli errori.

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

Nota: assicurati di aggregare le chiamate della libreria in blocchi try...catch per gestire gli errori imprevisti.

Interrompi monitoraggio

Per impedire al fornitore della posizione di monitorare la spedizione, rimuovi l'ID monitoraggio dal fornitore della posizione.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Rimuovi il fornitore della posizione dalla visualizzazione mappa

L'esempio seguente mostra come rimuovere un fornitore di posizione dalla visualizzazione mappa.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Personalizza l'aspetto della mappa base

Per personalizzare l'aspetto del componente per le mappe, applica lo stile della mappa utilizzando strumenti basati su cloud o impostando le opzioni direttamente nel codice.

Utilizzare la personalizzazione delle mappe basata su cloud

La personalizzazione delle mappe basata su cloud consente di creare e modificare gli stili di mappa per qualsiasi app che utilizzano Google Maps dalla console Google Cloud, senza richiedere alcuna modifica al codice. Gli stili di mappa vengono salvati come ID mappa nel tuo progetto Cloud. Per applicare uno stile alla mappa di monitoraggio delle spedizioni JavaScript, specifica un mapId quando crei JourneySharingMapView. Il campo mapId non può essere modificato o aggiunto dopo aver creato un'istanza di JourneySharingMapView. Il seguente esempio mostra come attivare uno stile di mappa creato in precedenza con un ID mappa.

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

Utilizzare gli stili di mappa basati su codice

Un altro modo per personalizzare gli stili della mappa è impostare mapOptions quando crei JourneySharingMapView.

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

Utilizzare le personalizzazioni degli indicatori

Con la libreria JavaScript Shipment Tracking Library, puoi personalizzare l'aspetto e il design degli indicatori aggiunti alla mappa. A tale scopo, specifica le personalizzazioni degli indicatori, che verranno poi applicate dalla Shipment Tracking Library prima di aggiungere gli indicatori alla mappa e a ogni aggiornamento degli indicatori.

La personalizzazione più semplice consiste nello specificare un oggetto MarkerOptions che verrà applicato a tutti gli indicatori dello stesso tipo. Le modifiche specificate nell'oggetto vengono applicate dopo la creazione di ciascun indicatore, sovrascrivendo eventuali opzioni predefinite.

Un'opzione più avanzata consiste nello specificare una funzione di personalizzazione. Le funzioni di personalizzazione consentono di applicare uno stile agli indicatori in base ai dati e di aggiungere interattività agli indicatori, come la gestione dei clic. In particolare, il monitoraggio delle spedizioni trasmette alla funzione di personalizzazione i dati relativi al tipo di oggetto rappresentato dall'indicatore: veicolo o destinazione. Ciò consente di modificare lo stile degli indicatori in base allo stato corrente dell'elemento indicatore stesso; ad esempio, il numero di fermate pianificate rimanenti fino alla destinazione. Puoi anche utilizzare dati provenienti da origini esterne a Fleet Engine e applicare uno stile all'indicatore in base a queste informazioni.

La libreria Monitoraggio delle spedizioni fornisce i seguenti parametri di personalizzazione in FleetEngineShipmentLocationProviderOptions:

Modifica lo stile degli indicatori utilizzando MarkerOptions

L'esempio seguente mostra come configurare lo stile di un indicatore di veicolo con un oggetto MarkerOptions. Segui questo schema per personalizzare lo stile degli indicatori.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Modificare lo stile degli indicatori utilizzando le funzioni di personalizzazione

L'esempio seguente mostra come configurare lo stile di un indicatore di veicolo. Segui questo pattern per personalizzare lo stile di qualsiasi indicatore utilizzando uno dei parametri di personalizzazione degli indicatori elencati sopra.

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

Aggiungere la gestione dei clic agli indicatori

L'esempio seguente mostra come aggiungere la gestione dei clic a un indicatore di veicolo. Segui questo pattern per aggiungere la gestione dei clic a qualsiasi indicatore utilizzando uno dei parametri di personalizzazione degli indicatori elencati sopra.

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

Usare le personalizzazioni delle polilinee

Con la libreria per il tracciamento delle spedizioni puoi anche personalizzare l'aspetto del percorso della spedizione sulla mappa. La libreria crea un oggetto google.maps.Polyline per ogni coppia di coordinate nel percorso attivo o rimanente della spedizione. Puoi definire gli oggetti Polyline specificando le personalizzazioni della polilinea. La libreria applica quindi queste personalizzazioni in due situazioni: prima di aggiungere gli oggetti alla mappa e quando i dati utilizzati per gli oggetti sono cambiati.

Come per la personalizzazione degli indicatori, puoi specificare un insieme di PolylineOptions da applicare a tutti gli oggetti Polyline corrispondenti quando vengono creati o aggiornati.

Analogamente, puoi specificare una funzione di personalizzazione. Le funzioni di personalizzazione consentono di applicare uno stile individuale agli oggetti in base ai dati inviati da Fleet Engine. La funzione può modificare lo stile di ciascun oggetto in base allo stato corrente della spedizione, ad esempio colorando l'oggetto Polyline con un colore più intenso o rendendolo più spesso quando il veicolo si muove più lentamente. Puoi anche eseguire join da origini esterne a Fleet Engine e definire lo stile dell'oggetto Polyline in base a queste informazioni.

Puoi specificare le personalizzazioni utilizzando i parametri forniti in FleetEngineShipmentLocationProviderOptions. Puoi impostare le personalizzazioni per i diversi stati del percorso nel percorso del veicolo: già percorso, attivamente in viaggio o non ancora percorso. I parametri sono i seguenti:

Modifica lo stile di Polyline oggetti utilizzando PolylineOptions

L'esempio seguente mostra come configurare lo stile per un oggetto Polyline con PolylineOptions. Segui questo pattern per personalizzare lo stile di qualsiasi oggetto Polyline utilizzando una qualsiasi delle personalizzazioni della polilinea elencate in precedenza.

JavaScript

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

TypeScript

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

Modifica lo stile di Polyline oggetti utilizzando le funzioni di personalizzazione

L'esempio seguente mostra come configurare lo stile di un oggetto Polyline attivo. Segui questo pattern per personalizzare lo stile di qualsiasi oggetto Polyline utilizzando uno qualsiasi dei parametri di personalizzazione della polilinea elencati in precedenza.

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

Controlla la visibilità di Polyline oggetti

Per impostazione predefinita, tutti gli oggetti Polyline sono visibili. Per rendere invisibile un oggetto Polyline, imposta la relativa proprietà visible:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Mostra un InfoWindow per un veicolo o un indicatore di posizione

Puoi utilizzare un elemento InfoWindow per visualizzare ulteriori informazioni su un veicolo o un indicatore di posizione.

L'esempio seguente mostra come creare un elemento InfoWindow e attaccarlo a un indicatore di veicolo:

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

Disattiva adattamento automatico

Puoi impedire alla mappa di adattare automaticamente l'area visibile al veicolo e al percorso previsto disattivando l'adattamento automatico. L'esempio seguente mostra come disabilitare l'adattamento automatico quando configuri la visualizzazione mappa del percorso di condivisione.

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

Sostituire una mappa esistente

Puoi utilizzare la libreria JavaScript Shipment Tracking Library per sostituire una mappa esistente che include indicatori o altre personalizzazioni, senza perdere queste personalizzazioni.

Ad esempio, supponi di avere una pagina web con un'entità google.maps.Map standard sulla quale è visualizzato un indicatore:

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

Per aggiungere la libreria di condivisione del percorso JavaScript:

  1. Aggiungi il codice per il valore di fabbrica del token di autenticazione.
  2. Inizializza un fornitore di servizi di localizzazione nella funzione initMap().
  3. Inizializza la visualizzazione mappa nella funzione initMap(). La visualizzazione contiene la mappa.
  4. Sposta la personalizzazione nella funzione di callback per l'inizializzazione della visualizzazione mappa.
  5. Aggiungi la libreria delle località al caricatore dell'API.

L'esempio seguente mostra le modifiche da apportare:

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

Se hai un pacco monitorato con l'ID specificato nei pressi di Uluru, questo verrà visualizzato sulla mappa.