Podczas śledzenia przejazdu aplikacja dla klienta wyświetla mu lokalizację odpowiedniego pojazdu. Aby to zrobić, aplikacja musi zacząć śledzić podróż, zaktualizować jej postęp i przestać śledzić ją, gdy się zakończy.
W tym dokumencie opisujemy najważniejsze kroki tego procesu:
- Konfigurowanie mapy
- Inicjalizacja mapy i wyświetlenie udostępnionej trasy
- Aktualizowanie i śledzenie postępów podróży
- Przestań obserwować podróż
- Obsługa błędów dotyczących podróży
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 trasy. Możesz załadować 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 przy użyciu interfejsu Google 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. 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>
Zastępowanie istniejącej mapy
Możesz zastąpić dotychczasową mapę zawierającą znaczniki lub inne elementy niestandardowe, nie tracąc tych elementów.
Jeśli np. masz stronę internetową ze standardowym elementem google.maps.Map, na którym wyświetlany jest znacznik, możesz zastąpić mapę, zachowując ten znacznik. W tej sekcji znajdziesz instrukcje, jak to zrobić.
Aby zastąpić mapę i zachować modyfikacje, dodaj do strony HTML udostępnianie ścieżek, wykonując te czynności (również ponumerowane w podanym niżej przykładzie):
Dodaj kod fabryki tokenów uwierzytelniających.
Inicjuj dostawcę lokalizacji w funkcji
initMap().Zainicjuj widok mapy w funkcji
initMap(). Widok zawiera mapę.Przenieś dostosowanie do funkcji wywołania zwrotnego na potrzeby inicjowania widoku mapy.
Dodaj bibliotekę lokalizacji do programu ładowania interfejsu API.
Przykład poniżej pokazuje, jakie zmiany należy wprowadzić. Jeśli podróżujesz z podanym identyfikatorem w pobliżu Uluru, teraz wyświetli się na mapie:
<!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>
let locationProvider;
// (1) Authentication Token Fetcher
async function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
// Initialize and add the map
function initMap() {
// (2) Initialize location provider.
locationProvider = new google.maps.journeySharing.FleetEngineTripLocationProvider({
projectId: "YOUR_PROVIDER_ID",
authTokenFetcher,
});
// (3) Initialize map view (which contains the map).
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map'),
locationProviders: [locationProvider],
// any styling options
});
locationProvider.tripId = TRIP_ID;
// (4) Add customizations like before.
// 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 async attribute allows the browser to render the page while the API loads
* The key parameter will contain your own API key (which is not needed for this tutorial)
* The callback parameter executes the initMap() function
*
* (5) Add the SDK to the API loader.
-->
<script defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
</script>
</body>
</html>
Inicjalizacja mapy i wyświetlanie postępu podróży
Gdy podróż się rozpoczyna, aplikacja musi utworzyć instancję dostawcy lokalizacji dla podróży, a następnie zainicjować mapę, aby zacząć udostępniać postępy w podróży. Przykłady znajdziesz w sekcjach poniżej.
Tworzenie wystąpienia dostawcy lokalizacji podróży
Pakiet SDK JavaScript ma wstępnie zdefiniowany dostawca lokalizacji dla interfejsu API Ridesharing Fleet Engine. Aby utworzyć instancję fabryki tokenów, użyj identyfikatora projektu i odwołania do niej.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineTripLocationProvider({
projectId: 'your-project-id',
authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step
// Optionally, you may specify a trip ID to
// immediately start tracking.
tripId: 'your-trip-id',
});
Inicjowanie widoku mapy
Po załadowaniu pakietu SDK JavaScript zainicjuj
widok mapy i dodaj go do strony HTML. Strona powinna zawierać element <div> z widokiem mapy. W przykładzie poniżej element <div> ma nazwę map_canvas.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);
Zaktualizuj i śledź postępy w podróży
Aplikacja powinna nasłuchiwać zdarzeń i aktualizować postęp podróży w miarę jej postępów. Możesz pobrać metadane o podróży z obiektu zadania, korzystając z dostawcy lokalizacji. Metadane obejmują szacowany czas dotarcia na miejsce i pozostałą odległość przed odebraniem lub dostarczeniem. Zmiany metadanych wywołują zdarzenie update. Przykład poniżej pokazuje, jak nasłuchiwać zdarzeń zmian.
JavaScript
locationProvider.addListener('update', e => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
TypeScript
locationProvider.addListener('update', (e:
google.maps.journeySharing.FleetEngineTripLocationProviderUpdateEvent) => {
// e.trip contains data that may be useful
// to the rest of the UI.
console.log(e.trip.dropOffTime);
});
Przestań obserwować podróż
Po zakończeniu podróży musisz zatrzymać śledzenie przez dostawcę lokalizacji. Aby to zrobić, usuń identyfikator i dostawcę lokalizacji. Przykłady znajdziesz w sekcjach poniżej.
Usuwanie identyfikatora podróży z dostawcy danych o lokalizacji
Ten przykład pokazuje, jak usunąć identyfikator podróży od dostawcy lokalizacji.
JavaScript
locationProvider.tripId = '';
TypeScript
locationProvider.tripId = '';
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 związanych z podróżą
Błędy, które występują asynchronicznie podczas wysyłania żądania informacji o podróży, powodują wystąpienie zdarzeń błędu. Przykład poniżej pokazuje, jak nasłuchiwać zdarzeń w celu obsługi błędów.
JavaScript
locationProvider.addListener('error', e => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});
TypeScript
locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
// e.error contains the error that triggered the
// event
console.error(e.error);
});