Tracciare le spedizioni con la libreria di monitoraggio della spedizione JavaScript

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

Componenti

La JavaScript Shipment Tracking Library fornisce componenti per la visualizzazione del veicolo e del percorso man mano che raggiunge una destinazione, nonché feed di dati non elaborati per l'orario di arrivo stimato di un conducente o la distanza rimanente da raggiungere.

Visualizzazione mappa del tracciamento della spedizione

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

Fornitore del luogo di spedizione

Un fornitore della località di spedizione inserisce le informazioni sulla posizione degli oggetti tracciati nella mappa di monitoraggio della spedizione per il monitoraggio della 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 di posizione monitora la posizione di oggetti come veicoli e destinazioni.

Località di destinazione

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

Posizione del veicolo

La posizione del veicolo è la posizione monitorata di un veicolo. Può includere facoltativamente un percorso per il veicolo.

Recuperatore token di autenticazione

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

Opzioni di stile

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

Controlla la visibilità delle località monitorate

In questa sezione vengono descritti i controlli di visibilità per gli oggetti tracciati sulla mappa. Queste regole si applicano a due categorie di oggetti:

  • Indicatore di posizione
  • Dati attività

Visibilità degli indicatori di posizione

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

Visibilità dei dati dell'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à attive del veicolo: puoi personalizzare questo tipo di attività.
  • Attività del veicolo inattive: non puoi personalizzare la visibilità per queste attività.

Attività di indisponibilità

Se è presente almeno un'attività di indisponibilità (ad esempio, se il conducente fa una pausa o il veicolo viene fatto rifornimento) lungo il percorso verso l'attività monitorata, il veicolo non è visibile. L'ora di arrivo prevista e l'ora di completamento stimata delle attività sono ancora disponibili.

Attività attive del veicolo

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

  • Polilinee di percorso
  • Tempo stimato all'arrivo
  • Tempo stimato per il completamento dell'attività
  • Distanza di guida rimanente dall'attività
  • Numero di interruzioni rimanenti
  • Posizione del veicolo

Puoi personalizzare la configurazione della visibilità in base all'attività impostando TaskTrackingViewConfig su un'attività quando crei o aggiorni l'attività in Fleet Engine. Questo crea regole per la disponibilità di singoli elementi di dati, che possono essere basate sui seguenti criteri (indicati come opzione di visibilità di seguito):

  • Numero di interruzioni rimanenti
  • Durata fino all'ora di arrivo prevista
  • Distanza di guida rimanente
  • Sempre visibile
  • Mai visibile

Tieni presente che ogni elemento dei dati può essere associato a una sola opzione di visibilità. Non è possibile combinare i criteri usando OR oppure 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 rimanente in auto è inferiore a 5000 metri.
  • Non mostrare mai il numero di fermate rimanenti.
  • Ogni altro campo mantiene la visibilità predefinita, ovvero quando il veicolo si trova a 5 fermate dall'attività.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

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

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

Quando le polilinee del percorso sono visibili, deve essere visibile anche la posizione del veicolo, altrimenti la posizione del veicolo può essere indicata dalla fine delle polilinee. Ciò significa che le polilinee di route non possono avere un'opzione di visibilità meno restrittiva.

È necessario seguire queste regole per fornire una combinazione valida di polilinee di percorso e visibilità della posizione dei veicoli:

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

    • Se l'opzione di visibilità è il numero di fermate, la durata fino all'orario di arrivo stimato o la distanza rimanente in auto, 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 ha un'opzione di visibilità non visibile, anche le polilinee del percorso devono fornire un'opzione di visibilità mai visibile.

  • Quando le polilinee dei percorsi e la posizione dei veicoli hanno tipi di opzioni di visibilità diversi, la posizione del veicolo è visibile solo quando entrambe le opzioni di visibilità sono soddisfatte.

    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 di guida rimanente è di almeno 3000 metri.

Inizia a utilizzare la libreria di condivisione del percorso JavaScript

Prima di utilizzare la libreria di condivisione del percorso JavaScript, assicurati di conoscere meglio Fleet Engine e ottenere una chiave API.

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

Crea una rivendicazione relativa all'ID monitoraggio

Per tracciare una spedizione utilizzando il fornitore della località di spedizione, crea un token web JSON (JWT) con una richiesta di ID monitoraggio.

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

L'esempio seguente mostra come creare un token per il monitoraggio per ID di 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",
   }
}

Crea 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 sui client. altrimenti rischi di compromettere 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 in questo periodo di tempo dopo il recupero.

La libreria JavaScript per il monitoraggio della spedizione richiede un token tramite il fetcher del token di autenticazione quando una delle seguenti condizioni è vera:

  • Non ha un token valido, ad esempio se non ha chiamato il fetcher in un nuovo caricamento pagina o se il fetcher non ha restituito il fetcher con un token.
  • Il token recuperato in precedenza è scaduto.
  • Il token recuperato in precedenza scade un minuto dopo la 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, il valore è 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 del 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 per il monitoraggio della spedizione 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 visualizzare il 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 per il tracciamento della spedizione per seguire un ritiro o una consegna di una spedizione. Assicurati di caricare la libreria dalla funzione di callback specificata nel tag script prima di eseguire il codice.

Creare un'istanza per un fornitore della località di spedizione

La JavaScript Shipment Tracking Library predefinisce un fornitore di località per l'API Fleet Engine Deliveries. Utilizza l'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> che include la visualizzazione mappa. Nell'esempio seguente, l'elemento <div> è denominato map_canvas.

Per evitare le condizioni di gara, imposta l'ID monitoraggio per il fornitore della 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 potrebbe corrispondere a diverse attività, ad esempio un ritiro e un'attività di consegna per lo stesso pacco o diversi tentativi di consegna non riusciti. Viene selezionata un'attività da mostrare sulla mappa di monitoraggio della spedizione. L'attività da mostrare è determinata come segue:

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

Ascolta gli eventi di modifica

Puoi recuperare le meta informazioni su un'attività dall'oggetto informazioni di monitoraggio dell'attività utilizzando il provider di posizione. Le meta informazioni includono l'orario di arrivo stimato, il numero di fermate rimanenti e la distanza rimanente prima del ritiro o della consegna. Le modifiche alle metadati 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 che derivano in modo asincrono dalla richiesta dei dati di spedizione attivano eventi di errore. 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 eseguire il wrapping delle chiamate alla libreria nei blocchi try...catch per gestire 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 = '';

Rimuovere il fornitore di 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 Maps, applica uno stile alla mappa utilizzando strumenti basati su cloud o impostando le opzioni direttamente nel codice.

Utilizza la personalizzazione delle mappe basata su cloud

La Personalizzazione delle mappe basata su cloud ti consente di creare e modificare gli stili di mappa per qualsiasi app che utilizza Google Maps dalla console Google Cloud, senza dover apportare modifiche al codice. Gli stili di mappa vengono salvati come ID mappa nel progetto Cloud. Per applicare uno stile alla tua mappa di monitoraggio della spedizione JavaScript, specifica un mapId quando crei JourneySharingMapView. Non è possibile modificare o aggiungere il campo mapId dopo aver creato l'istanza di JourneySharingMapView. L'esempio seguente 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.
});

Utilizza lo stile delle mappe basato 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 di monitoraggio della spedizione di JavaScript, puoi personalizzare l'aspetto degli indicatori aggiunti alla mappa. Per farlo, devi specificare le personalizzazioni degli indicatori, che verranno poi applicate dalla libreria di tracciamento delle spedizioni prima di aggiungere 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 le eventuali opzioni predefinite.

Un'opzione più avanzata è specificare una funzione di personalizzazione. Le funzioni di personalizzazione consentono di definire lo stile degli indicatori in base ai dati e di aggiungere interattività agli indicatori, ad esempio la gestione dei clic. Nello specifico, il monitoraggio delle spedizioni trasmette i dati alla funzione di personalizzazione del tipo di oggetto rappresentato dall'indicatore, ovvero veicolo o destinazione. In questo modo, lo stile degli indicatori può cambiare in base allo stato corrente dell'elemento indicatore stesso, ad esempio al numero di fermate pianificate rimanenti fino alla destinazione. Puoi anche eseguire l'unione con i dati provenienti da origini esterne a Fleet Engine e applicare uno stile all'indicatore in base a queste informazioni.

La libreria Monitoraggio della spedizione fornisce i seguenti parametri di personalizzazione in FleetEngineShipmentLocationProviderOptions:

Modifica lo stile degli indicatori utilizzando MarkerOptions

L'esempio seguente mostra come configurare lo stile dell'indicatore di un veicolo con un oggetto MarkerOptions. Segui questo pattern per personalizzare lo stile di qualsiasi indicatore utilizzando una delle personalizzazioni sopra elencate.

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 degli indicatori di veicoli. Segui questo pattern per personalizzare lo stile di qualsiasi indicatore usando uno dei parametri di personalizzazione dell'indicatore sopra elencati.

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

Aggiungi 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 dell'indicatore sopra elencati.

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

Utilizza personalizzazioni delle polilinee

Con la Shipment Tracking Library puoi anche personalizzare l'aspetto del percorso di 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 lo stile degli oggetti Polyline specificando le personalizzazioni delle polilinee. La libreria applica quindi queste personalizzazioni in due situazioni: prima di aggiungere oggetti alla mappa e quando i dati utilizzati per gli oggetti sono stati modificati.

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 assegnare 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 attuale della spedizione; ad esempio, colorando l'oggetto Polyline con una tonalità più profonda o rendendolo più spesso quando il veicolo si muove più lentamente. Puoi anche eseguire un 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 diversi stati del percorso nel 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 delle personalizzazioni delle polilinee 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 usando uno 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 InfoWindow per visualizzare informazioni aggiuntive su un veicolo o un indicatore di posizione.

L'esempio seguente mostra come creare un InfoWindow e collegarlo a un indicatore di veicoli:

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 adattarsi automaticamente all'area visibile al veicolo e al percorso previsto disattivando il montaggio automatico. L'esempio seguente mostra come disattivare l'adattamento automatico quando configuri la visualizzazione mappa per la condivisione del percorso.

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 di monitoraggio della spedizione di JavaScript per sostituire una mappa esistente che include indicatori o altre personalizzazioni senza perdere queste personalizzazioni.

Ad esempio, supponiamo che tu abbia una pagina web con un'entità google.maps.Map standard in cui viene mostrato 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 la fabbrica del token di autenticazione.
  2. Inizializza un provider di località 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 di località al caricatore 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 vicino a Uluru, ora verrà visualizzato sulla mappa.