此页面由 Cloud Translation API 翻译。

跟随运单

现在，您已为安排的任务设置了 JavaScript 消费者 SDK，接下来就可以使用消费者应用跟踪配送。本文档将介绍此过程中的以下关键步骤：

初始化地图并显示共享的行程
更新和跟踪历程进度
停止关注运单
处理物流跟踪错误

设置地图

如需在 Web 应用中跟踪货物自提或送货，您需要加载地图并实例化消费者 SDK，以开始跟踪物流信息。您可以加载新地图，也可以使用现有地图。然后，您可以使用初始化函数实例化 Consumer SDK，以便地图视图与被跟踪项的位置相对应。

使用 Google Maps JavaScript API 加载新地图

如需创建新地图，请在您的 Web 应用中加载 Google Maps JavaScript API。以下示例展示了如何加载 Google Maps JavaScript API、启用 SDK 并触发初始化检查。

callback 参数会在 API 加载后运行 initMap 函数。
defer 属性允许浏览器在 API 加载的同时继续渲染网页的其余部分。

使用 initMap 函数实例化 Consumer SDK。例如：

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

加载现有地图

您还可以加载 Google Maps JavaScript API 创建的现有地图，例如您已经在使用的地图。

例如，假设您有一个网页包含标准 google.maps.Map 实体，且在该实体上，标记按照以下 HTML 代码中的定义进行了显示。这会在末尾的回调中使用相同的 initMap 函数来显示您的地图：

    <!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>

实例化配送位置信息提供程序

使用运输位置信息提供程序以及您之前定义的授权令牌提取器，开始从车队引擎接收数据。

以下示例展示了如何实例化位置信息提供程序。

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
  });

显示共享的历程

如需显示已安排的任务的进度，请初始化其视图，这会将地图的帧设置为与跟踪的行程的位置相对应。然后，使用方 SDK 在从 Fleet Engine 获取信息后会提供进度。

提示：

确保您的网页包含用于容纳地图视图的 <div> 元素。在以下示例中，<div> 元素名为 map_canvas。
请注意 Fleet Engine 应用于跟踪的历程的默认可见性规则。您还可以为正在进行的车辆运输和预定的停止任务配置公开范围规则。请参阅配置任务指南中的自定义任务公开范围部分。

以下示例展示了如何初始化地图视图。

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);
}

更新配送进度

您可以监听事件，并随着旅程的推进更新配送进度。使用位置信息提供程序从 taskTrackingInfo 对象检索元信息。对元信息所做的更改会触发更新事件。taskTrackingInfo 对象提供以下内容：

预计到达时间
剩余经停点数
距离自提或送达地点的剩余距离

以下示例展示了如何监听这些更改事件。

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);
});

显示多个任务的条件

适用于定期任务的 Consumer SDK 在图表中仅会显示每个跟踪 ID 对应的一项任务。不过，您通常还需要为特定的运单商品分配一个跟踪 ID，该配送商品在您的系统中在整个配送途中始终与该商品保持关联。这意味着，一个跟踪 ID 可能与多个任务相关联，例如同一包裹的取件任务后跟送货任务，或包裹的多个配送失败任务。

为了处理这种情况，车队引擎会应用显示任务的条件，如下表所示。

任务条件	结果
打开取件任务
存在一个	显示任务
存在多个	生成错误
已关闭的接货任务
仅存在一个	显示任务
存在多个（有些具有结果时间）	显示结果时间最近的任务
存在多个（没有任何结果时间）	生成错误
打开提交任务
存在一个	显示任务
存在多个	生成错误
已关闭的提交任务
存在一个	显示任务
存在多个（有些具有结果时间）	显示结果时间最近的任务
存在多个（没有任何结果时间）	生成错误

停止跟踪运输

当配送历程完成或取消时，您的消费者应用应从地图视图中移除跟踪 ID 和位置信息提供程序，以停止跟踪配送。如需了解详情，请参阅以下各部分。

移除跟踪 ID

如需停止位置信息提供程序跟踪运输，请从位置信息提供程序中移除跟踪 ID。以下示例展示了如何执行此操作。

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

从地图视图中移除位置信息提供程序

以下示例展示了如何从地图视图中移除位置信息提供程序。

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

处理物流跟踪错误

由于请求配送信息而异步产生的错误会触发错误事件。以下示例展示了如何监听这些事件以处理错误。

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);
});

注意：请务必将库调用封装在 try...catch 块中，以处理意外错误。

后续步骤

设置地图样式