现在，您已为预定任务设置了 JavaScript Consumer 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 函数实例化 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>
实例化配送位置信息提供程序
使用货件位置信息提供程序以及您之前定义的授权令牌提取器，开始从 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
});
显示共享行程
如需显示预定任务的进度，请初始化其视图，该视图会设置地图的框架，使其与所跟踪行程的位置相对应。然后，Consumer 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 可能与多个任务相关联，例如同一包裹的取件任务和配送任务，或者包裹的多个配送失败任务。
为应对这种情况，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 块中，以处理意外错误。