Follow a shipment

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 callback parameter runs the initMap function after the API loads.
  • The defer attribute 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:

  1. Ensure your page contains a <div> element that holds the map view. In the following example, the <div> element is named map_canvas.

  2. 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.

What's next