Śledzenie przesyłki za pomocą biblioteki śledzenia dostawy JavaScript

Biblioteka śledzenia przesyłek w języku JavaScript umożliwia wizualizację lokalizacji pojazdów i interesujących lokalizacji śledzonych we Fleet Engine. Biblioteka zawiera komponent mapy JavaScript, który zastępuje standardową encję google.maps.Map i komponenty danych w celu połączenia z Fleet Engine. Dzięki bibliotece śledzenia przesyłek w JavaScripcie możesz korzystać z animowanych funkcji śledzenia przesyłki z poziomu swojej aplikacji internetowej.

Komponenty

Biblioteka śledzenia przesyłek w języku JavaScript zawiera komponenty do wizualizacji pojazdu i trasy w czasie podróży do miejsca docelowego, a także nieprzetworzone dane o szacowanym czasie dotarcia kierowcy lub o pozostałej odległości do przejechania.

Widok mapy śledzenia przesyłek

Komponent widoku mapy wizualizuje lokalizację pojazdów i miejsc docelowych. Jeśli trasa pojazdu jest znana, komponent widoku mapy animuje go, gdy porusza się on po przewidywanej trasie.

Dostawca lokalizacji dostawy

Dostawca lokalizacji przesyłki przesyła informacje o lokalizacji śledzonych obiektów do mapy śledzenia przesyłki, aby śledzić przesyłkę na pierwszej i ostatniej trasie.

Możesz skorzystać z usług dostawcy lokalizacji dostawy, aby śledzić:

  • Miejsce odbioru lub dostawy przesyłki.
  • Lokalizacja i trasa pojazdu dostawczego.

Śledzone obiekty lokalizacji

Dostawca usługi lokalizacji śledzi lokalizację obiektów, takich jak pojazdy i miejsca docelowe.

Lokalizacja docelowa

Lokalizacja docelowa to miejsce, w którym kończy się podróż. W przypadku śledzenia dostawy jest to planowane miejsce działania.

Lokalizacja pojazdu

Lokalizacja pojazdu to jego monitorowana lokalizacja. Opcjonalnie może obejmować trasę dla pojazdu.

Moduł pobierania tokenów uwierzytelniania

Aby kontrolować dostęp do danych o lokalizacji przechowywanych we Fleet Engine, musisz wdrożyć na swoim serwerze usługę generowania tokenów sieciowych JSON (JWT) dla Fleet Engine. Następnie zaimplementuj narzędzie do pobierania tokenów uwierzytelniania w swojej aplikacji internetowej, korzystając z biblioteki udostępniania czynności JavaScript w celu uwierzytelniania dostępu do danych o lokalizacji.

Opcje stylu

Style znaczników i linii łamanych określają wygląd i styl śledzonych obiektów lokalizacji na mapie. Za pomocą opcji stylów niestandardowych możesz zmienić styl domyślny, by pasował do stylu Twojej aplikacji internetowej.

Kontrolowanie widoczności śledzonych lokalizacji

W tej sekcji opisujemy elementy sterujące widocznością śledzonych obiektów na mapie. Te reguły dotyczą 2 kategorii obiektów:

  • Znacznik lokalizacji
  • Dane zadania

Widoczność znacznika lokalizacji

Wszystkie znaczniki lokalizacji miejsca wylotu i celu podróży są zawsze wyświetlane na mapie. Na przykład miejsce dostawy jest zawsze wyświetlane na mapie, niezależnie od stanu dostawy.

Widoczność danych zadania

W tej sekcji opisano domyślne reguły widoczności, które mają zastosowanie do danych zadań, takich jak lokalizacja pojazdu i pozostała trasa. Możesz dostosować wiele zadań, ale nie wszystkie:

  • Zadania związane z niedostępnością – nie możesz dostosować widoczności tych zadań.
  • Aktywne zadania związane z pojazdem – możesz dostosować ten typ zadań.
  • Nieaktywne zadania związane z pojazdem – nie możesz dostosować widoczności tych zadań.

Zadania związane z niedostępnością

Jeśli na trasie prowadzącej do śledzonego zadania występuje co najmniej jedno zadanie związane z niedostępnością (np. kierowca robi sobie przerwę lub uzupełnia paliwo), pojazd nie jest widoczny. Szacowany czas dotarcia i szacowany czas ukończenia zadania są nadal dostępne.

Aktywne zadania związane z pojazdem

Obiekt TaskTrackingInfo zawiera wiele elementów danych, które można wyświetlić w bibliotece śledzenia przesyłki. Domyślnie te pola są widoczne, gdy zadanie zostanie przypisane do pojazdu lub gdy pojazd znajdzie się w odległości do 5 przesiadek. Widoczność przestaje być widoczna po ukończeniu lub anulowaniu zadania. Pola są następujące:

  • Linie łamane trasy
  • Szacowany czas dotarcia na miejsce
  • Szacowany czas ukończenia zadania
  • Pozostała odległość do pracy do zadania
  • Liczba pozostałych przystanków
  • Lokalizacja pojazdu

Konfigurację widoczności możesz dostosowywać dla poszczególnych zadań, ustawiając TaskTrackingViewConfig dla zadania podczas jego tworzenia lub aktualizowania w Fleet Engine. Spowoduje to utworzenie reguł określających dostępność poszczególnych elementów danych, które mogą być oparte na tych kryteriach (opcjach widoczności poniżej):

  • Liczba pozostałych przystanków
  • Czas podróży do przewidywanej godziny przyjazdu
  • Pozostała odległość do jazdy samochodem
  • Zawsze widoczne
  • Nigdy niewidoczne

Pamiętaj, że każdy element danych może być powiązany tylko z jedną opcją widoczności. Nie można łączyć kryteriów za pomocą operatorów LUB ani ORAZ.

Oto przykład dostosowania: Zasady tego dostosowania są następujące:

  • Pokaż linie łamane trasy, jeśli pojazd znajduje się w promieniu 3 przystanków.
  • Pokaż szacowany czas dotarcia, jeśli pozostały dystans przejazdu jest krótszy niż 5000 metrów.
  • Nigdy nie pokazuj liczby przystanków.
  • Każde pozostałe pole zachowuje domyślną widoczność, która jest wyświetlana, gdy pojazd znajduje się w odległości 5 przystanków od zadania.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Możesz też dostosować domyślną konfigurację widoczności projektu, kontaktując się z zespołem pomocy.

Linie łamane trasy i reguły widoczności lokalizacji pojazdu:

Gdy linie łamane na trasie są widoczne, musi być też widoczna lokalizacja pojazdu. W przeciwnym razie lokalizacja pojazdu może być określona na końcu linii łamanej. Oznacza to, że linie łamane tras nie mogą mieć mniej restrykcyjnej opcji widoczności.

Aby można było uzyskać prawidłową kombinację linii łamanych trasy i widoczności lokalizacji pojazdu, należy ich przestrzegać:

  • Gdy linie łamane na trasie i lokalizacja pojazdu mają ten sam typ opcji widoczności:

    • Jeśli w opcji widoczności pozostaje liczba postojów, czas trwania do czasu dotarcia na miejsce lub pozostały dystans samochodem, linie łamane na trasie muszą zawierać wartość mniejszą od wartości ustawionej dla tej opcji widoczności dla lokalizacji pojazdu. Oto przykład:
    "taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
    • Jeśli linie łamane na trasie mają opcję widoczności „zawsze widoczna”, lokalizacja pojazdu musi też zapewniać opcję widoczności, która jest zawsze widoczna.
    • Jeśli lokalizacja pojazdu ma opcję widoczności „Nigdy niewidoczna”, linie łamane trasy muszą też zawierać opcję widoczności „Nigdy niewidoczną”.

  • Gdy linie łamane na trasie i lokalizacja pojazdu mają różne opcje widoczności, lokalizacja pojazdu jest widoczna tylko wtedy, gdy spełnione są obie opcje widoczności.

    Oto przykład:

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

    W tym przykładzie lokalizacja pojazdu jest widoczna tylko wtedy, gdy pozostała liczba postojów wynosi co najmniej 3 ORAZ pozostały dystans przejazdu to co najmniej 3000 metrów.

Pierwsze kroki z biblioteką udostępniania czynności JavaScriptu

Przed skorzystaniem z biblioteki udostępniania czynności w JavaScript upewnij się, że znasz Fleet Engine i jak uzyskać klucz interfejsu API.

Aby śledzić dostawę, najpierw utwórz roszczenie dotyczące identyfikatora śledzenia.

Tworzenie roszczenia dotyczącego identyfikatora śledzenia

Aby śledzić przesyłkę za pomocą dostawcy miejsca wysyłki, utwórz token sieciowy JSON (JWT) z deklaracjami identyfikatora śledzenia.

Aby utworzyć ładunek JWT, dodaj w sekcji autoryzacji dodatkową deklarację z kluczem trackingid. Jako jego wartość ustaw identyfikator śledzenia przesyłki.

Z przykładu poniżej dowiesz się, jak utworzyć token na potrzeby śledzenia według identyfikatora śledzenia:

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

Tworzenie modułu pobierania tokenów uwierzytelniania

Możesz utworzyć moduł pobierania tokenów uwierzytelniania, aby pobrać token wykryty z odpowiednimi deklaracjami na Twoich serwerach przy użyciu certyfikatu konta usługi dla Twojego projektu. Ważne jest, aby tokeny generować tylko na swoich serwerach i nigdy nie udostępniać certyfikatów żadnym klientom. Jeśli tego nie zrobisz, bezpieczeństwo Twojego systemu będzie narażone na niebezpieczeństwo.

Moduł pobierania musi zwrócić strukturę danych z 2 polami ujętymi w obietnicę:

  • Ciąg tekstowy token.
  • Numer expiresInSeconds. Token wygasa po tym czasie po pobraniu.

Biblioteka śledzenia dostawy JavaScriptu żąda tokena za pomocą modułu pobierania tokenów uwierzytelniania, gdy jest spełniony dowolny z tych warunków:

  • Nie ma ona prawidłowego tokena, na przykład nie wywołała modułu pobierania przy nowym wczytaniu strony lub nie zwróciła przy użyciu tokena.
  • Pobrany wcześniej token wygasł.
  • Token, który został pobrany wcześniej, przypada w ciągu minuty od wygaśnięcia.

W przeciwnym razie biblioteka używa wcześniej wydanego, ale nadal prawidłowego tokena i nie wywołuje modułu pobierania.

Z przykładu poniżej dowiesz się, jak utworzyć moduł pobierania tokenów uwierzytelniania:

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

Implementując punkt końcowy po stronie serwera do generowania tokenów, pamiętaj o tych kwestiach:

  • Punkt końcowy musi zwrócić czas wygaśnięcia tokena. W powyższym przykładzie jest to wartość data.ExpiresInSeconds.
  • Moduł pobierania tokenów uwierzytelniania musi przekazać do biblioteki czas wygaśnięcia (w sekundach, od czasu pobrania) do biblioteki, jak pokazano w przykładzie.
  • Adres URL serwera SERVER_TOKEN_URL zależy od implementacji backendu. Oto URL-e przykładowego backendu aplikacji:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/czytnik_floty

Wczytywanie mapy z HTML

Poniższy przykład pokazuje, jak wczytać bibliotekę śledzenia dostawy JavaScript z określonego adresu URL. Parametr callback wykonuje funkcję initMap po wczytaniu interfejsu API. Atrybut defer umożliwia przeglądarce kontynuowanie renderowania pozostałej części strony podczas wczytywania interfejsu API.

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

Śledź przesyłkę

W tej sekcji pokazujemy, jak korzystać z biblioteki śledzenia dostawy JavaScriptu, aby śledzić dostawę lub odbiór przesyłki. Przed uruchomieniem kodu pamiętaj, aby załadować bibliotekę z funkcji wywołania zwrotnego określonej w tagu skryptu.

Utwórz dostawcę lokalizacji dostawy

Biblioteka śledzenia dostawy JavaScript wstępnie definiuje dostawcę lokalizacji dla Fleet Engine Deliveries API. Utwórz instancję, używając identyfikatora projektu i odniesienia do fabryki tokenów.

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

Inicjowanie widoku mapy

Po wczytaniu biblioteki JavaScript udostępniania czynności w języku JavaScript zainicjuj widok mapy i dodaj go do strony HTML. Strona powinna zawierać element <div> z widokiem mapy. W tym przykładzie element <div> ma nazwę map_canvas.

Aby uniknąć wyścigu, ustaw identyfikator śledzenia dostawcy lokalizacji w wywołaniu zwrotnym, które jest wywoływane po zainicjowaniu mapy.

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProvider: 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'),
  locationProvider: 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);

Identyfikator śledzenia

Identyfikator śledzenia dostarczony dostawcy lokalizacji może odpowiadać kilku działaniom, takim jak odbiór i dostarczenie tej samej przesyłki lub kilka nieudanych prób dostarczenia. Wybrano jedno zadanie do wyświetlania na mapie śledzenia przesyłek. Zadanie do wyświetlenia jest określane w następujący sposób:

  1. Jeśli jest dokładnie 1 otwarte zadanie odbioru, jest ono wyświetlane. Jeśli istnieje wiele otwartych zadań odbioru, generowany jest błąd.
  2. Jeśli jest otwarte dokładnie jedno zadanie wyświetlania, zostanie ono wyświetlone. W przypadku wielu otwartych zadań dostarczania generowany jest błąd.
  3. Jeśli masz zamknięte zadania związane z wyświetlaniem:
    • Jeśli jest dokładnie 1 zamknięte zadanie wyświetlania, zostanie ono wyświetlone.
    • Jeśli jest wiele zamkniętych zadań wyświetlania, wyświetlane jest to z najnowszym czasem zakończenia wyświetlania.
    • W przypadku wielu zamkniętych zadań wyświetlania, z których żadne nie ma określonego czasu wyniku, generowany jest błąd.
  4. Jeśli masz zamknięte zadania odbioru:
    • Jeśli masz dokładnie 1 zamknięte zadanie odbioru, zostanie ono wyświetlone.
    • Jeśli jest wiele zamkniętych zadań odbioru, wyświetlane jest to z ostatnim czasem dostawy.
    • Jeśli istnieje wiele zamkniętych zadań odbioru, z których żadne nie ma określonego czasu wyniku, generowany jest błąd.
  5. W przeciwnym razie nie jest wyświetlane żadne zadanie.

Nasłuchiwanie zdarzeń zmian

Możesz pobrać metadane o zadaniu z obiektu informacji o śledzeniu zadania przy użyciu dostawcy lokalizacji. Metainformacje obejmują szacowany czas dotarcia, liczbę pozostałych przystanków i pozostałą odległość przed odbiorem lub dostawą. Zmiany w metainformacjach wywołują zdarzenie update. Z przykładu poniżej dowiesz się, jak nasłuchiwać tych zdarzeń zmiany.

JavaScript

locationProvider.addListener('update', e => {
  // e.task 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.task contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

Obsługa błędów

Błędy powstające asynchronicznie w wyniku żądania informacji o dostawie wywołują zdarzenia błędów. Z przykładu poniżej dowiesz się, jak nasłuchiwać tych zdarzeń w celu obsługi błędów.

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

Uwaga: pamiętaj o zapakowaniu wywołań biblioteki w bloki try...catch, by obsługiwać nieprzewidziane błędy.

Dostosuj wygląd i styl mapy podstawowej

Aby dostosować wygląd i styl komponentu map, zmień styl mapy za pomocą narzędzi działających w chmurze lub ustawiając opcje bezpośrednio w kodzie.

Użyj stylu mapy opartego na chmurze

Definiowanie stylów map w Google Cloud pozwala tworzyć i edytować style mapy w dowolnych aplikacjach korzystających z Map Google z poziomu konsoli Google Cloud bez konieczności wprowadzania zmian w kodzie. Style mapy są zapisywane jako identyfikatory map w Twoim projekcie Cloud. Aby zastosować styl do mapy śledzenia przesyłek JavaScript, podaj mapId podczas tworzenia JourneySharingMapView. Po utworzeniu wystąpienia JourneySharingMapView nie można zmienić ani dodać pola mapId. Z przykładu poniżej dowiesz się, jak włączyć utworzony wcześniej styl mapy z identyfikatorem mapy.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProvider: locationProvider,
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProvider: locationProvider,
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

Użyj stylu mapy opartego na kodzie

Innym sposobem dostosowania stylu mapy jest ustawienie mapOptions podczas tworzenia tagu JourneySharingMapView.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProvider: locationProvider,
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProvider: locationProvider,
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

Zmienianie stylu i widoczności tras

Aby skonfigurować styl i widoczność podejmowanych i przewidywanych tras, użyj niestandardowych opcji stylu. Więcej informacji znajdziesz w artykule o interfejsie PolylineOptions.

Z przykładu poniżej dowiesz się, jak skonfigurować styl i widoczność przewidywanych tras. Aby skonfigurować styl i widoczność robionych tras, użyj takenRoutePolylineSetup zamiast anticipatedRoutePolylineSetup.

JavaScript

// This function is specified in the 
// JourneySharingMapView constructor's options 
// parameter.
function anticipatedRoutePolylineSetup({
    defaultPolylineOptions, defaultVisible}) {
  // If this function is not specified, the 
  // PolylineOptions object contained in 
  // defaultPolylineOptions is used to render the
  // anticipated route polyline. visible property sets the
  // polyline's visibility. Modify this object and 
  // pass it back to customize the style of the map.
  defaultPolylineOptions.strokeOpacity = 0.5;
  defaultPolylineOptions.strokeColor = 'red';
  return {
    polylineOptions: defaultPolylineOptions,
    visible: true
  };
}

// As an alternative, set a static PolylineOptions to 
// use for the anticipated route:
const anticipatedRoutePolylineOptionsSetup = {
  polylineOptions: {
    strokeOpacity: 0.5,
    strokeColor: 'red',
    …
  },
  visible: true,
};

TypeScript

// This function is specified in the 
// JourneySharingMapView constructor's options 
// parameter.
function anticipatedRoutePolylineSetup(options: {
  defaultPolylineOptions: google.maps.PolylineOptions,
  visible: boolean,
}): {
  polylineOptions: google.maps.PolylineOptions,
  visible: boolean,
} {
  // If this function is not specified, the 
  // PolylineOptions object contained in 
  // defaultPolylineOptions is used to render the
  // anticipated route polyline. visible property sets the
  // polyline's visibility. Modify this object and 
  // pass it back to customize the style of the map.
  options.defaultPolylineOptions.strokeOpacity = 0.5;
  options.defaultPolylineOptions.strokeColor = 'red';
  return {
    polylineOptions: options.defaultPolylineOptions,
    visible: true
  };
}

// As an alternative, set a static PolylineOptions to 
// use for the anticipated route:
const anticipatedRoutePolylineSetup = {
  polylineOptions: {
    strokeOpacity: 0.5,
    strokeColor: 'red',
    …
  },
  visible: true,
};

Skorzystaj z dostosowań znaczników

W bibliotece śledzenia przesyłek JavaScript możesz dostosować wygląd i sposób działania znaczników dodawanych do mapy. W tym celu musisz określić dostosowania znaczników, które będzie stosować Biblioteka śledzenia przesyłek przed ich dodaniem do mapy i po każdej ich aktualizacji.

Najprostsze dostosowanie to określenie obiektu MarkerOptions, który będzie stosowany do wszystkich znaczników tego samego typu. Zmiany określone w obiekcie zostaną zastosowane po utworzeniu każdego znacznika, zastępując wszystkie opcje domyślne.

Bardziej zaawansowaną opcją jest określenie funkcji dostosowywania. Funkcje dostosowywania umożliwiają nadawanie stylu znaczników na podstawie danych, a także dodawanie do znaczników elementów interaktywnych, np. obsługi kliknięć. W szczególności śledzenie dostawy przekazuje do funkcji dostosowywania dane o typie obiektu reprezentowanego przez znacznik: pojazdu lub miejsca docelowego. Dzięki temu styl znaczników może się zmieniać na podstawie bieżącego stanu samego elementu znacznika, np. liczby planowanych przystanków pozostałych do miejsca docelowego. Możesz nawet łączyć dane ze źródeł spoza Fleet Engine i dostosowywać na ich podstawie styl znacznika.

Biblioteka śledzenia przesyłek zawiera te parametry dostosowania w FleetEngineShipmentLocationProviderOptions:

Zmień styl znaczników za pomocą: MarkerOptions

Z przykładu poniżej dowiesz się, jak skonfigurować styl znacznika pojazdu za pomocą obiektu MarkerOptions. Użyj tego wzoru, by dostosować styl dowolnego markera za pomocą powyższych metod.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Zmiana stylu znaczników przy użyciu funkcji dostosowywania

Poniższy przykład pokazuje, jak skonfigurować styl oznakowania pojazdu. Użyj tego wzoru, aby dostosować styl dowolnego znacznika za pomocą dowolnych parametrów dostosowania znaczników wymienionych powyżej.

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

Dodaj obsługę kliknięć do znaczników

Poniższy przykład pokazuje, jak dodać obsługę kliknięć do znacznika pojazdu. Użyj tego wzoru, by dodać obsługę kliknięć do dowolnego znacznika za pomocą dowolnego z wymienionych powyżej parametrów dostosowania znacznika.

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

Wyświetl InfoWindow dla znacznika pojazdu lub lokalizacji

Korzystając z InfoWindow, możesz wyświetlić dodatkowe informacje o pojeździe lub znaczniku lokalizacji.

Poniższy przykład pokazuje, jak utworzyć obiekt InfoWindow i przymocować go do znacznika pojazdu:

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

Wyłącz automatyczne dopasowanie

Możesz wyłączyć automatyczne dopasowanie widocznego obszaru do pojazdu i przewidywanej trasy, wyłączając automatyczne dopasowanie. Z przykładu poniżej dowiesz się, jak wyłączyć automatyczne dopasowywanie podczas konfigurowania widoku mapy do udostępniania przejazdu.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProvider: 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();

Zastępowanie istniejącej mapy

Za pomocą biblioteki JavaScript śledzenia dostawy możesz zastąpić istniejącą mapę ze znacznikami lub innymi dostosowaniami bez utraty tych dostosowań.

Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map, na którym wyświetla się znacznik:

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

Aby dodać bibliotekę udostępniania czynności JavaScript w języku JavaScript:

  1. Dodaj kod fabryki tokenów uwierzytelniania.
  2. Inicjowanie dostawcy lokalizacji w funkcji initMap().
  3. Zainicjuj widok mapy w funkcji initMap(). Widok zawiera mapę.
  4. Przenieś swoje modyfikacje do funkcji wywołania zwrotnego w celu inicjowania widoku mapy.
  5. Dodaj bibliotekę lokalizacji do programu wczytującego interfejs API.

Przykład poniżej pokazuje zmiany do wprowadzenia:

<!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'), 
    locationProvider: 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>

Jeśli masz śledzoną paczkę o określonym identyfikatorze w pobliżu Uluru, zostanie ona wyświetlona na mapie.