Now that you've set up the JavaScript Consumer SDK for scheduled tasks, you're ready to follow a shipment with your consumer app. This document covers the following key steps in this process:
- Initialize a map and display the shared journey
- Update and follow journey progress
- Stop following a shipment
- Handle shipment tracking errors
Set up a map
To follow a shipment pickup or delivery in your web app, you need to load a map and instantiate the Consumer SDK to start tracking your shipment. You can load either a new map or use an existing one. You then use the initialization function to instantiate the Consumer SDK so that the map view corresponds to the location of the item being tracked.
Load a new map using the Google Maps JavaScript API
To create a new map, load the Google Maps JavaScript API in your web app. The following example shows how to load the Google Maps JavaScript API, enable the SDK, and trigger the initialization check.
- The
callbackparameter runs theinitMapfunction after the API loads. - The
deferattribute lets the browser continue rendering the rest of your page while the API loads.
Use the initMap function to instantiate the Consumer SDK. For example:
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>
Load an existing map
You can also load an existing map created by the Google Maps JavaScript API, such as one you have already in use.
For example, suppose you have a web page with a standard google.maps.Map
entity on which a marker is shown as defined in the following HTML code. This
shows your map using the same initMap function in the callback at the end:
<!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>
Instantiate a shipment location provider
Use the shipment location provider, together with the authorization token fetcher you defined previously, to start receiving data from Fleet Engine.
These examples show how to instantiate the location provider.
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
});
Display the shared journey
To display the progress of a scheduled task, initialize its view, which sets the frame for the map to correspond to the location for tracked journey. The progress is then provided by the Consumer SDK after it gets the information from Fleet Engine.
Tips:
Ensure your page contains a <div> element that holds the map view. In the following example, the <div> element is named
map_canvas.Be aware of the default visibility rules Fleet Engine applies to tracked journeys. You can also configure visibility rules for active vehicle shipment and scheduled stop tasks. See Customize task visibility in the Configure tasks guide.
These examples show how to initialize a map view.
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);
}
Update shipment progress
You can listen for events and update the shipment progress as a journey
progresses. Use the location provider to retrieve meta information from the
taskTrackingInfo object. Changes to the meta
information trigger an update event. The taskTrackingInfo object provides
the following:
- ETA
- Number of remaining stops
- Remaining distance before pickup or delivery
The following example shows how to listen to these change events.
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);
});
Display criteria for multiple tasks
The Consumer SDK for scheduled tasks shows only one task per tracking ID on the map. However, you also typically assign one tracking ID to a specific shipment good that remains associated with the good throughout its journey in your system. This means that a single tracking ID might be associated with multiple tasks, such as a pickup task followed by a delivery task for the same package, or multiple failed shipment tasks for a package.
To handle this situation, Fleet Engine applies criteria for displaying tasks, shown in the following table.
| Task criteria | Result |
|---|---|
| Open pickup tasks | |
| Exactly one exists | Show the task |
| Multiple exist | Generate error |
| Closed pickup tasks | |
| Exactly one exists | Show the task |
| Multiple exist (some with outcome times) | Show task with most recent outcome time |
| Multiple exist (none with outcome times) | Generate error |
| Open delivery tasks | |
| Exactly one exists | Show the task |
| Multiple exist | Generate error |
| Closed delivery tasks | |
| Exactly one exists | Show the task |
| Multiple exist (some with outcome times) | Show task with most recent outcome time |
| Multiple exist (none with outcome times) | Generate error |
Stop following a shipment
When a shipment journey completes or is cancelled, your consumer app should stop following a shipment by removing the tracking ID and the location provider from the map view. For details, see the following sections.
Remove the tracking ID
To stop the location provider from tracking the shipment, remove the tracking ID from the location provider. The following examples show how to do this.
JavaScript
locationProvider.trackingId = '';
TypeScript
locationProvider.trackingId = '';
Remove the location provider from the map view
The following example shows how to remove a location provider from the map view.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Handle shipment tracking errors
Errors that arise asynchronously from requesting shipment information trigger error events. The following example shows how to listen for these events to handle errors.
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);
});
Note: Make sure to wrap library calls in try...catch blocks
to handle unanticipated errors.