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
- Rezygnacja z obserwowania przesyłki
- Obsługa błędów śledzenia przesyłki
Konfigurowanie mapy
Aby śledzić dostawę lub odbiór przesyłki w aplikacji internetowej, musisz wczytać mapę i utworzyć instancję pakietu Consumer SDK. Pozwoli Ci to śledzić przesyłkę. Możesz wczytać nową mapę lub użyć istniejącej. Następnie za pomocą funkcji inicjowania tworzysz instancję Consumer SDK, aby widok mapy odpowiadał lokalizacji śledzonego produktu.
Wczytywanie nowej mapy za pomocą interfejsu Maps JavaScript API
Aby utworzyć nową mapę, wczytaj w swojej aplikacji internetowej interfejs Google Maps JavaScript API. Z poniższego przykładu dowiesz się, jak wczytać interfejs JavaScript API Map Google, włączyć pakiet SDK i rozpocząć 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ż wczytać istniejącą mapę utworzoną przy użyciu interfejsu Google Maps JavaScript API, np. tę, która jest już używana.
Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map, na którym jest wyświetlany znacznik, zgodnie z definicją w tym kodzie HTML. Wyświetla 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
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, w którym ramka mapy będzie odpowiadała lokalizacji śledzonej podróży. Po otrzymaniu informacji z Fleet Engine pakiet konsumencki SDK przekazuje informacje o postępie.
Wskazówki:
Upewnij się, że strona zawiera element <div> z widokiem mapy. W poniższym przykładzie element <div> ma nazwę
map_canvas.Pamiętaj o domyślnych regułach widoczności, które mają zastosowanie do ś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ły dystans przed odbiorem lub dostawą
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 Consumer SDK do zaplanowanych zadań pokazuje na mapie tylko jedno 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ę.
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 | |
| Tylko jeden istnieje | Wyświetlanie zadania |
| Wiele | Błąd generowania |
| 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 | |
| Tylko jeden istnieje | Wyświetlanie zadania |
| Istnieje wiele (niektóre z czasem trwania) | Pokaż zadanie z najnowszym czasem zakończenia |
| Istnieje wiele (brak wartości czasu wyniku) | Błąd generowania |
Rezygnacja z obserwowania przesyłki
Gdy proces dostawy zakończy się lub zostanie anulowany, aplikacja konsumenta powinna przestać śledzić przesyłkę, usuwając z widoku mapy identyfikator śledzenia i dostawcę lokalizacji. 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. 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);
Postępowanie w przypadku błędów śledzenia przesyłki
Błędy, które występują asynchronicznie podczas żądania informacji o dostawie, wywołują zdarzenia error. Przykład poniżej pokazuje, jak nasłuchiwać 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.