Ś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. Ta biblioteka zawiera komponent mapy JavaScript, który jest zwykłym zamiennikiem standardowej encji google.maps.Map i komponentów danych umożliwiających połączenie z Fleet Engine. Korzystając z biblioteki śledzenia przesyłek JavaScript, możesz zapewnić spersonalizowane, animowane śledzenie przesyłek z poziomu aplikacji internetowej.

Komponenty

Biblioteka śledzenia przesyłek JavaScript udostępnia komponenty do wizualizacji pojazdu i trasy w miarę jego dochodzenia do miejsca docelowego, a także nieprzetworzone pliki danych z szacowanym czasem dotarcia kierowcy lub pozostałą odległością pokonaną przez kierowcę.

Widok mapy śledzenia przesyłki

Komponent Widok 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 dostawy przekazuje informacje o lokalizacji śledzonych obiektów do mapy śledzenia przesyłki, co umożliwia śledzenie przesyłki na pierwszej i ostatniej mili.

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

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

Obiekty ze śledzoną lokalizacją

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 przesyłki jest to lokalizacja planowanego zadania.

Lokalizacja pojazdu

Lokalizacja pojazdu to śledzona lokalizacja pojazdu. Opcjonalnie może obejmować trasę przejazdu pojazdem.

Pobieranie 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 moduł pobierania tokenów uwierzytelniania w ramach swojej aplikacji internetowej, korzystając z biblioteki udostępniania ścieżek JavaScript do uwierzytelniania dostępu do danych o lokalizacji.

Opcje stylu

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

Kontrolowanie widoczności śledzonych lokalizacji

W tej sekcji opisano ustawienia 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 punktu początkowego i docelowego są zawsze wyświetlane na mapie. Przykładowo miejsce dostawy jest zawsze wyświetlane na mapie, niezależnie od stanu dostawy.

Widoczność danych dotyczących zadań

W tej sekcji opisujemy domyślne reguły widoczności, które mają zastosowanie do danych o zadaniach, np. lokalizację pojazdu i pozostałą trasę. Możesz dostosować wiele zadań, ale nie wszystkie:

  • Zadań o niedostępności – nie można dostosować ich widoczności.
  • Aktywne zadania związane z pojazdem – możesz dostosować tego typu zadania.
  • Nieaktywne zadania związane z pojazdem – nie możesz dostosować ich widoczności.

Zadania związane z niedostępnością

Jeśli na trasie do śledzonego zadania istnieje co najmniej 1 zadanie związane z niedostępnością (np. kierowca robi sobie przerwę lub uzupełnia paliwo), pojazd nie będzie widoczny. Szacowany czas przyjazdu i szacowany czas ukończenia zadania są nadal dostępne.

Aktywne zadania związane z pojazdem

Obiekt TaskTrackingInfo zawiera pewną liczbę elementów danych, które mogą być widoczne w bibliotece śledzenia przesyłek. Domyślnie te pola są widoczne, gdy zadanie jest przypisane do pojazdu i gdy pojazd znajduje się w odległości 5 przystanków od zadania. Widoczność kończy się po ukończeniu lub anulowaniu zadania. Pola:

  • Wyznacz linie łamane trasy
  • Szacowany czas do przybycia
  • Szacowany czas ukończenia zadania
  • Pozostała odległość samochodem do zadania
  • Pozostała liczba zatrzymania
  • Lokalizacja pojazdu

Możesz dostosować konfigurację widoczności dla poszczególnych zadań, ustawiając właściwość TaskTrackingViewConfig dla zadania podczas tworzenia lub aktualizowania zadania we Fleet Engine. Powoduje to, że dostępne są poszczególne elementy danych. Mogą się one opierać na tych kryteriach (nazywanych poniżej opcją widoczności):

  • Pozostała liczba zatrzymania
  • Czas do szacowanego czasu przyjazdu
  • Pozostały dystans jazdy
  • Zawsze widoczne
  • Nigdy niewidoczne

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

Oto przykład dostosowania. Oto zasady tego dostosowania:

  • Pokaż linie łamane trasy, jeśli pojazd znajduje się w odległości 3 przystanków.
  • Pokaż szacowany czas dotarcia, jeśli pozostała długość trasy jest krótsza niż 5000 metrów.
  • Nigdy nie pokazuj liczby pozostałych przystanków.
  • Każde pozostałe pole zachowuje domyślną widoczność, czyli wyświetla się, 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.

Zasady dotyczące linii łamanych 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ć wskazana na końcu linii łamanych. Oznacza to, że linie łamane trasy nie mogą mieć mniej restrykcyjnej opcji widoczności.

Aby zapewnić prawidłową kombinację linii łamanych trasy i widoczności lokalizacji pojazdu, należy przestrzegać tych reguł:

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

    • Jeśli opcja widoczności to pozostała liczba przystanków, czas podróży do szacowanego czasu dotarcia na miejsce albo pozostały czas jazdy, linie łamane trasy muszą podawać wartość mniejszą lub równą wartości ustawionej dla tej opcji widoczności dla lokalizacji pojazdu. Przykład:
    "taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
    • Jeśli linie łamane trasy mają opcję Zawsze widoczną widoczność, lokalizacja pojazdu musi też zapewniać opcję zawsze widocznej widoczności.
    • Jeśli w przypadku lokalizacji pojazdu opcja widoczności jest „Nigdy niewidoczna”, linie łamane trasy muszą też zapewniać opcję widoczności „Nigdy nie widać”.

  • Gdy linie łamane trasy i lokalizacja pojazdu mają różne typy opcji widoczności, lokalizacja pojazdu jest widoczna tylko wtedy, gdy są spełnione oba te opcje.

    Przykład:

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

    W tym przykładzie lokalizacja pojazdu jest widoczna tylko wtedy, gdy pozostała liczba przystanków wynosi co najmniej 3 ORAZ pozostała odległość jazdy wynosi co najmniej 3000 metrów.

Pierwsze kroki z biblioteką udostępniania ścieżek JavaScript

Zanim zaczniesz korzystać z biblioteki udostępniania czynności JavaScript, upewnij się, że znasz Fleet Engine i uzyskasz klucz interfejsu API.

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

Tworzenie roszczenia dotyczącego identyfikatora śledzenia

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

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

Poniższy przykład pokazuje, 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 pobierać na Twoje serwery token z odpowiednimi deklaracjami za pomocą certyfikatu konta usługi w projekcie. Ważne jest, aby generować tokeny wyłącznie na serwerach i nigdy nie udostępniać certyfikatów klientom. W przeciwnym razie nagrasz zagrożenie dla bezpieczeństwa systemu.

Moduł pobierania musi zwrócić strukturę danych z 2 polami umieszczonymi w obiekcie Promise:

  • Ciąg 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 jest spełniony dowolny z tych warunków:

  • Nie ma prawidłowego tokena, na przykład jeśli nie wywołał modułu pobierania przy nowym wczytaniu strony lub wtedy, gdy moduł pobierania nie zwrócił się z tokenem.
  • Pobrany wcześniej token wygasł.
  • Wygenerowany wcześniej token straci ważność w ciągu minuty.

W przeciwnym razie biblioteka używa wydanego wcześniej, wciąż ważnego tokena i nie wywołuje modułu pobierania.

Poniższy przykład pokazuje, 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 uwagach:

  • Punkt końcowy musi zwracać czas wygaśnięcia tokena. W przykładzie powyżej jest to data.ExpiresInSeconds.
  • Moduł pobierania tokenów uwierzytelniania musi przekazać do biblioteki czas wygaśnięcia (w sekundach, od czasu pobrania), jak pokazano w przykładzie.
  • Adres SERVER_TOKEN_URL zależy od implementacji backendu. Oto adresy URL 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

Ten przykład pokazuje, jak wczytać bibliotekę śledzenia przesyłki JavaScript z określonego adresu URL. Parametr callback wykonuje funkcję initMap po wczytaniu interfejsu API. Atrybut defer pozwala przeglądarce kontynuować renderowanie 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 śledzić odbiór lub dostawę przesyłki za pomocą biblioteki śledzenia przesyłki JavaScript. Pamiętaj, aby przed uruchomieniem kodu załadować bibliotekę z funkcji wywołania zwrotnego określonej w tagu skryptu.

Utwórz instancję dostawcy lokalizacji dostawy

Biblioteka śledzenia przesyłek JavaScript wstępnie definiuje dostawcę lokalizacji dla interfejsuFleet Engine Deliveries API. Utwórz instancję, używając identyfikatora projektu i odwołania 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 załadowaniu biblioteki JavaScript Journey Share 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 dla 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'), 
  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);

Identyfikator śledzenia

Identyfikator śledzenia przekazany dostawcy lokalizacji może odpowiadać kilku działaniom, np. odbiórowi i dostarczeniu tej samej przesyłki lub kilku nieudanych próbom jej doręczenia. Wybrano jedno zadanie, które ma być wyświetlane na mapie śledzenia przesyłki. Zadanie do wyświetlenia jest określone w ten sposób:

  1. Jeśli jest tylko jedno otwarte zadanie odbioru, zostanie ono wyświetlone. Jeśli będzie kilka otwartych zadań odbioru, pojawi się błąd.
  2. Jeśli istnieje dokładnie 1 otwarte zadanie dostarczania, zostanie ono wyświetlone. W przypadku kilku otwartych zadań dostarczania pojawia się błąd.
  3. Jeśli masz zadania dostawy zamkniętego:
    • Jeśli istnieje dokładnie 1 zamknięte zadanie dostarczania, jest ono wyświetlane.
    • Jeśli jest wiele zadań dostarczania zamkniętego, wyświetlane jest to o najnowszym czasie zakończenia.
    • Jeśli istnieje wiele zadań dostawy zamkniętego, z których żadne nie ma wyznaczonego czasu wyniku, wystąpi błąd.
  4. Jeśli masz zamknięte zadania dotyczące odbioru:
    • Jeśli istnieje dokładnie 1 zamknięte zadanie odbioru, jest ono wyświetlane.
    • Jeśli masz kilka zamkniętych zadań odbioru, wyświetli się to o najnowszym czasie realizacji.
    • Jeśli istnieje wiele zamkniętych zadań odbioru, z których żadne nie ma określonego czasu wykonania, pojawi się błąd.
  5. W przeciwnym razie zadanie nie jest wyświetlane.

Nasłuchuj zdarzeń zmian

Możesz pobrać metainformacje o zadaniu z obiektu informacji o śledzeniu zadań, korzystając z dostawcy lokalizacji. Metadane obejmują szacowany czas dotarcia na miejsce, liczbę pozostałych przystanków oraz odległość, która pozostała przed odbiorem lub dostawą. Zmiany metainformacji wywołują zdarzenie update. Z przykładu poniżej dowiesz się, jak nasłuchiwać zdarzeń zmian.

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

Obsługa błędów

Błędy, które występują asynchronicznie podczas żądania informacji o dostawie, wywołują zdarzenia error. 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: aby obsługiwać nieprzewidziane błędy, pamiętaj o opakowaniu wywołań biblioteki w bloki try...catch.

Zakończ śledzenie

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Usuń dostawcę lokalizacji z widoku mapy

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Dostosuj wygląd i styl mapy podstawowej

Aby dostosować wygląd i styl mapy, określ styl mapy, korzystając z narzędzi działających w chmurze lub ustawiając opcje bezpośrednio w kodzie.

Używaj stylu mapy w chmurze

Definiowanie stylów map w Google Cloud pozwala tworzyć i edytować style map dla dowolnych aplikacji korzystających z Map Google, korzystając z 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łki JavaScript, podczas tworzenia elementu 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.

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

Używaj stylu mapy opartego na kodzie

Innym sposobem dostosowania stylu mapy jest ustawienie mapOptions podczas tworzenia elementu 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" }
        ]
      }
    ]
  }
});

Dostosowywanie znaczników

Za pomocą biblioteki śledzenia przesyłek JavaScript możesz dostosować wygląd i sposób działania znaczników dodawanych do mapy. Aby to zrobić, określ dostosowania znaczników, które biblioteka śledzenia przesyłek stosuje przed dodaniem znaczników do mapy i po każdej aktualizacji tych znaczników.

Najprostsze dostosowanie to określenie obiektu MarkerOptions, który będzie stosowany 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 pozwalają na określanie stylu znaczników na podstawie danych oraz dodawanie do znaczników interaktywnych elementów, np. obsługi kliknięć. W szczególności śledzenie przesyłki przekazuje do funkcji dostosowywania dane dotyczące typu obiektu reprezentowanego przez znacznik: pojazdu lub miejsca docelowego. Dzięki temu styl znacznika może się zmieniać odpowiednio do bieżącego stanu samego elementu znacznika, np. do liczby zaplanowanych przystanków do momentu dotarcia do miejsca docelowego. Możesz nawet złączać dane ze źródeł spoza Fleet Engine i zmieniać styl znacznika na podstawie tych informacji.

Biblioteka śledzenia dostawy zawiera w FleetEngineShipmentLocationProviderOptions te parametry dostosowania:

Zmień styl znaczników za pomocą atrybutu MarkerOptions

Poniższy przykład pokazuje, jak skonfigurować styl znacznika pojazdu za pomocą obiektu MarkerOptions. Postępuj zgodnie z tym wzorcem, aby dostosować styl dowolnego znacznika za pomocą dowolnych z powyższych ustawień.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Zmienianie stylu znaczników za pomocą funkcji dostosowywania

Przykład poniżej pokazuje, jak skonfigurować styl znacznika pojazdu. Postępuj zgodnie z tym wzorcem, aby dostosować styl dowolnego znacznika za pomocą dowolnych parametrów dostosowywania 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. Postępuj zgodnie z tym wzorcem, aby dodać obsługę kliknięć do dowolnego znacznika za pomocą dowolnego z wymienionych wyżej parametrów dostosowywania znaczników.

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

Dostosowywanie linii łamanej

Za pomocą biblioteki ś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 na aktywnej lub pozostałej ścieżce przesyłki. Możesz stylizować obiekty Polyline, określając niestandardowe ustawienia linii łamanej. Następnie biblioteka stosuje te dostosowania w 2 sytuacjach: przed dodaniem obiektów do mapy i gdy dane używane przez te obiekty ulegną zmianie.

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

Możesz również określić funkcję dostosowywania. Funkcje dostosowywania pozwalają na określanie indywidualnego stylu obiektów na podstawie danych przesłanych przez Fleet Engine. Ta funkcja może zmieniać styl każdego obiektu w zależności od bieżącego stanu przesyłki. Na przykład kolorowanie obiektu Polyline ma głębszy odcień lub zwiększenie jego grubości, gdy pojazd porusza się wolniej. Możesz nawet złączać dane ze źródeł spoza Fleet Engine i określać styl obiektu Polyline na podstawie tych informacji.

Możesz określić dostosowania za pomocą parametrów podanych w zadaniu FleetEngineShipmentLocationProviderOptions. Możesz ustawić dostosowania dla różnych stanów trasy na trasie pojazdu – już przebyty, aktywnie podróżujący lub jeszcze nie pokonany. Parametry są następujące:

Zmień styl Polyline obiektów za pomocą PolylineOptions

Poniższy przykład pokazuje, jak skonfigurować styl obiektu Polyline za pomocą PolylineOptions. Postępuj zgodnie z tym wzorcem, aby dostosować styl dowolnego obiektu Polyline za pomocą wymienionych wcześniej dostosowań linii łamanych.

JavaScript

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

TypeScript

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

Zmień styl Polyline obiektu za pomocą funkcji dostosowywania

Poniższy przykład pokazuje, jak skonfigurować styl aktywnego obiektu Polyline. Postępuj zgodnie z tym wzorcem, aby dostosować styl dowolnego obiektu Polyline za pomocą wymienionych wcześniej parametrów dostosowywania linii łamanych.

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

Kontroluj widoczność obiektów Polyline

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

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Aby wyświetlać InfoWindow obok pojazdu lub znacznika lokalizacji

Aby wyświetlić dodatkowe informacje o pojeździe lub znaczniku lokalizacji, możesz użyć znaku InfoWindow.

Poniższy przykład pokazuje, jak utworzyć obiekt InfoWindow i dołączyć 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 dopasowywanie widocznego obszaru do pojazdu i przewidywanej trasy na mapie. W tym celu wyłącz automatyczne dopasowanie. Z przykładu poniżej dowiesz się, jak wyłączyć automatyczne dopasowanie podczas konfigurowania widoku mapy udostępniania podróży.

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

Zastępowanie istniejącej mapy

Za pomocą biblioteki śledzenia dostawy JavaScript możesz zastąpić istniejącą mapę, która zawiera znaczniki i inne dostosowania, bez utraty tych dostosowań.

Załóżmy np., że masz stronę internetową ze standardowym elementem google.maps.Map, na którym jest wyświetlany 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ę do udostępniania czynności JavaScript:

  1. Dodaj kod fabryki tokenów uwierzytelniania.
  2. Zainicjuj dostawcę lokalizacji w funkcji initMap().
  3. Zainicjuj widok mapy w funkcji initMap(). Widok zawiera mapę.
  4. Przenieś dostosowanie do funkcji wywołania zwrotnego na potrzeby zainicjowania widoku mapy.
  5. Dodaj bibliotekę lokalizacji do wczytywania interfejsu API.

Poniższy przykład pokazuje zmiany, które należy wprowadzić:

<!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 wyrenderowana na mapie.