为大型车辆提供精细导航

本指南面向的对象： 如果您是移动应用开发者，负责为卡车或其他大型车辆的驾驶员打造驾驶室内的导航体验，请阅读本指南。

本指南涵盖的内容： 本指南介绍了如何获取由 Routes API 或 Route Optimization API 生成的卡车专用 路线，并 使用该路线通过 Navigation SDK 提供精细导航会话。

学习内容

您将学习如何执行以下操作：

  • 使用 routeToken 将后端路线规划与应用内导航体验相关联。
  • 配置 Navigation SDK 以使用预先规划的卡车路线。
  • 了解卡车专用限制 在界面中向驾驶员显示的方式。

前提条件

在开始之前，您必须满足以下要求。

项目设置

您的 Google Cloud 云项目必须已预配大型车辆路线规划功能。如果您为 Routes API 和 Navigation SDK 使用单独的项目，则这两个项目都必须相应地进行预配。

生成路线令牌

您必须先按照生成 卡车路线和预计到达时间指南中的说明生成路线。该过程的输出（即 routeToken）是完成本指南中的步骤所必需的。

最低要求

您的应用必须使用最低要求的 Navigation SDK 版本：

  • Android： 5.2.0 或更高版本
  • iOS： 5.4.0 或更高版本

此外，您还必须满足使用 Navigation SDK 的所有要求：

限制

在开始之前，您必须了解以下限制和要求。

  • 地理位置可用性：大型车辆路线规划功能仅在 美国本土 48 个州 提供。
  • 大型车辆路线规划功能处于预览版阶段。驾驶员不得仅依赖此 API 返回的路线来确保安全或合法。系统不保证路线适合车辆，遵循这些路线可能会使驾驶员面临低桥或禁止大型车辆通行的道路等危险。
  • 尽力而为的路线 。在某些情况下，API 无法找到完全符合出行限制的路线。相反，它会返回“尽力而为”的路线，这些路线可能仍会穿过限制区域。Routes API 响应会在 routeRestrictionsPartiallyIgnored 字段中清楚地标记这些路线。 在这种情况下，请仔细规划路线，最好使用其他来源的数据。 请勿将标记的路线用作规划或导航的唯一可信来源。
  • 不支持的功能：我们正在努力为此产品/功能添加更多功能 ，但大型车辆路线规划功能不支持以下功能 ：
    • 卡车通行费
    • 速度限制
    • 放射性危险品的路线规划
  • 用量限额： 所有请求均受标准每秒查询次数 (QPS) 限制的约束。

显示卡车专用界面

Navigation SDK 会在地图上自动显示视觉警告（称为路线 标注），以提醒驾驶员即将到来的卡车限制。系统会为规划路线中的限制呈现标注，但不会为附近的其他道路呈现标注。

SDK 包含以下限制的标注：

限制 标注图标和文字 显示条件
身高 黄色身高限制图标
黄色 = 警告，您的车辆接近允许的最大高度
红色身高限制图标
红色 = 您的车辆超过允许的最大高度 		当车辆的高度接近限制时，系统会显示黄色 标注。
一幅包含高度限制警告的地图
如果路线不合规且违反了高度限制，系统会显示红色标注。
存在高度限制违规情况的地图
重量 限重图标 当车辆的重量超过道路的限制时，系统会显示红色标注。
一幅包含重量限制图标的地图
禁止卡车通行 “禁止卡车通行”图标 在有卡车限制的路段行驶时，系统会显示红色标注。
一幅包含禁止卡车通行图标的地图
危险品 危险品图标 当车辆的危险品货物在路段上被禁止通行时，系统会显示红色标注。
一幅包含危险货物图标的地图

路线令牌工作流

routeToken 是由 Routes API 生成的路线的加密安全快照。它包含所有路线详细信息，包括用于创建路线的车辆资料。使用令牌可确保导航会话与您在后端规划的路线一致。

请注意，驾驶员开始导航后，Navigation SDK 呈现的路线可能会因交通状况和道路状况而发生变化。在某些情况下，它可能会与路线令牌指定的路线有所不同。

在这些情况下，以及在驾驶员偏离规划路线的情况下，使用路线令牌可确保新重新计算的路线遵循原始 Routes API 请求中配置的车辆属性。

工作流遵循以下步骤：

  1. 您的后端向 Routes API 请求卡车路线。
  2. Routes API 返回 routeToken。
  3. 您的后端将此令牌发送到您的移动应用 。
  4. 移动应用将 routeToken 传递给 Navigation SDK 以开始行程。
  5. Navigation SDK 处理精细导航体验的各个方面，包括在驾驶员偏离路线时重新规划路线，同时保留原始车辆限制。

实现：开始卡车专用行程

如需使用卡车路线启动导航会话，请将路线令牌传递给 Navigator。

第 1 步：获取路线令牌

您的应用从后端服务器接收 routeToken 字符串。

以下代码是令牌示例：

CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g

第 2 步：将令牌传递给 Navigator

设置行程目的地时，请向 Navigator 提供 routeToken。 然后，Navigation SDK 会将此令牌用于行程的所有路线计算。

请注意，Navigation SDK 具有 TravelMode 配置，该配置必须设置为 TravelMode.DRIVING。这与 Routes API 中的 travelMode 配置不同，后者必须设置为 TRUCK。Routes API travelMode 配置编码在 routeToken 中，并向 Navigation SDK 发出信号，以显示卡车专用体验和路线。

Android

使用 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)

iOS

使用 mapView.navigator setDestinations 方法将路线令牌传递给 Navigation SDK，并指定创建路线令牌时使用的相同目的地航点：

// Obtain the routeToken string from your backend
let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinations([destination], routeToken: routeToken, callback: {...})

后续步骤