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