现在，您已为安排的任务设置了 JavaScript 消费者 SDK，接下来就可以使用消费者应用跟踪配送。本文档将介绍此过程中的以下关键步骤：
- 初始化地图并显示共享的行程
- 更新并跟踪旅程进度
- 停止跟踪运输
- 处理配送跟踪错误
设置地图
如需在 Web 应用中跟踪运输接收或送达情况，您需要加载地图并实例化 Consumer SDK，以便开始跟踪运输。您可以加载新地图或使用现有地图。然后，您可以使用初始化函数实例化 Consumer SDK，以便地图视图与被跟踪项的位置相对应。
使用 Google Maps JavaScript API 加载新地图
如需创建新地图，请在您的 Web 应用中加载 Google Maps JavaScript API。以下示例展示了如何加载 Google Maps JavaScript API、启用 SDK 并触发初始化检查。
callback参数会在 API 加载后运行initMap函数。defer属性可让浏览器在 API 加载的同时继续渲染网页的其余部分。
使用 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>
实例化配送地点提供商
使用运输位置信息提供程序以及您之前定义的授权令牌提取器，开始从车队引擎接收数据。
以下示例展示了如何实例化位置信息提供程序。
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 对象检索元信息。对元信息的更改会触发 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);
});
显示多个任务的条件
适用于定期任务的 Consumer SDK 在图表中仅会显示每个跟踪 ID 对应的一项任务。不过，您通常还需要为特定的运单商品分配一个跟踪 ID，该配送商品在您的系统中在整个配送途中始终与该商品保持关联。这意味着，一个跟踪 ID 可能与多个任务相关联，例如同一包裹的取件任务后跟送货任务，或包裹的多个配送失败任务。
为了处理这种情况，车队引擎会应用显示任务的条件，如下表所示。
| 任务条件 | 结果 |
|---|---|
| 打开自提任务 | |
| 存在一个 | 显示任务 |
| 存在多个 | 生成错误 |
| 已关闭的接货任务 | |
| 存在一个 | 显示任务 |
| 存在多个（有些具有结果时间） | 显示结果时间最近的任务 |
| 存在多个（没有任何结果时间） | 生成错误 |
| 打开交付任务 | |
| 存在一个 | 显示任务 |
| 存在多个 | 生成错误 |
| 关闭的交付任务 | |
| 仅存在一个 | 显示任务 |
| 存在多个（有些具有结果时间） | 显示结果时间最近的任务 |
| 存在多个（没有任何结果时间） | 生成错误 |
停止跟踪运输订单
当发货流程完成或取消后，您的消费者应用应通过从地图视图中移除跟踪 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 块中，以处理意外错误。