本指南適用對象：如果您是行動應用程式開發人員，負責為卡車、巴士或其他大型商用車的駕駛人建構路線規劃體驗，請參閱本指南。
本指南涵蓋內容：本指南說明如何取得 Routes API 或 Route Optimization API 產生的卡車專屬路線，並使用該路線透過 iOS 版 Navigation SDK 啟動即時路況導航。
課程內容
您將瞭解如何執行下列工作：
- 使用
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.4.0 以上版本。此外，專案也必須符合標準的Navigation SDK 設定需求。
限制和作業指南
開始之前，請注意下列限制和操作規範：
- 適用地區：大型車輛路線規劃功能適用於美國本土 48 州 (正式發布) 和日本 (實驗版)。不適用於阿拉斯加、夏威夷或美國領土。
- 駕駛人建議和安全：駕駛人不得完全依賴 Navigation SDK 傳回的路線，確保安全或合法。路線可能不適合所有路況下的車輛，跟隨路線可能會讓駕駛人暴露於危險中，例如淨空高度不足或有重量限制的道路。駕駛人必須隨時保持警覺，並遵守張貼的道路標誌和當地法規。
- 盡量符合限制的路線：如果 Routing API 找不到完全符合車輛限制的路線，就會傳回「盡量符合限制」的路線，這類路線可能仍會經過受限路段。舉例來說，Routes API 會在回應中設定
routeRestrictionsPartiallyIgnored旗標。在這些路徑上導航時，Navigation SDK 會顯示路徑標註，醒目顯示相關限制。在這些情況下，請仔細規劃路線，且不要將標記的路線做為規劃或導航的單一事實來源。 - 不支援的功能：大型車輛路線規劃不支援下列功能：
- 卡車通行費
- 卡車或重型車輛的速限
- 放射性有害物質的路線
- 用量限制：對 Navigation SDK 提出的要求會受到標準用量和配額限制。詳情請參閱「用量與計費」。
顯示卡車專屬的 UI (路線標註)
Navigation SDK 會在地圖上自動顯示視覺警告 (稱為路線標註)，提醒駕駛人即將遇到卡車限制。如果限制發生在規劃路線上，系統會顯示附註，但不會顯示在附近的其他道路上。
Navigation SDK 包含下列限制的附註：
| 限制 | 圖說圖示和文字 | 顯示條件 |
|---|---|---|
| 高度 |
黃色 = 警告，車輛高度接近允許上限 
紅色 = 車輛高度超過允許上限 |
車輛高度接近限制時，系統會顯示黃色標註。
如果路線不符合規定，違反高度限制，系統會顯示紅色標註。 
|
| 權重 |
|
如果車輛重量超過道路限制，系統會顯示紅色標註。
|
| 禁止卡車通行 |
|
行駛於有商用卡車限制的路段時，畫面上會顯示紅色的標註。
|
| 危險物品 |
|
如果車輛的危險物品裝載量超過路段限制，系統會顯示紅色標示。
|
路徑權杖的運作方式
routeToken 是由 Google 路線後端建立的加密路線快照。其中封裝了規劃路線的幾何形狀，以及車輛的實體尺寸和限制設定檔。
工作流程如下：
- 要求路線：後端伺服器向 Routes API (或 Route Optimization API) 要求卡車路線。
- 接收權杖：Routing API 會計算符合規定的路線，並將
routeToken傳回後端伺服器。 - 轉送權杖：後端伺服器會將
routeToken和目的地座標傳遞至行動應用程式。 - 傳遞至 SDK：行動應用程式會將
routeToken傳遞至 Navigation SDK。 - 開始導覽：Navigation SDK 會處理所有即時路線體驗，包括算繪路線標註，以及根據車輛限制處理動態重新規劃路線。
動態重新計算和重新規劃路線
在主動導航期間，如果遇到路況、道路封閉或錯過轉彎，車輛可能會偏離規劃路線。
重新規劃路線時：
- Navigation SDK 會自動重新計算前往目的地的路線。
- SDK 會保留原始
routeToken中編碼的車輛屬性和尺寸。 - 重新計算的路線會避開低淨空高度、限重橋樑，以及禁止商用卡車通行的道路。
實作：開始卡車專屬行程
請按照下列步驟，使用大型車輛路線權杖初始化並開始即時路況導航。
步驟 1：從後端取得路徑權杖
行動應用程式會從後端伺服器接收 routeToken 字串和目的地座標。如要瞭解如何在伺服器上產生這個權杖，請參閱 Routes API 說明文件中的「產生大型車輛路線和預計抵達時間」。
以下是路徑權杖範例：
{
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}
步驟 2：將權杖傳遞至 Navigator
將 routeToken 和目的地路線控點傳遞至 mapView.navigator
setDestinations 方法。
設定途中的航點並傳遞路線權杖時，請注意下列事項：
- 目的地比對規定：傳遞至
setDestinations的目的地座標，必須與產生routeToken時使用的目的地座標相符。指定其他目的地會導致錯誤。 - 靠路邊路線：大型商用車輛無法在狹窄街道上輕鬆迴轉，為確保貨車從道路正確側接近目的地，請在途中的每個停靠點設定
preferSameSideOfRoad = true。 - 車輛中途停靠：如要引導卡車前往適當的停靠或卸貨地點，請在途中的航點上設定
vehicleStopover = true。 - 導覽點：如果目的地設有專用貨運入口或裝卸碼頭，請使用導覽點權杖指定。
步驟 3：處理路線狀態並開始導航
評估 setDestinations 回呼中傳回的 GMSRouteStatus。當狀態為 .OK (GMSRouteStatusOK) 時，請設定 isGuidanceActive = true (guidanceActive = YES) 開始提供即時的逐向導引。
程式碼範例
使用 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: {...})