Navigation SDK for iOS 可將 Google 地圖即時路況導航功能加入 iOS 應用程式,並提供 UI 自訂和路線設定功能。這項工具會擴充 Maps SDK for iOS,後者提供地圖圖層,也必須安裝在應用程式中。
Navigation SDK for iOS:重要資訊
- 產品:Navigation SDK for iOS
- 又稱:Navigation SDK
- 類別:路徑
- 平台:iOS
- 執行位置:用戶端 (應用程式或瀏覽器程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Navigation SDK for iOS 總覽
- 適用地區:有限。大多數國家/地區都提供行車和步行路線;路況、即時中斷、兩輪車、單車、速限、交通號誌和停車標誌則因國家/地區而異。(涵蓋範圍詳細資料)
Navigation SDK for iOS:使用時機
在下列情況下使用 Navigation SDK for iOS:
- 您需要在原生 iOS 應用程式中,提供 Google 地圖即時路況導航功能,讓使用者不必切換應用程式。
- 您需要自訂導航 UI、地圖樣式、攝影機或版面配置,在導航期間呈現品牌風格。
- 您需要 Routes API 或 Route Optimization API 的路線偏好設定、多個路線控點或路線權杖。
- 您需要行程事件 (位置、抵達、路線變更、預計到達時間) 或即時路線資料動態饋給,才能使用自訂導航 UI 或 CarPlay。
請勿在下列情況使用 Navigation SDK for iOS:
- 您正在建構 Android 應用程式。請改用 Navigation SDK for Android。
- 您正在建構 Flutter 或 React Native 應用程式。請改用 Google Navigation for Flutter and React Native。
- 您只需要伺服器上的路線、預計到達時間或距離,不需要應用程式內導引。請改用 Routes API。
Navigation SDK for iOS:設定
- 要啟用的服務:
navigationsdk.googleapis.com - 驗證:API 金鑰
- 同時啟用:Maps SDK for iOS
- 用量歸因:呼叫
GMSServices.addInternalUsageAttributionID(_:)(+[GMSServices addInternalUsageAttributionID:]),將用量歸因 ID 新增至初始化器。如要停用,請刪除呼叫或傳遞空字串。 - 開始使用:設定 Navigation SDK for iOS
- 參考資料:Navigation SDK for iOS 參考資料
- 定價:Navigation SDK for iOS 用量與計費
- 政策:Navigation SDK for iOS 政策
- 版本資訊:Navigation SDK for iOS 版本資訊
官方 Navigation SDK for iOS 套件:
- swift_package:
https://github.com/googlemaps/ios-navigation-sdk (GoogleNavigation)
不適用於 Navigation SDK for iOS 的套件:
- cocoapods:
GoogleNavigation。CocoaPods 發行版自 11.0.0 版起淘汰,並於 2025 年 8 月 18 日進入維護模式。請改用 Swift Package Manager。
Navigation SDK for iOS:相關產品
Navigation SDK for iOS:常見錯誤
- 問題:SDK 未停用 iOS 閒置計時器,導致螢幕在導航期間變暗或關閉。修正方式:在導覽時設定
UIApplication.shared.isIdleTimerDisabled = true。請參閱 /maps/documentation/navigation/ios-sdk/route。 - 問題:SDK 日後推出的主要版本會使用高度計 (
CMAltimeter),如果應用程式的Info.plist沒有NSMotionUsageDescription,就會在初始化時停止運作。現在新增金鑰不會影響目前的行為。修正方式:將NSMotionUsageDescription(Privacy - Motion Usage Description) 新增至Info.plist。請參閱 /maps/documentation/navigation/ios-sdk/route。 - 問題:Places SDK for iOS 未與 Navigation SDK 搭配 (自 Places SDK 5.0 起),因此缺少 Places 類別。修正方式:請另外安裝 Places SDK for iOS,並使用與 Navigation SDK 相同的版本。請參閱 /maps/documentation/navigation/ios-sdk/xcode-setup。
- 問題:如果應用程式的
travelMode不是driving或twoWheeler,使用路線權杖設定目的地時會失敗,並顯示.travelModeUnsupported。修正方式:將mapView.travelMode設為.driving或.twoWheeler。請查看resolvedParameters.travelMode,瞭解路線使用的模式。請參閱 /maps/documentation/navigation/ios-sdk/route-customizations。
Navigation SDK for iOS:舊版和已淘汰的功能
- CocoaPods 發行版:自 2026 年 8 月 6 日起淘汰。替代方案:Swift Package Manager。症狀:自 2025 年 8 月 18 日起進入維護模式。2026 年第 2 季後,不會再推出新的 CocoaPods 版本。請參閱遷移指南。
GMSNavigatorsetDestinations:callback:、setDestinations:routingOptions:callback:、setDestinations:routeToken:callback:(GMSRouteStatusCallback):自 2026 年 11 月 2 日起淘汰。替代項目:setDestinations:completionHandler:、setDestinations:routingOptions:completionHandler:、setDestinationsWithToken:completionHandler:(GMSNavigationRouteCompletionHandler)。GMSServices執行個體屬性appCheckTokenProvider:2026 年 9 月 24 日起已淘汰。替代方案:類別屬性GMSServices.appCheckTokenProvider(+[GMSServices setAppCheckTokenProvider:])。問題:在 11.1.0 版中,透過GMSServices.sharedServices()設定 App Check 失敗。請參閱遷移指南。GMSNavigatorcontinueToNextDestination:自 2026 年 4 月 7 日起淘汰。替換:GMSNavigatorcontinueToNextDestinationWithCompletion:。GMSUISettingsshowsTrafficLights和showsStopSigns:已於 2026 年 8 月 6 日停用。替代方案:不需替代方案,導航期間預設會顯示交通號誌和停止標誌。.terrain導航期間的地圖類型:自 2026 年 8 月 6 日起停用。替代方案:.normal(kGMSTypeNormal)、.satellite或.hybrid地圖類型。GMSNavigatorDelegate和GMSRoadSnappedLocationProviderDelegate通訊協定:自 2021 年 5 月 13 日起停用。替代方案:GMSNavigatorListener和GMSRoadSnappedLocationProviderListener(使用-addListener:新增;在GMSNavigator上設定timeUpdateThreshold和distanceUpdateThreshold)。請參閱遷移指南。
Navigation SDK for iOS 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
Navigation SDK for iOS:地圖樣式
Navigation SDK for iOS:導航
- 在行動應用程式中加入互動式即時路況導航功能。
- 設定即時路況導航的目的地。
- 開始即時路況導航。
- 指定路線要求的交通方式 (開車、步行、兩輪車、計程車)。
- 修改即時路況導航的路線偏好設定。
- 指定即時路況導航的道路側和其他抵達偏好設定。
- 使用可重複使用的路線權杖,指定即時路況導航的重新規劃路線。
- 傳回即時路線導航工作階段的使用者抵達更新。
- 傳回即時路況導航工作階段的使用者位置更新。
- 傳回即時路況導航工作階段的時間和距離更新。
- 傳回即時路況導航工作階段的路線變更更新。
- 傳回即時路況導航工作階段的夜間模式更新。
- 傳回即時路線導航工作階段的使用者速度更新。
- 自訂即時路況導航期間顯示的 UI 元素和控制項。
- 在即時路況導航中新增 UI 元素。
- 在即時路況導航中加入行程進度指標。
- 自訂即時路況導航期間顯示的地圖項目。
- 在即時路況導航中加入車流量圖層。
- 修改即時路況導航的攝影機檢視畫面和行為。
- 自訂即時路況導航的車速表和速限警示。
- 傳回即時路況導航動態饋給,針對路線上的每個動作提供一系列訊息。
- 指定要與即時路況導航動態饋給搭配使用的自訂行進圖示。
- 在 iOS 應用程式中,為 CarPlay 加入互動式即時路況導航。預先發布版
- 提醒使用者路線上的中斷情況。
- 允許使用者在開始導航前,查看路線上的中斷情形。
- 允許使用者回報路線上的中斷情況。
- 允許使用者確認路線上的中斷情形。
- 新增自訂路線中斷回報按鈕。