本指南的适用对象：如果您是移动开发者，负责为卡车、公交车或其他大型商用车的司机打造精细导航体验，请阅读本指南。
本指南涵盖的内容：本指南介绍了如何获取由 Routes API 或 Route Optimization API 生成的卡车专用路线，并使用该路线通过 Navigation SDK for iOS 启动精细导航会话。
学习内容
您将学习如何完成以下任务：
- 使用
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.4.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 步：使用路线令牌设置目的地
将 routeToken 传递给 mapView.navigator setDestinationsWithToken:completionHandler: 方法。Navigation SDK 会从路线令牌中获取目的地，以及指示其应用大型车辆限制的 TRUCK 路线配置文件。您无需传递航点。应用的出行方式必须是 .driving (GMSNavigationTravelModeDriving)（默认值）或 .twoWheeler (GMSNavigationTravelModeTwoWheeler)。
在创建路线令牌的 Routes API 请求中设置航点选项。 Navigation SDK 会从令牌中获取这些信息以及您的目的地。对于大型车辆，请考虑以下选项：
- 路边路线规划：大型商用车无法在狭窄的街道上轻松掉头。为确保卡车从道路的正确一侧接近目的地，请在目的地航点上将
sideOfRoad设置为true。 - 车辆停靠点：如需引导卡车前往合适的位置停车或卸货，请在目的地航点上将
vehicleStopover设置为true。 - 导航点：如果您的目的地有指定的货运入口或装卸站，请使用导航点令牌进行指定。
第 3 步：处理路线状态并开始导航
Navigation SDK 完成路线计算后，会将 GMSNavigationRouteDescription 传递给您的完成处理程序。当其 routeStatus 为 .OK (GMSRouteStatusOK) 时，设置 isGuidanceActive = true (guidanceActive = YES) 以开始主动精细导航。
如需确认 Navigation SDK 是否应用了路线令牌，请参阅检查 Navigation SDK 是否应用了路线令牌。
代码示例
将路线令牌传递给 setDestinationsWithToken:completionHandler:，然后在路线状态为 .OK 时开始导航。
// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
if routeDescription?.routeStatus == .OK {
self?.mapView.navigator?.isGuidanceActive = true
}
}