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

Biblioteka śledzenia przesyłek 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 JavaScript możesz zapewnić spersonalizowaną, animowaną funkcję śledzenia przesyłki z poziomu swojej aplikacji internetowej.

Komponenty

Biblioteka śledzenia przesyłek JavaScript zawiera komponenty do wizualizacji pojazdu i trasy w miarę przesuwania się do miejsca docelowego, a także pliki nieprzetworzonych danych o szacowanym czasie dotarcia kierowcy lub 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 pojazd, poruszając się po przewidywanej trasie.

Dostawca miejsca dostawy

Dostawca lokalizacji dostawy przesyła do mapy śledzenia przesyłki informacje o lokalizacji śledzonych obiektów, aby umożliwić śledzenie przesyłki na pierwszej i ostatniej mili.

Możesz korzystać z usług dostawcy miejsca dostawy, aby śledzić:

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

Śledzone obiekty lokalizacji

Dostawca 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 lokalizacja zaplanowanego zadania.

Lokalizacja pojazdu

Lokalizacja pojazdu to jego śledzona lokalizacja. Może ona opcjonalnie obejmować trasę dla pojazdu.

Narzędzie do 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 w swojej aplikacji internetowej zaimplementuj moduł pobierania tokenów uwierzytelniania, korzystając z biblioteki udostępniania ścieżki 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 stylu niestandardowego możesz zmienić styl domyślny, by pasował do stylu Twojej aplikacji internetowej.

Kontrolowanie widoczności śledzonych lokalizacji

W tej sekcji opisujemy ustawienia widoczności śledzonych obiektów na mapie. Te reguły mają zastosowanie do 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 zawsze jest wyświetlane na mapie, niezależnie od stanu dostawy.

Widoczność danych zadania

W tej sekcji opisujemy domyślne reguły widoczności, które mają zastosowanie do danych o zadaniach, 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ć te rodzaje zadań.
• Zadania związane z nieaktywnymi pojazdami – nie możesz dostosować widoczności dla tych zadań.

Zadania związane z niedostępnością

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

Aktywne zadania związane z pojazdem

Obiekt TaskTrackingInfo zawiera elementy danych, które można wyświetlać w bibliotece śledzenia przesyłek. Domyślnie te pola są widoczne, gdy zadanie zostanie przypisane do pojazdu, lub gdy znajdzie się on w odległości 5 przesiadek od zadania. Widoczność kończy się 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 zadania
• Liczba pozostałych przystanków
• Lokalizacja pojazdu

Możesz dostosować konfigurację widoczności dla poszczególnych zadań, ustawiając obiekt TaskTrackingViewConfig w zadaniu podczas jego tworzenia lub aktualizowania we Fleet Engine. Spowoduje to utworzenie reguł określających dostępność poszczególnych elementów danych, które mogą opierać się na tych kryteriach (opcjach widoczności poniżej):

• Liczba pozostałych przystanków
• Czas podróży do szacowanej godziny przyjazdu
• Pozostała odległość dojazdowa
• 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 dostosowania:

• Pokazuj linie łamane trasy, jeśli pojazd znajduje się w maksymalnie 3 przystankach.
• Pokaż szacowany czas dotarcia na miejsce, jeśli pozostała odległość jest mniejsza niż 5000 metrów.
• Nigdy nie pokazuj pozostałej 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 trasy są widoczne, musi być też widoczna lokalizacja pojazdu. W przeciwnym razie lokalizacja pojazdu może być określona na końcu linii łamanych. Oznacza to, że linie łamane tras nie mogą mieć mniej restrykcyjnej opcji widoczności.

Należy ich przestrzegać, aby uzyskać prawidłową kombinację linii łamanych trasy i widoczność lokalizacji pojazdu:

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

  • Jeśli opcja widoczności nadal podaje liczbę przystanków, czas do osiągnięcia czasu dotarcia na miejsce lub pozostały dystans jazdy, linie łamane trasy muszą podawać wartość mniejszą lub równą 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 zawsze widoczna.
  • Jeśli lokalizacja pojazdu ma opcję widoczności nigdy niewidocznej, linie łamane trasy muszą zawierać opcję widoczności nigdy niewidocznej.

• 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 liczba pozostałych przystanków wynosi co najmniej 3 ORAZ pozostała odległość co najmniej 3000 metrów.

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

Przed skorzystaniem z biblioteki udostępniania ścieżki JavaScript zapoznaj się z funkcją Fleet Engine i uzyskaj klucz interfejsu API.

Aby śledzić dostawę, najpierw utwórz roszczenie z identyfikatorem śledzenia.

Tworzenie roszczenia dotyczącego identyfikatora śledzenia

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

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

Z przykładu poniżej dowiesz się, jak utworzyć token do ś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ć na swoje serwery token z odpowiednimi deklaracjami przy użyciu certyfikatu konta usługi przypisanego do Twojego projektu. Pamiętaj, aby generować tokeny tylko na swoich serwerach i nigdy nie udostępniać certyfikatów żadnym klientom. W przeciwnym razie naraża to bezpieczeństwo systemu.

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

• Ciąg znaków token.
• Numer expiresInSeconds. Po pobraniu token wygasa po tym czasie.

Biblioteka śledzenia przesyłek JavaScript wysyła żądanie tokena za pomocą modułu pobierania tokenów uwierzytelniania, gdy spełniony jest dowolny z tych warunków:

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

W przeciwnym razie biblioteka używa wcześniej wystawionego tokena, który nadal jest prawidłowy i nie wywołuje modułu pobierania.

Poniższy przykład pokazuje, jak utworzyć moduł pobierania tokenów uwierzytelniania:

function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

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

• Punkt końcowy musi zwracać datę wygaśnięcia tokena. W powyższym przykładzie jest on podany jako data.ExpiresInSeconds.
• Zgodnie z przykładem narzędzie pobierania tokenów uwierzytelniania musi przekazać czas wygaśnięcia (w sekundach, od czasu pobrania) do biblioteki.
• Wartość SERVER_TOKEN_URL zależy od implementacji backendu. Oto URL-e backendu przykładowej aplikacji:
  • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
  • https://SERVER_URL/token/fleet_reader

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 reszty strony podczas wczytywania interfejsu API.

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

Śledzenie przesyłki

W tej sekcji pokazujemy, jak korzystać z biblioteki śledzenia dostawy JavaScript za pomocą biblioteki śledzenia przesyłki do śledzenia przesyłki. Pamiętaj, aby przed uruchomieniem kodu załadować bibliotekę z funkcji wywołania zwrotnego określonej w tagu skryptu.

Utwórz instancję dostawcy miejsca dostawy

Biblioteka śledzenia przesyłek JavaScript wstępnie definiuje dostawcę lokalizacji dla Fleet Engine Deliveries API. Aby utworzyć instancję, użyj identyfikatora projektu i odniesienia do fabryki tokenów.

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

Inicjowanie widoku mapy

Po wczytaniu biblioteki udostępniania ścieżki JavaScript JavaScript zainicjuj widok mapy i dodaj go do strony HTML. Strona powinna zawierać element <div>, który utrzymuje widok mapy. W poniższym przykładzie element <div> nosi nazwę map_canvas.

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

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-id';

// Give the map an initial viewport to allow it to 
// initialize; otherwise the 'ready' event above may 
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // Any undefined styling options will use defaults.
});

// If you did not specify a tracking ID in the location
// provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.trackingId = 'your-tracking-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may 
// not fire. The user also has access to the mapView
// object to customize as they wish.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

Identyfikator śledzenia

Identyfikator śledzenia przekazany dostawcy lokalizacji może odpowiadać kilku działaniom, np. zadaniu odbioru i dostawy tego samego przesyłki lub kilku nieudanych próbom dostarczenia. Wybrano jedno zadanie do wyświetlenia na mapie śledzenia przesyłki. Zadanie do wyświetlenia jest określane w następujący sposób:

1. Jeśli jest dokładnie 1 otwarte zadanie odbioru, będzie ono widoczne. Jeśli jest wiele otwartych zadań odbioru, pojawia się błąd.
2. Jeśli jest tylko 1 otwarte zadanie dostarczania, zostanie ono wyświetlone. Jeśli jest wiele otwartych zadań dostarczania, pojawia się błąd.
3. Jeśli masz zamknięte zadania dostawy:
   • Jeśli jest dokładnie 1 zamknięte zadanie wyświetlania, jest ono widoczne.
   • Jeśli jest wiele zamkniętych zadań związanych z wyświetlaniem, 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 jest dokładnie 1 zamknięte zadanie odbioru, będzie ono widoczne.
   • Jeśli jest wiele zamkniętych zadań odbioru, wyświetlane jest to z najnowszym czasem dostawy.
   • Jeśli istnieje wiele zamkniętych zadań odbioru, z których żadne nie ma określonego czasu wyniku, zostanie wygenerowany błąd.
5. W przeciwnym razie nie jest wyświetlane żadne zadanie.

Wykrywaj zmiany

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

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

Obsługa błędów

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

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

Uwaga: wywołania biblioteki pakuj w bloki try...catch, aby obsłużyć nieprzewidziane błędy.

Zakończ śledzenie

Aby uniemożliwić dostawcy lokalizacji śledzenie przesyłki, usuń identyfikator śledzenia od dostawcy lokalizacji.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

Usuń dostawcę lokalizacji z widoku mapy

Poniższy przykład pokazuje, jak usunąć dostawcę lokalizacji z widoku mapy.

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

Dostosuj wygląd i styl mapy podstawowej

Aby dostosować wygląd i styl komponentu mapy, 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

Style map w Google Cloud pozwalają 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 projekcie Cloud. Aby zastosować styl do mapy śledzenia przesyłek JavaScript, podczas tworzenia tagu JourneySharingMapView podaj mapId. Po utworzeniu instancji JourneySharingMapView nie można zmienić ani dodać pola mapId. Poniższy przykład pokazuje, jak włączyć wcześniej utworzony styl mapy z identyfikatorem mapy.

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

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

Użyj stylu mapy opartego na kodzie

Innym sposobem dostosowywania stylu mapy jest ustawienie mapOptions podczas tworzenia elementu JourneySharingMapView.

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

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

Dostosuj znaczniki

Za pomocą biblioteki śledzenia przesyłek JavaScript możesz dostosować wygląd i działanie znaczników dodawanych do mapy. Możesz to zrobić, określając dostosowania znaczników, które będzie stosować Biblioteka śledzenia przesyłek przed ich dodaniem do mapy i przy każdej ich aktualizacji.

Najprostszym sposobem dostosowania jest określenie obiektu MarkerOptions, który zostanie zastosowany do wszystkich znaczników tego samego typu. Zmiany określone w obiekcie są stosowane po utworzeniu każdego znacznika, zastępując wszystkie opcje domyślne.

Bardziej zaawansowaną opcją jest określenie funkcji dostosowywania. Funkcje dostosowywania umożliwiają określanie 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 przesyłek 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ć zależnie od bieżącego stanu samego elementu znacznika, np. liczby planowanych przystanków pozostałych do miejsca docelowego. Możesz nawet złączać z danymi pochodzącymi ze źródeł spoza Fleet Engine i na tej podstawie określać styl znacznika.

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

• deliveryVehicleMarkerCustomization
• destinationMarkerCustomization

Zmień styl znaczników za pomocą: MarkerOptions

Poniższy przykład pokazuje, jak skonfigurować styl znacznika pojazdu za pomocą obiektu MarkerOptions. Postępując zgodnie z tym wzorem, możesz dostosować styl dowolnego znacznika za pomocą powyższych sposobów.

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Zmiana stylu znaczników za pomocą funkcji dostosowywania

Poniższy przykład pokazuje, jak skonfigurować styl oznakowania pojazdu. Postępuj zgodnie z tym wzorcem, aby dostosować styl dowolnego znacznika za pomocą dowolnego z wymienionych powyżej parametrów dostosowania znacznika.

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

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

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

Przykład poniżej pokazuje, jak dodać obsługę kliknięć do znacznika pojazdu. Postępuj zgodnie z tym wzorcem, aby dodać obsługę kliknięć do dowolnego znacznika z wykorzystaniem dowolnego z wymienionych powyżej parametrów dostosowania znacznika.

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

Dostosuj linię łamaną

W bibliotece śledzenia przesyłki możesz też dostosować wygląd i styl trasy przesyłki na mapie. Biblioteka tworzy obiekt google.maps.Polyline dla każdej pary współrzędnych w aktywnej lub pozostałej ścieżce przesyłki. Możesz określić styl obiektów Polyline, określając dostosowania linii łamanej. Biblioteka stosuje te dostosowania w 2 sytuacjach: przed dodaniem obiektów do mapy i gdy zmienią się dane używane do tych obiektów.

Podobnie jak w przypadku dostosowywania znaczników, możesz określić zestaw obiektów PolylineOptions, który zostanie zastosowany do wszystkich pasujących obiektów Polyline podczas ich tworzenia lub aktualizacji.

Możesz także określić funkcję dostosowywania. Funkcje dostosowywania umożliwiają nadawanie im indywidualnych stylów obiektów na podstawie danych wysyłanych przez Fleet Engine. Funkcja może zmieniać styl każdego obiektu w zależności od jego aktualnego stanu dostawy, np. kolorować obiekt Polyline bardziej odcień lub pogrubić go, gdy pojazd jedzie wolniej. Możesz nawet złączać się ze źródłami spoza Fleet Engine i na tej podstawie określać styl obiektu Polyline.

Możesz określić dostosowania za pomocą parametrów w FleetEngineShipmentLocationProviderOptions. Możesz dostosować ustawienia dla różnych stanów na trasie pojazdu – już w podróży, w trakcie podróży lub jeszcze nie. Parametry są następujące:

• takenPolylineCustomization, w przypadku już przebytej trasy;
• activePolylineCustomization, w przypadku aktywnie poruszającej się ścieżki;
• remainingPolylineCustomization, jeśli jeszcze nie przebyta trasa.

Zmień styl obiektów Polyline za pomocą elementu PolylineOptions

Przykład poniżej pokazuje, jak skonfigurować styl obiektu Polyline w PolylineOptions. Korzystając z tego wzorca, możesz dostosować styl dowolnego obiektu Polyline za pomocą dowolnych spośród opisanych wcześniej dostosowań linii łamanych.

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

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

Zmień styl obiektów Polyline za pomocą funkcji dostosowywania

Poniższy przykład pokazuje, jak skonfigurować styl aktywnego obiektu Polyline. Korzystając z tego wzorca, możesz dostosować styl dowolnego obiektu Polyline za pomocą dowolnych parametrów dostosowania linii łamanej wymienionych wcześniej.

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

Kontroluj widoczność Polyline obiektów

Domyślnie widoczne są wszystkie obiekty Polyline. Aby ustawić obiekt Polyline jako niewidoczny, ustaw jego właściwość visible:

remainingPolylineCustomization = {visible: false};

remainingPolylineCustomization = {visible: false};

Wyświetl InfoWindow w przypadku pojazdu lub znacznika lokalizacji

Aby wyświetlić dodatkowe informacje o pojeździe lub znaczniku lokalizacji, użyj symbolu InfoWindow.

Poniższy przykład pokazuje, jak utworzyć dokument InfoWindow i dołączyć go do znacznika pojazdu:

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Wyłącz automatyczne dopasowanie

Możesz zatrzymać 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 dopasowanie podczas konfigurowania widoku mapy udostępnianego przejazdu.

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.   
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Zastępowanie istniejącej mapy

Możesz użyć biblioteki śledzenia przesyłek JavaScript, aby zastąpić istniejącą mapę ze znacznikami lub innymi dostosowaniami bez utraty tych dostosowań.

Załóżmy np., ż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 sekwencji JavaScriptu:

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

Poniższy przykład pokazuje zmiany, które mają zostać wprowadzone:

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

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