本指南的适用对象：如果您是移动开发者，负责为卡车、公交车或其他大型商用车的司机打造精细导航体验，请阅读本指南。
本指南涵盖的内容：本指南介绍了如何获取由 Routes API 或 Route Optimization API 生成的卡车专用路线，并使用该路线通过 Navigation SDK for Android 启动精细导航会话。
学习内容
您将学习如何完成以下任务：
- 使用
routeToken将后端路线规划与应用内导航体验连接起来。 - 配置 Navigation SDK，以使用预先规划的卡车路线。
- 了解卡车专用限制在导航界面中如何向司机显示。
前提条件
在开始之前，请确保您满足以下要求：
1. 为您的项目申请访问权限
大型车辆路线规划功能仅面向部分客户提供。如需表达兴趣并为您的 Google Cloud 云项目申请访问权限，请填写联系表单。Google 代表会与您联系，告知您后续步骤。
Google 授予访问权限后，请确保您的 Google Cloud 项目已配置为支持大型车辆路线规划。
如果贵组织为后端 Routes API 和移动 Navigation SDK 使用不同的 Google Cloud 云项目，请与 Google 联系，为每个项目进行配置。
2. 设置后端路线生成并获取路线令牌
在设备上开始导航之前，您的后端服务器必须生成卡车路线，并使用以下任一 API 获取 routeToken：
- Routes API：建议用于计算起点和终点之间的单条卡车路线。如需查看设置说明，请参阅生成大型车辆路线和预计到达时间。
- Route Optimization API：建议用于优化整个车队的多经停点路线。如需了解详情，请参阅 Route Optimization API 大型车辆路线规划指南。
您的后端请求必须指定 travelMode: TRUCK 以及车辆的物理属性（高度、宽度、长度、重量、车轴数量和危险品货物）。Routes API 会在其响应中返回 routeToken，您的后端服务器会将该令牌传递给您的移动应用。
3. 满足最低 SDK 和系统要求
您的应用必须使用最低要求的 Navigation SDK 版本 5.2.0 或更高版本。此外，您的项目必须满足标准的 Navigation SDK 设置要求。
限制和操作指南
在开始之前，请注意以下限制和操作指南：
- 适用地区：大型车辆路线规划功能适用于美国本土 48 个州（正式版）和日本（实验版）。阿拉斯加、夏威夷或美国领地不提供此服务。
- 驾驶员建议和安全：驾驶员不得仅依赖 Navigation SDK 返回的路线来确保安全或合法。在某些路况下，路线可能不适合车辆，遵循这些路线可能会使驾驶员面临净空高度低或道路限重等危险。驾驶员必须始终保持警惕，并遵守张贴的路标和当地法规。
- 尽力而为路线：当 Routes API 无法找到完全符合车辆限制的路线时，它会返回一条“尽力而为”路线，该路线可能仍会穿过受限路段。例如，Routes API 会在其响应中设置
routeRestrictionsPartiallyIgnored标志。在这些路线上导航时，Navigation SDK 会显示路线标注，以突出显示相关限制。在这些情况下，请仔细规划路线，不要将标记的路线作为规划或导航的单一事实来源。 - 不支持的功能：大型车辆路线规划不支持以下功能：
- 卡车通行费
- 卡车或重型车辆专用限速
- 放射性有害物质的路线
- 用量限额：向 Navigation SDK 发出的请求遵循标准用量和配额限制。如需了解详情，请参阅用量和结算。
显示卡车专用界面（路线标注）
Navigation SDK 会自动在地图上显示视觉警告（称为路线标注），以提醒驾驶员前方有卡车限制。标注会显示在规划路线沿途的限制路段，但不会显示在附近的其他道路上。
Navigation SDK 包含针对以下限制的标注：
| 限制 | 宣传信息图标和文字 | 显示条件 |
|---|---|---|
| Height |
黄色 = 警告，您的车辆接近允许的最大高度 
红色 = 您的车辆超过了允许的最大高度 |
当车辆高度接近限制时，系统会显示黄色标注。
如果路线不合规且违反了高度限制，则会显示红色标注。 
|
| 权重 |
|
当车辆重量超过道路限重时，系统会显示红色标注。
|
| 禁止卡车通行 |
|
在有商用卡车限制的路段上行驶时，系统会显示红色标注。
|
| 危险品 |
|
如果车辆的危险品负载在某个路段上被禁止，则会显示红色标注。
|
路线令牌的工作原理
routeToken 是由 Google 路线后端创建的路线的加密快照。它封装了规划的路线几何图形以及车辆的物理尺寸和限制配置文件。
工作流遵循以下步骤：
- 请求路线：您的后端服务器向 Routes API（或 Route Optimization API）请求卡车路线。
- 接收令牌：Routes API 计算合规路线，并向您的后端服务器返回
routeToken。 - 转发令牌：您的后端服务器将
routeToken和目的地坐标传递给移动应用。 - 传递给 SDK：移动应用将
routeToken传递给 Navigation SDK。 - 开始导航：Navigation SDK 会处理精细导航体验的所有方面，包括呈现路线标注以及根据车辆限制处理动态重新规划路线。
动态重新计算和重新规划路线
在主动导航期间，路况信息、封路或错过转弯可能会导致车辆偏离规划路线。
重新规划路线时：
- Navigation SDK 会自动重新计算前往目的地的路线。
- SDK 会保留原始
routeToken中编码的车辆属性和维度。 - 新计算出的路线会避开限高路段、限重桥梁以及禁止商用卡车通行的道路。
实现：启动卡车专用行程
请按照以下步骤初始化并使用大型车辆路线令牌启动精细导航。
第 1 步：从后端获取路线令牌
您的移动应用会从后端服务器接收 routeToken 字符串以及目的地坐标。如需详细了解如何在服务器上生成此令牌，请参阅 Routes API 文档中的生成大型车辆路线和预计到达时间。
以下代码是一个路线令牌示例：
{
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}
第 2 步：配置 CustomRoutesOptions
使用 CustomRoutesOptions.builder 将路线令牌传递给 CustomRoutesOptions 实例：
- 使用
setRouteToken(routeToken)传递令牌。 - 使用
setTravelMode(CustomRoutesOptions.TravelMode.DRIVING)设置出行方式。
第 3 步：定义航点并设置目的地
将目的地航点和 CustomRoutesOptions 传递给 navigator.setDestinations。
在配置航点和传递自定义路线选项时，请注意以下事项：
- 目的地匹配要求：传递给
setDestinations的目的地坐标必须与生成routeToken时使用的目的地坐标一致。指定其他目标位置会导致错误。 - 路边路线规划：大型商用车在狭窄的街道上很难掉头。为确保卡车从道路的正确一侧接近目的地，请在航点上调用
setPreferSameSideOfRoad(true)。 - 车辆停靠点：如需引导卡车前往合适的位置停车或卸货，请在航点上调用
setVehicleStopover(true)。 - 导航点：如果目的地有指定的货运入口或装卸站，请使用导航点令牌进行指定。
第 4 步：处理路线状态并开始导航
在 ListenableResultFuture<Navigator.RouteStatus> 上注册 OnResultListener。当路线状态为 OK 时，调用 navigator.startGuidance 以开始有效的精细导航。
代码示例
使用 CustomRoutesOptions.builder 设置令牌，然后将其传递给 navigator.setDestinations。
// Obtain the routeToken string from your backend
val routeToken = "route token returned by Routes API"
val customRoutesOptions = CustomRoutesOptions.builder()
.setRouteToken(routeToken)
.setTravelMode(TravelMode.DRIVING)
.build()
// Specify the same destination used to create the route token
ArrayList <Waypoint> destinations = Lists.newArrayList();
val destination = Waypoint.builder()
.setLatLng(10.0, 20.0)
.setTitle("title")
.setVehicleStopover(true)
.build()
destinations.add(destination);
navigator.setDestinations(destinations, customRoutesOptions)