Śledź przesyłkę

Po skonfigurowaniu pakietu JavaScript Consumer SDK do zaplanowanych zadań możesz rozpocząć wysyłkę za pomocą aplikacji dla klientów indywidualnych. W tym dokumencie omawiamy: następujące kroki:

  • Zainicjuj mapę i wyświetl udostępnioną podróż
  • Zaktualizuj i śledź postępy podróży
  • Przestań udostępniać trasę
  • Obsługa błędów

Konfigurowanie mapy

Aby śledzić w aplikacji internetowej informacje o odbiorze lub dostawie przesyłki, musisz wczytać mapę i utwórz instancję pakietu Consumer SDK, aby zacząć śledzić przesyłkę. Możesz wczytać użyć nowej lub istniejącej. Następnie należy użyć polecenia inicjowania tworząc instancję pakietu Consumer SDK, tak aby widok mapy odpowiadał lokalizację śledzonego produktu.

Wczytywanie nowej mapy przy użyciu interfejsu Google Maps JavaScript API

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

  • Parametr callback uruchamia funkcję initMap po wczytaniu interfejsu API.
  • Atrybut defer pozwala przeglądarce kontynuować renderowanie pozostałej części 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 Google Maps JavaScript API. takich jak ten, z którego już korzystasz.

Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map jednostka, w której jest wyświetlany znacznik, zgodnie z definicją podaną w poniższym kodzie HTML. Ten pokazuje mapę przy użyciu 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>

Utwórz instancję dostawcy lokalizacji dostawy

Użyj dostawcy miejsca nadania oraz tokenu autoryzacji zdefiniowany wcześniej przez Ciebie moduł pobierania, aby zacząć otrzymywać dane z Fleet Engine.

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świetl udostępnioną podróż

Aby wyświetlić na mapie udostępnioną podróż, musisz zainicjować jej widoku, w którym ramka mapy odpowiada lokalizacji śledzona ścieżka dostarczana przez pakiet SDK Consumer SDK po otrzymaniu informacji z Fleet Engine.

Wskazówki:

  1. Upewnij się, że strona zawiera element &lt;div&gt; z widokiem mapy. W poniższym przykładzie element &lt;div&gt; ma nazwę map_canvas.

  2. Pamiętaj o domyślnych regułach widoczności stosowanych do śledzonych przez Fleet Engine Możesz też skonfigurować reguły widoczności dla aktywnego pojazdu wysyłek i zaplanowanego zatrzymania. Zobacz Dostosowywanie widoczności zadań w Przewodnik konfigurowania zadań.

Te przykłady pokazują, jak inicjować 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);
}

Zaktualizuj postęp dostawy

Możesz nasłuchiwać zdarzeń i aktualizować postęp wysyłki w ramach podróży Twoje postępy. Użyj dostawcy lokalizacji, aby pobrać metadane z taskTrackingInfo obiekt. Zmiany w metatagach informacje wywołują zdarzenie update. Obiekt taskTrackingInfo udostępnia następujące:

  • Szacowany czas zakończenia
  • Liczba pozostałych przystanków
  • Pozostały dystans przed odbiorem lub dostawą

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

Wyświetlanie kryteriów dla wielu zadań

Pakiet Consumer SDK do zaplanowanych zadań pokazuje tylko jedno zadanie na identyfikator śledzenia w mapę. Jednak zwykle przypisujesz jeden identyfikator śledzenia do konkretnego towar wysyłkowy, który pozostaje powiązany z towarem na każdym etapie podróży w Twoim systemie. Oznacza to, że jeden identyfikator śledzenia może być powiązany z wiele zadań, takich jak odbiór, a następnie zadanie dostawy dla tego samego przesyłki lub wiele nieudanych zadań związanych z dostawą przesyłki.

Aby to zrobić, Fleet Engine stosuje kryteria wyświetlania zadań, w poniższej tabeli.

Kryteria zadania Wynik
Otwórz zadania odbioru
Tylko jeden istnieje Pokaż zadanie
Istnieje wiele Błąd generowania
Zamknięte zadania dotyczące odbioru
Tylko jeden istnieje Pokaż zadanie
Istnieje wiele (niektóre z czasem uzyskania wyników) Pokaż zadanie z najnowszym czasem wyniku
Istnieje wiele (brak z czasami wyniku) Błąd generowania
Otwieranie zadań dostarczania
Tylko jeden istnieje Pokaż zadanie
Istnieje wiele Błąd generowania
Zadania z zamkniętym dostarczaniem
Tylko jeden istnieje Pokaż zadanie
Istnieje wiele (niektóre z czasem uzyskania wyników) Pokaż zadanie z najnowszym czasem wyniku
Istnieje wiele (brak z czasami wyniku) Błąd generowania

Rezygnacja z obserwowania przesyłki

Gdy proces dostawy zakończy się lub zostanie anulowany, aplikacja konsumenta powinna aby zakończyć udostępnianie, usuwając identyfikator śledzenia i dostawcę lokalizacji z widoku mapy.

Usuwanie identyfikatora śledzenia

Aby uniemożliwić dostawcy lokalizacji śledzenie przesyłki, usuń identyfikator śledzenia od dostawcy lokalizacji. W przykładach poniżej pokazujemy, jak to zrobić.

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

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

Błędy, które występują asynchronicznie podczas żądania aktywacji informacji o dostawie error. Przykład poniżej pokazuje, jak nasłuchiwać tych zdarzeń 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, aby wywołania biblioteki umieścić w try...catch blokach. aby radzić sobie z nieoczekiwanymi błędami.

Co dalej?