為大型車輛提供即時路線導航

本指南適用對象：如果您是行動應用程式開發人員，負責為卡車或其他大型車輛的駕駛人打造車內導航體驗，請參閱本指南。

本指南涵蓋的主題：本指南說明如何取得 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) 限制。

顯示卡車專屬 UI

Navigation SDK 會在地圖上自動顯示視覺警告 (稱為「路線標註」)，提醒駕駛人即將遇到的卡車限制。系統會針對規劃路線中的限制顯示附註，但不會顯示附近其他道路的限制。

SDK 包含下列限制的附註：

限制 圖說圖示和文字 顯示條件
身高 黃色高度限制圖示
黃色 = 警告，車輛高度接近允許上限
紅色高度限制圖示
紅色 = 車輛高度超過允許上限 		車輛高度接近限制時，系統會顯示黃色標註。
顯示高度限制警告的地圖
如果路線不符合規定，且違反高度限制，系統會顯示紅色標註。
地圖：顯示違反高度限制的車輛
體重 限重圖示 如果車輛重量超過道路限制，系統會顯示紅色標註。
含重量限制圖示的地圖
禁止卡車通行 禁止卡車通行圖示 行駛在有卡車限制的路段時，系統會顯示紅色對話框。
含禁止卡車圖示的地圖
危險物品 危險物品圖示 如果路段禁止車輛運送危險物品，系統會顯示紅色標註。
含危險物品圖示的地圖

路徑權杖工作流程

routeToken 是由 Routes API 產生的加密安全路徑快照。其中包含所有路線詳細資料，包括用於建立路線的車輛設定檔。使用權杖可確保導覽工作階段與您在後端規劃的路徑相符。

請注意，駕駛人開始導航後，導航 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

設定行程目的地時，請將 routeToken 提供給 Navigator。 然後，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: {...})

後續步驟