Śledź przesyłkę

Po skonfigurowaniu pakietu JavaScript Consumer SDK na potrzeby zaplanowanych zadań możesz śledzić przesyłkę za pomocą aplikacji użytkownika. Ten dokument zawiera te najważniejsze kroki tego procesu:

• Inicjowanie mapy i wyświetlanie udostępnionej podróży
• Aktualizowanie i śledzenie postępów w ramach ścieżki
• Jak przestać obserwować przesyłkę
• Obsługa błędów śledzenia przesyłki

Konfigurowanie mapy

Aby śledzić odbiór lub dostawę przesyłki w aplikacji internetowej, musisz wczytać mapę i utworzyć instancję pakietu Consumer SDK. Możesz wczytać nową mapę lub użyć istniejącej. Następnie użyj funkcji inicjowania, aby utworzyć instancję pakietu Consumer SDK, tak aby widok mapy odpowiadał lokalizacji śledzonego elementu.

Wczytywanie nowej mapy za pomocą interfejsu Google Maps JavaScript API

Aby utworzyć nową mapę, wczytaj interfejs Google Maps JavaScript API w aplikacji internetowej. Przykład poniżej pokazuje, jak wczytać interfejs Google Maps JavaScript API, włączyć pakiet SDK i uruchomić sprawdzanie inicjalizacji.

• Parametr callback uruchamia funkcję initMap po wczytaniu interfejsu API.
• Atrybut defer umożliwia przeglądarce dalsze renderowanie pozostałej części strony podczas wczytywania interfejsu API.

Użyj funkcji initMap, aby utworzyć instancję pakietu SDK dla konsumentów. Na przykład:

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

Wczytywanie istniejącej mapy

Możesz też wczytać istniejącą mapę utworzoną za pomocą interfejsu Google Maps JavaScript API, np. taką, której już używasz.

Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map, na którym wyświetlany jest znacznik zdefiniowany w poniższym kodzie HTML. Poniżej pokazujemy, jak wyświetlić mapę, używając tej samej funkcji initMap w wywołaniu zwrotnym na końcu:

    <!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 Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // 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 Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * 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>

Utworzenie instancji dostawcy lokalizacji przesyłki

Aby zacząć otrzymywać dane z Fleet Engine, użyj dostawcy lokalizacji przesyłki wraz ze zdefiniowanym wcześniej modułem pobierania tokenów autoryzacji.

Te przykłady pokazują, jak utworzyć instancję dostawcy lokalizacji.

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Wyświetlanie udostępnionej podróży

Aby wyświetlić postęp zaplanowanego zadania, zainicjuj jego widok, który ustawia ramkę mapy tak, aby odpowiadała lokalizacji śledzonej podróży. Postęp jest następnie podawany przez pakiet SDK dla klientów po otrzymaniu informacji z Fleet Engine.

Wskazówki:

1. Upewnij się, że strona zawiera element <div>, który zawiera widok mapy. W poniższym przykładzie element <div> ma nazwę map_canvas.

2. Zwróć uwagę na domyślne reguły widoczności, które Fleet Engine stosuje do śledzonych podróży. Możesz też skonfigurować reguły widoczności dla aktywnych zadań dostawy pojazdem i zaplanowanych zadań postoju. Więcej informacji znajdziesz w sekcji Dostosowywanie widoczności zadań w przewodniku Konfigurowanie zadań.

Te przykłady pokazują, jak zainicjować widok mapy.

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts 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);
}

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

Aktualizowanie postępu dostawy

Możesz nasłuchiwać zdarzeń i aktualizować postęp przesyłki w miarę postępu podróży. Użyj dostawcy lokalizacji, aby pobrać metainformacje z obiektu taskTrackingInfo. Zmiany metainformacji wywołują zdarzenie update. Obiekt taskTrackingInfo zawiera te informacje:

• Szacowany czas dotarcia
• Liczba pozostałych przystanków
• odległość pozostałą do pokonania przed odbiorem lub dostawą,

Z poniższego przykładu 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);
});

Wyświetlanie kryteriów wielu zadań

Pakiet Consumer SDK do zaplanowanych zadań wyświetla na mapie tylko 1 zadanie na identyfikator śledzenia. Zwykle jednak przypisujesz też 1 identyfikator śledzenia do konkretnego towaru w dostawie, który pozostaje powiązany z tym towarem przez cały czas jego przemieszczania się w systemie. Oznacza to, że pojedynczy identyfikator śledzenia może być powiązany z wieloma zadaniami, takimi jak zadanie odbioru, po którym następuje zadanie dostawy tej samej paczki, lub wiele nieudanych zadań wysyłki paczki.

Aby poradzić sobie z tą sytuacją, Fleet Engine stosuje kryteria wyświetlania zadań, które są podane w tabeli poniżej.

Jak przestać obserwować przesyłkę

Gdy dostawa zostanie zrealizowana lub anulowana, aplikacja użytkownika powinna przestać śledzić przesyłkę, usuwając identyfikator śledzenia i dostawcę lokalizacji z widoku mapy. Szczegółowe informacje znajdziesz w sekcjach poniżej.

Usuwanie identyfikatora śledzenia

Aby uniemożliwić dostawcy lokalizacji śledzenie przesyłki, usuń identyfikator śledzenia od dostawcy lokalizacji. Poniższe przykłady pokazują, jak to zrobić.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

Usuwanie dostawcy lokalizacji z widoku mapy

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

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

Obsługa błędów śledzenia przesyłki

Błędy, które pojawiają się asynchronicznie podczas żądania informacji o dostawie, wywołują zdarzenia error. Poniższy przykład pokazuje, jak nasłuchiwać tych zdarzeń, aby obsługiwać błędy.

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: pamiętaj, aby wywołania biblioteki umieszczać w blokach try...catch, co pozwoli na obsługę nieoczekiwanych błędów.

Co dalej?

• Zmienianie stylu mapy