现在，您已为安排的任务设置了 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 函数实例化 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
});
显示共享的行程
如需显示已安排的任务的进度，请初始化其视图，这会将地图的帧设置为与跟踪的行程的位置相对应。然后，Consumer SDK 会在从 Fleet Engine 获取信息后提供进度。
提示：
确保您的网页包含用于容纳地图视图的 <div> 元素。在以下示例中，<div> 元素名为
map_canvas。请注意车队引擎对跟踪的行程应用的默认公开范围规则。您还可以为正在进行的车辆运输和预定的停止任务配置公开范围规则。请参阅配置任务指南中的自定义任务公开范围部分。
以下示例展示了如何初始化地图视图。
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
如需停止位置信息提供程序跟踪运输，请从位置信息提供程序中移除跟踪 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 块中，以处理意外错误。