Navigation SDK for Android 可將 Google 地圖即時路況導航功能加入 Android 應用程式,並提供 UI 自訂和路線設定功能。其中包含 Maps SDK 地圖圖層,因此使用該程式庫的應用程式無法同時包含 Maps SDK for Android。
Navigation SDK for Android:重要資訊
- 產品:Navigation SDK for Android
- 又稱:Navigation SDK
- 類別:路徑
- 平台:Android
- 執行位置:用戶端 (應用程式或瀏覽器程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Navigation SDK for Android 總覽
Navigation SDK for Android:使用時機
在下列情況下使用 Navigation SDK for Android:
- 您需要在自己的 Android 應用程式中,提供 Google 地圖即時路況導航功能,讓使用者不必切換至其他應用程式。
- 您需要自訂導航 UI,使其符合品牌形象,或打造自訂導航體驗。
- 您需要應用程式內導航功能,用於開車、步行、騎單車或兩輪車。
- 您必須將路徑權杖傳遞至 SDK,才能沿著使用 Routes API 規劃的路徑導航。
請勿在下列情況使用 Navigation SDK for Android:
- 您正在建構 iOS 應用程式。請改用 Navigation SDK for iOS。
- 您正在使用 Flutter 或 React Native 建構跨平台應用程式。請改用 Google Navigation for Flutter and React Native。
- 您需要伺服器端路線、預計到達時間或路線權杖運算,而非應用程式內即時路線指引。請改用 Routes API。
Navigation SDK for Android:設定
- 要啟用的服務:
navigationsdk.googleapis.com - 驗證:API 金鑰
- 用量歸因:呼叫
MapsApiSettings.addInternalUsageAttributionId(context, id),將用量歸因 ID 新增至初始化工具。如要停用,請刪除呼叫或傳遞空字串。 - 開始使用:設定 Navigation SDK for Android
- 參考資料:Navigation SDK for Android 參考資料
- 定價:Navigation SDK for Android 用量與計費
- 政策:Navigation SDK for Android 政策
- 版本資訊:Navigation SDK for Android 版本資訊
官方 Navigation SDK for Android 套件:
- maven:
com.google.android.libraries.navigation:navigation
Navigation SDK for Android:相關產品
Navigation SDK for Android:常見錯誤
- 問題:Navigation SDK 已隨附 Maps SDK。如果版本直接或透過傳遞依附元件提取
play-services-maps,就會產生重複的 Maps SDK 副本。修正方式:從所有依附元件中排除com.google.android.gms:play-services-maps(Gradle 設定排除或 Maven 排除),並移除任何直接的 Maps SDK 依附元件。請參閱 /maps/documentation/navigation/android-sdk/android-studio-setup。 - 問題:Navigation SDK 8.0 以上版本會宣告
minAndroidGradlePluginVersion=9.0.1,因此使用舊版 AGP 的建構作業會失敗。修正方式:使用 8.0 以上版本建構前,請先升級至 AGP 9.0.1、Gradle 9.1.0 和 Kotlin 2.3.0。請參閱 /maps/documentation/navigation/android-sdk/kotlin-compatibility-migration。 - 問題:使用
NavigationFragment時直接呼叫NavigationView生命週期方法,或未按照NavigationView順序呼叫,會導致錯誤。修正方式:使用NavigationFragment管理生命週期回呼。如果使用NavigationView,請嚴格按照順序轉送生命週期方法。請參閱 /maps/documentation/navigation/android-sdk/nav-map-interactions-best-practices。 - 問題:使用者必須接受 Google 導航服務條款,才能使用導航功能。修正方式:讓 SDK 在首次叫用導覽器時顯示提示,或使用
TermsAndConditionsCheckOption/NavigationApi.showTermsAndConditionsDialog提早顯示對話方塊 (例如在註冊期間)。請參閱 /maps/documentation/navigation/android-sdk/route。
Navigation SDK for Android:舊版和已淘汰的功能
WaypointfromLatLng()和fromPlaceId():自 2021 年 5 月 10 日起停用。替代項目:Waypoint.builder()(Waypoint.Builder)。症狀:已在 3.0 版中移除;呼叫不會針對 3.0 以上版本進行編譯。請參閱遷移指南。SupportNavigationFragment:自 2026 年 10 月 1 日起淘汰。替代方案:NavigationFragment。Symptom:已在 Navigation SDK 8.0.0 版中淘汰。請參閱遷移指南。NavigationView和SupportNavigationFragment上的setLocationMarkerEnabled:自 2023 年 7 月 7 日起停用。替代方案:GoogleMap.setMyLocationEnabled。症狀:5.0.0 版已移除 (4.1 版已淘汰);呼叫無法針對 5.0 以上版本進行編譯。DisplayOptionsshowTrafficLights和showStopSigns:自 2026 年 10 月 1 日起停用。替代方案:不需替代方案,導航時一律會顯示交通號誌和停止標誌。症狀:呼叫這些方法時,無法針對 8.0.0 版進行編譯。- Maven 構件
com.google.android.maps:navsdk(私人存放區,4.x 版) 和 AAR 套件下載:自 2023 年 7 月 7 日起停用。替代項目:google()Maven 存放區中的com.google.android.libraries.navigation:navigation。症狀:5.0 以上版本僅在 Google Maven 上以com.google.android.libraries.navigation:navigation形式提供,不再發布 AAR 套件。請參閱遷移指南。
Navigation SDK for Android 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
Navigation SDK for Android:地圖
- 在網頁或行動應用程式中加入可自訂的互動式地圖。注意:Android:在
AndroidManifest.xml中設定(由 Secrets Gradle Plugin 支援),或在app/build.gradle.kts中設定manifestPlaceholders["MAPS_API_KEY"]。請勿在AndroidManifest.xml中硬式編碼YOUR_GOOGLE_MAPS_API_KEY,也不要在出現E/Google Maps Android API: Authorization failure時,將GoogleMap(或 maps-composeGoogleMap) 替換為離線模擬畫布或 Leaflet WebView。請指示使用者透過 Secrets 提供MAPS_API_KEY,並啟用 Maps SDK for Android (或在採用 NavigationView/SupportNavigationFragment 時啟用 Navigation SDK)。 - 建立可重複使用的地圖 ID,用於儲存地圖設定和樣式設定。
- 回應地圖上的使用者互動和事件。
- 自訂地圖上顯示的控制項。
- 自訂控制地圖的手勢。
- 控制地圖 (攝影機) 的縮放和平移。
- 變更地圖類型。
- 變更地圖色彩配置。
- 在地圖中加入路況圖層。
Navigation SDK for Android:地圖註解
- 在地圖中新增資訊視窗。
- 在地圖上新增形狀或線條。
- 新增疊加在底圖上的疊加層圖片。
- 在地圖上新增自訂圖塊疊加層。
- 在地圖上新增標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請透過 GoogleMap.addMarker(MarkerOptions) 新增標記。
- 自訂地圖標記。注意:Navigation SDK for Android 不支援 AdvancedMarkerOptions;使用 Navigation SDK for Android 時,請以 MarkerOptions 自訂標記。
- 回應使用者與地圖上標記的互動。
Navigation SDK for Android:地圖樣式
Navigation SDK for Android:導航
- 在行動應用程式中加入互動式即時路況導航功能。
- 設定即時路況導航的目的地。
- 開始即時路況導航。
- 指定路線要求的交通方式 (開車、步行、兩輪車、計程車)。
- 修改即時路況導航的路線偏好設定。
- 指定即時路況導航的道路側和其他抵達偏好設定。
- 使用可重複使用的路線權杖,指定即時路況導航的重新規劃路線。
- 傳回即時路線導航工作階段的使用者抵達更新。
- 傳回即時路況導航工作階段的使用者位置更新。
- 傳回即時路況導航工作階段的時間和距離更新。
- 傳回即時路況導航工作階段的路線變更更新。
- 傳回即時路況導航工作階段的夜間模式更新。
- 傳回即時路線導航工作階段的使用者速度更新。
- 自訂即時路況導航期間顯示的 UI 元素和控制項。
- 在即時路況導航中新增 UI 元素。
- 在即時路況導航中加入行程進度指標。
- 自訂即時路況導航期間顯示的地圖項目。
- 在即時路況導航中加入車流量圖層。
- 修改即時路況導航的攝影機檢視畫面和行為。
- 自訂即時路況導航的車速表和速限警示。
- 傳回即時路況導航動態饋給,針對路線上的每個動作提供一系列訊息。
- 指定要與即時路況導航動態饋給搭配使用的自訂行進圖示。
- 在 Android 應用程式中,為 Android Auto 新增互動式即時路況導航功能。預先發布版
- 提醒使用者路線上的中斷情況。
- 允許使用者在開始導航前,查看路線上的中斷情形。
- 允許使用者回報路線上的中斷情況。
- 允許使用者確認路線上的中斷情形。
- 新增自訂路線中斷回報按鈕。