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 wystąpienie pakietu Consumer SDK, aby widok mapy odpowiadał lokalizacji śledzonego produktu.
Wczytywanie nowej mapy za pomocą interfejsu Maps JavaScript API
Aby utworzyć nową mapę, załaduj interfejs Google Maps JavaScript API w swojej aplikacji internetowej. W tym przykładzie pokazujemy, jak załadować interfejs Google Maps JavaScript API, włączyć pakiet SDK i uruchomić 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ć mapę utworzoną za pomocą interfejsu Maps JavaScript API, na przykład taką, której używasz.
Załóżmy na przykład, że masz stronę internetową ze standardowym elementem google.maps.Map, na którym wyświetla się znacznik zgodnie z definicją 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 wraz z określonym wcześniej odbiornikiem tokenu 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 wspólnej trasy
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 Consumer SDK przekazuje informacje o postępie.
Wskazówki:
Upewnij się, że strona zawiera 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 zatrzymaniem. Więcej informacji o dostosowywaniu widoczności zadań znajdziesz w poradnikach Konfigurowanie 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 trakcie podróży. 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 w przypadku 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 przesyłce, 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 tego samego pakietu, lub z wieloma zadaniami wysyłki, które nie powiodły się w przypadku danego pakietu.
Aby sobie z tym poradzić, mechanizm floty stosuje kryteria wyświetlania zadań, które znajdziesz w tabeli poniżej.
.| Kryteria zadania | Wynik |
|---|---|
| Otwarte zadania dotyczące odbioru | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele | Generowanie błędu |
| Zamknięte zadania dotyczące odbioru | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele (niektóre z czasem trwania) | Wyświetlanie zadania z najnowszym czasem zakończenia |
| Istnieje wiele (brak wartości z czasem wyniku) | Generowanie błędu |
| Otwieranie zadań związanych z dostarczaniem | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele | Generowanie błędu |
| Zamknięte zadania dotyczące dostawy | |
| istnieje dokładnie jeden, | Wyświetlanie zadania |
| Wiele (niektóre z czasem trwania) | Wyświetlanie zadania z najnowszym czasem zakończenia |
| Istnieje wiele (brak wartości z czasem wyniku) | Generowanie błędu |
Przerwanie śledzenia przesyłki
Gdy proces dostawy zostanie zakończony lub anulowany, 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 z ustawienia dostawcy lokalizacji. Poniżej znajdziesz 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 występują asynchronicznie z powodu żądania informacji o przesyłce, powodują zdarzenia error. W tym przykładzie pokazujemy, 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łużyć nieoczekiwane błędy, zwróć uwagę, aby otaczać wywołania biblioteki blokami try...catch.