本指南適用對象：如果您是行動應用程式開發人員，負責為卡車、巴士或其他大型商用車的駕駛人建構路線規劃體驗，請參閱本指南。
本指南涵蓋的主題：本指南說明如何取得 Routes API 或 Route Optimization API 產生的卡車專屬路線，並使用 iOS 版 Navigation SDK 啟動即時路況導航。
課程內容
您將瞭解如何執行下列工作：
- 使用
routeToken將後端路線規劃與應用程式內導覽體驗連結。 - 設定 Navigation SDK，使用預先規劃的卡車路線。
- 瞭解導航使用者介面如何向駕駛人顯示卡車專屬限制。
必要條件
開始前，請確認符合下列需求：
1. 申請專案存取權
大型車輛路線規劃功能僅適用於少數客戶。如要表達意願並為 Google Cloud 雲端專案申請存取權，請填寫聯絡表單。Google 代表會與您聯絡，說明後續步驟。
Google 授予存取權後，請確認 Google Cloud 雲端專案已佈建大型車輛路徑規劃服務。
如果貴機構使用不同的 Google Cloud 專案來處理後端路徑 API 和行動版 Navigation SDK，請與 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: {...})