Śledź przesyłkę

Po skonfigurowaniu pakietu JavaScript Consumer SDK do obsługi zaplanowanych zadań możesz śledzić dostawę za pomocą aplikacji dla konsumentów. Ten dokument zawiera informacje o tych kluczowych krokach:

  • Inicjowanie mapy i wyświetlanie wspólnej podróży
  • Aktualizowanie i śledzenie postępów podróży
  • Przestawanie śledzenia dostawy
  • Obsługa błędów śledzenia dostawy

Konfigurowanie mapy

Aby śledzić odbiór lub dostawę w aplikacji internetowej, musisz wczytać mapę i utworzyć instancję pakietu Consumer SDK, aby rozpocząć śledzenie dostawy. 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 Maps JavaScript API

Aby utworzyć nową mapę, wczytaj interfejs Maps JavaScript API w aplikacji internetowej. Poniższy przykład pokazuje, jak wczytać interfejs Maps JavaScript API, włączyć pakiet SDK i uruchomić sprawdzanie inicjowania.

  • 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 Consumer SDK. 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 Maps JavaScript API, np. mapę, której już używasz.

Załóżmy na przykład, że masz stronę internetową ze standardową encją google.maps.Map, na której wyświetla się znacznik zdefiniowany w tym kodzie HTML. Mapa jest wyświetlana za pomocą 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>

Tworzenie instancji dostawcy lokalizacji dostawy

Aby zacząć otrzymywać dane z Fleet Engine, użyj dostawcy lokalizacji dostawy wraz z pobieraniem tokena autoryzacji zdefiniowanym wcześniej.

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

JavaScript

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

TypeScript

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

Wyświetlanie wspólnej 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 udostępniany przez pakiet Consumer SDK po uzyskaniu informacji z Fleet Engine.

Wskazówki:

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

  2. Pamiętaj o domyślnych regułach widoczności, które Fleet Engine stosuje do śledzonych podróży. Możesz też skonfigurować reguły widoczności dla aktywnych zadań dostawy pojazdu i zaplanowanych przystanków. Więcej informacji znajdziesz w przewodniku Konfigurowanie zadań w sekcji Dostosowywanie widoczności zadań.

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

JavaScript

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

TypeScript

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ępów dostawy

Możesz nasłuchiwać zdarzeń i aktualizować postępy dostawy w miarę postępów podróży. Użyj dostawcy lokalizacji, aby pobrać metadane z obiektu taskTrackingInfo. Zmiany metadanych powodują wywołanie zdarzenia update. Obiekt taskTrackingInfo zawiera te informacje:

  • Szacowany czas dotarcia
  • Liczba pozostałych przystanków
  • Pozostała odległość do odbioru lub dostawy

Ten przykład pokazuje, jak nasłuchiwać tych zdarzeń zmiany.

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

Kryteria wyświetlania wielu zadań

Pakiet Consumer SDK do obsługi zaplanowanych zadań wyświetla na mapie tylko 1 zadanie na identyfikator śledzenia. Zazwyczaj jednak przypisujesz 1 identyfikator śledzenia do konkretnego towaru, który pozostaje z nim powiązany przez cały czas podróży w Twoim systemie. Oznacza to, że 1 identyfikator śledzenia może być powiązany z kilkoma zadaniami, np. z zadaniem odbioru, a następnie z zadaniem dostawy tej samej paczki lub z kilkoma nieudanymi zadaniami dostawy paczki.

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

Kryteria zadania Wynik
Otwarte zadania odbioru
Istnieje dokładnie 1 Wyświetl zadanie
Istnieje kilka Wygeneruj błąd
Zamknięte zadania odbioru
Istnieje dokładnie 1 Wyświetl zadanie
Istnieje kilka (niektóre z czasem zakończenia) Wyświetl zadanie z najnowszym czasem zakończenia
Istnieje kilka (żadne nie mają czasu zakończenia) Wygeneruj błąd
Otwarte zadania dostawy
Istnieje dokładnie 1 Wyświetl zadanie
Istnieje kilka Wygeneruj błąd
Zamknięte zadania dostawy
Istnieje dokładnie 1 Wyświetl zadanie
Istnieje kilka (niektóre z czasem zakończenia) Wyświetl zadanie z najnowszym czasem zakończenia
Istnieje kilka (żadne nie mają czasu zakończenia) Wygeneruj błąd

Przestawanie śledzenia dostawy

Gdy podróż dostawy się zakończy lub zostanie anulowana, aplikacja dla konsumentów powinna przestać śledzić dostawę, usuwając identyfikator śledzenia i dostawcę lokalizacji z widoku mapy. Szczegółowe informacje znajdziesz w sekcjach poniżej.

Usuwanie identyfikatora śledzenia

Aby dostawca lokalizacji przestał śledzić dostawę, usuń identyfikator śledzenia z dostawcy lokalizacji. Poniższe przykłady pokazują, jak to zrobić.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Usuwanie dostawcy lokalizacji z widoku mapy

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Obsługa błędów śledzenia dostawy

Błędy, które występują asynchronicznie podczas wysyłania prośby o informacje o dostawie, powodują wywołanie zdarzeń error. Ten przykład pokazuje, jak nasłuchiwać tych zdarzeń, aby obsługiwać błędy.

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ć nieoczekiwane błędy, pamiętaj, aby wywołania biblioteki umieszczać w blokach try...catch.

Co dalej?