本指南面向的对象 ：如果您是移动开发者，负责为卡车、巴士或其他大型商用车辆的驾驶员打造精细导航体验，请阅读本指南。
本指南涵盖的内容：本指南介绍了如何获取由 Routes API 或 Route Optimization API 生成的卡车专用路线，并使用该路线通过 Navigation SDK for Android 驱动精细导航会话。
学习内容
您将学习如何执行以下任务：
- 使用
routeToken将后端路线规划与 应用内导航体验相关联。 - 配置 Navigation SDK 以使用预先规划的卡车路线。
- 了解卡车专用限制 在导航界面中向驾驶员显示的方式。
前提条件
在开始之前，请确保满足以下要求：
1. 为您的项目请求访问权限
大型车辆路线规划功能仅面向部分客户提供。如要表达 兴趣并为您的 Google Cloud 项目请求访问权限，请填写 联系表单。Google 代表会与您联系，告知您后续步骤。
Google 授予访问权限后，请确保您的 Google Cloud 项目已预配大型车辆路线规划功能。
如果您的组织为后端路线规划 API 和移动 Navigation SDK 使用单独的 Google Cloud 项目，请与 Google 联系以预配每个项目。
2. 设置后端路线生成并获取路线令牌
在设备上开始导航之前，您的后端服务器必须生成卡车路线并使用以下某个 API 获取 routeToken：
- Routes API：建议用于计算 起点和目的地之间的单条卡车路线。如需了解设置说明，请参阅生成大型 车辆路线和预计到达时间。
- Route Optimization API：建议用于优化多经停点路线 车队。如需了解详情，请参阅 Route Optimization API 大型车辆路线规划指南。
您的后端请求必须指定 travelMode: TRUCK 以及车辆的物理属性（高度、宽度、长度、重量、轴数和危险品货物）。路线规划 API 会在其响应中返回 routeToken，您的后端服务器会将该令牌传递给您的移动应用。
3. 满足最低 SDK 和系统要求
您的应用必须使用最低要求的 Navigation SDK 版本 5.2.0 或更高版本。此外，您的项目必须满足标准 Navigation SDK 的设置要求。
限制和操作指南
在开始之前，请注意以下限制和操作指南：
- 地理位置可用性：大型车辆路线规划功能在 美国本土 48 个州（正式版）和日本 （实验版）提供。该功能在阿拉斯加、夏威夷或美国属地不可用。
- 驾驶员建议和安全：驾驶员不得仅依赖 Navigation SDK 返回的路线 来确保安全或合法。路线可能不适合所有路况下的车辆，遵循这些路线可能会使驾驶员面临低净空或限重道路等危险。 驾驶员必须始终保持警惕，并遵守张贴的道路标志和当地法规。
- 尽力而为的路线：当路线规划 API 找不到完全
符合车辆限制的路线时，它会返回“尽力而为”的路线，该路线
可能仍会经过受限路段。例如，Routes API 会在其响应中设置
routeRestrictionsPartiallyIgnored标志。在导航这些路线时，Navigation SDK 会显示路线宣传信息，以突出显示相关限制。在这些情况下，请仔细规划路线，不要将标记的路线用作规划或导航的唯一可靠来源。 - 不支持的功能：大型车辆路线规划功能不支持以下功能：
- 卡车通行费价格
- 卡车或重型车辆专用限速
- 放射性危险品路线规划
- 用量限制：对 Navigation SDK 发出的请求遵循 标准用量和配额限制。如需了解详情，请参阅 用量和结算。
显示卡车专用界面（路线宣传信息）
Navigation SDK 会在地图上自动显示视觉警告（称为 路线宣传信息），以提醒驾驶员即将到来的卡车 限制。宣传信息会针对计划路线中出现的限制显示，但不会在附近的其他道路上显示。
Navigation SDK 包含以下限制的宣传信息：
| 限制 | 宣传信息图标和文字 | 显示条件 |
|---|---|---|
| 身高 |
黄色 = 警告，您的车辆接近允许的最大高度 
红色 = 您的车辆高于允许的最大高度 |
当车辆的高度接近限制时，系统会显示黄色 宣传信息。
如果路线不合规并违反了高度限制，系统会显示红色 宣传信息。 
|
| 重量 |
|
当车辆的重量
超过道路的限制时，系统会显示红色宣传信息。
|
| 禁止卡车通行 |
|
在有商用卡车限制的路段行驶时，系统会显示红色 宣传信息。
|
| 危险品 |
|
当车辆的危险品货物在路段上被禁止时，系统会显示红色 宣传信息。
|
路线令牌的工作原理
routeToken 是由 Google 的路线规划后端创建的路线的加密快照。它封装了计划路线的几何图形以及车辆的物理尺寸和限制配置文件。
工作流程遵循以下步骤：
- 请求路线：您的后端服务器向 Routes API（或Route Optimization API）请求卡车路线。
- 接收令牌：路线规划 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 步：处理路线状态并开始导航
注册 OnResultListener 到
ListenableResultFuture<Navigator.RouteStatus>。当路线状态为 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)