此页面由 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 属性可让浏览器继续呈现页面。

使用 initMap 函数实例化使用方 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>

实例化配送地点提供商

搭配使用配送地点提供商和授权令牌您先前定义的提取程序，以开始从 Fleet Engine 接收数据。

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

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 从消费者 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 对象。对 Meta 的更改信息会触发 update 事件。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);
});

显示多个任务的条件

计划任务的使用方 SDK 在运行期间针对每个跟踪 ID 仅显示一个任务 地图。不过，您通常需要将一个跟踪 ID 分配给特定的 shipment good（配送商品在整个配送过程中始终与商品保持关联）。这意味着，一个跟踪 ID 可能与多个任务相关联，例如同一包裹的取件任务后跟送货任务，或包裹的多个配送失败任务。

为处理这种情况，Fleet Engine 会应用显示任务的条件，如下表所示。

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

停止关注运单

当发货流程完成或取消时，您的消费者应用应移除跟踪 ID 和位置信息提供程序，从而结束行程共享地图视图。

移除跟踪 ID

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

处理物流跟踪错误

因请求送货信息而异步出现的错误 error 事件。以下示例展示了如何监听这些事件处理错误。

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 块中处理意料之外的错误。

后续步骤

设置地图样式