Po skonfigurowaniu pakietu SDK JavaScript dla konsumentów na potrzeby zaplanowanych zadań możesz śledzić dostawę za pomocą aplikacji dla konsumentów. W tym dokumencie znajdziesz te kluczowe kroki:
- Inicjalizacja mapy i wyświetlenie udostępnionej trasy
- Aktualizowanie i śledzenie postępów podróży
- Przerwanie śledzenia przesyłki
- 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, aby rozpocząć śledzenie przesyłki. Możesz załadować nową mapę lub użyć istniejącej. Następnie za pomocą funkcji inicjowania tworzysz instancję pakietu Consumer SDK, aby widok mapy odpowiadał lokalizacji śledzonego produktu.
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 wywołać sprawdzanie inicjalizacji.
- Parametr
callbackuruchamia funkcjęinitMappo załadowaniu interfejsu API. - Atrybut
deferpozwala przeglądarce kontynuować renderowanie reszty strony podczas wczytywania interfejsu API.
Aby utworzyć instancję Consumer SDK, użyj funkcji initMap. 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ż załadować mapę utworzoną za pomocą interfejsu Maps JavaScript API, na przykład taką, której używasz już w swojej aplikacji.
Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map, na którym wyświetla się znacznik zdefiniowany w tym kodzie HTML. Pokazuje to mapę, która korzysta z 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 wystąpienia dostawcy lokalizacji przesyłki
Aby zacząć otrzymywać dane z Fleet Engine, użyj dostawcy lokalizacji przesyłki oraz wcześniej zdefiniowanego przez siebie pobierającego token autoryzacji.
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 udostępnionej podróży
Aby wyświetlić postęp zaplanowanego zadania, zainicjuj jego widok, który ustawia ramkę mapy tak, aby odpowiadała ona lokalizacji śledzonej podróży. Po otrzymaniu informacji z Fleet Engine pakiet konsumencki SDK przekazuje informacje o postępie.
Wskazówki:
Upewnij się, że na stronie znajduje się element <div>, który zawiera widok mapy. W tym przykładzie element <div> ma nazwę
map_canvas.Zapoznaj się z domyślnymi regułami widoczności stosowanymi przez Fleet Engine w przypadku śledzonych podróży. Możesz też skonfigurować reguły widoczności dla zadań związanych z aktywną przesyłką i zaplanowanymi przystankami. W przewodniku Konfigurowanie zadań zapoznaj się z sekcją 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ępu dostawy
Możesz nasłuchiwać zdarzeń i aktualizować postęp dostawy w miarę jej trwania. Użyj dostawcy lokalizacji, aby pobrać metadane z obiektu taskTrackingInfo. Zmiany w metainformacjach powodują zdarzenie update. Obiekt taskTrackingInfo zawiera:
- Szacowany czas zakończenia
- Liczba pozostałych przystanków
- Pozostała odległość do odbioru lub dostawy
W tym przykładzie pokazujemy, jak odbierać te zdarzenia 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);
});
Wyświetlanie kryteriów dla wielu zadań
Pakiet SDK dla konsumentów przeznaczony do zaplanowanych zadań wyświetla na mapie tylko 1 zadanie na identyfikator śledzenia. Zwykle przypisujesz też jeden identyfikator śledzenia do konkretnego produktu w dostawie, który pozostaje powiązany z produktem przez cały czas jego podróży w Twoim systemie. Oznacza to, że jeden identyfikator śledzenia może być powiązany z wieloma zadaniami, takimi jak zadanie odbioru, po którym następuje zadanie dostawy tej samej przesyłki, lub z wieloma zadaniami dostawy, które nie powiodły się w przypadku danej przesyłki.
Aby sobie z tym poradzić, Fleet Engine stosuje kryteria wyświetlania zadań, które znajdziesz w tabeli poniżej.
| Kryteria zadania | Wynik |
|---|---|
| Otwieranie zadań odbioru | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele | Wygeneruj błąd |
| Zamknięte zadania dotyczące odbioru | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Istnieje wiele (niektóre z czasem trwania) | Pokaż zadanie z najnowszym czasem zakończenia |
| Istnieje wiele (brak wartości czasu wyniku) | Wygeneruj błąd |
| Otwieranie zadań związanych z dostarczaniem | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele | Wygeneruj błąd |
| Zadania dotyczące zakończonych dostaw | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Istnieje wiele (niektóre z czasem trwania) | Pokaż zadanie z najnowszym czasem zakończenia |
| Istnieje wiele (brak wartości czasu wyniku) | Wygeneruj błąd |
Przerwanie śledzenia przesyłki
Gdy dostawa zostanie zakończona lub anulowana, aplikacja dla konsumentów 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 zatrzymać śledzenie przesyłki przez dostawcę lokalizacji, usuń identyfikator śledzenia od dostawcy lokalizacji. Poniżej podajemy przykłady, 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 przesyłki
Błędy, które pojawiają się asynchronicznie z powodu żądania informacji o przesyłce, powodują zdarzenia błędu. Przykład poniżej pokazuje, jak odbierać te zdarzenia, 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łużyć nieoczekiwane błędy, zwróć uwagę, aby otaczać wywołania biblioteki blokami try...catch.