Navigation SDK for iOS 快速參考

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:

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:常見錯誤

  • 問題: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 版本。請參閱遷移指南。
  • GMSNavigator setDestinations: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 失敗。請參閱遷移指南。
  • GMSNavigator continueToNextDestination:自 2026 年 4 月 7 日起淘汰。替換:GMSNavigatorcontinueToNextDestinationWithCompletion:。
  • GMSUISettings showsTrafficLights 和 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:導航