本指南適用對象：如果您是行動開發人員，負責為卡車、公車或其他大型商用車的駕駛人打造即時路況導航體驗，請參閱本指南。
本指南涵蓋內容：本指南說明如何使用 Routes API 或 Route Optimization API 生成卡車專用路線，並透過 iOS 導航 SDK，使用該路線進行即時路況導航。
課程內容
您將瞭解如何執行下列工作：
- 使用
routeToken，將後端路線規劃與應用程式內導航體驗連結。 - 設定 Navigation SDK，使用預先規劃的卡車路線。
- 瞭解導航 UI 如何向駕駛人顯示卡車專用限制。
必要條件
開始前，請確認您符合下列需求：
1. 申請專案存取權
大型車輛路線規劃功能僅開放給部分客戶使用。如要表達意願並為 Google Cloud 雲端專案申請存取權，請填寫聯絡表單。Google 代表會與您聯絡，說明後續步驟。
Google 授予存取權後，請確認 Google Cloud 專案已佈建大型車輛路線規劃功能。
如果貴機構使用不同的 Google Cloud 雲端專案，分別處理後端 Routes API 和行動 Navigation SDK，請與 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 傳回的路線，來確保安全或合法。路線可能不適合車輛在所有路況下行駛，如果駕駛人按照路線行駛，可能會遇到危險，例如限高或限重道路。駕駛人必須隨時保持警覺，並遵守道路標誌和當地法規。
- 盡力而為路線：如果 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中編碼的車輛屬性和維度。 - 重新計算的新路線會避開低淨空、限重橋梁，以及禁止商用卡車通行的道路。
實作：開始卡車專屬行程
請按照下列步驟，使用大型車輛路線權杖，初始化並啟動即時路線導航。
Step 1：從後端取得路徑權杖
您的行動應用程式會從後端伺服器收到 routeToken 字串和目的地座標。如要瞭解如何在伺服器上產生這個權杖，請參閱 Routes API 說明文件中的「產生大型車輛路線和預計到達時間」。
以下程式碼是路線權杖範例：
{
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g"
}
Step 2：將權杖傳遞至導覽器
將 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: {...})