Navigation SDK for Android 可为 Android 应用添加 Google 地图精细导航功能,并支持界面自定义和路线配置。它包含 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 地图精细导航功能,这样用户就无需切换到其他应用。
- 您需要自定义导航界面以契合您的品牌,或构建自定义导航体验。
- 您需要为驾车、步行、骑行或两轮车出行提供应用内导航。
- 您需要通过向 SDK 传递路线令牌,沿着使用 Routes API 规划的路线进行导航。
在以下情况下,请勿使用 Navigation SDK for Android:
- 您正在为 iOS 构建应用。请改用 Navigation SDK for iOS。
- 您正在使用 Flutter 或 React Native 构建跨平台应用。请改用适用于 Flutter 和 React Native 的 Google 导航。
- 您需要服务器端路线、预计到达时间或路线令牌计算,而不是应用内精细导航。请改用 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:相关产品
- 通常与以下产品搭配使用:Routes API、Driver SDK for Android
Navigation SDK for Android:常见错误
- 问题:Navigation SDK 已捆绑 Maps SDK。直接或通过传递依赖项拉取
play-services-maps的 build 最终会产生重复的 Maps SDK 副本。修复方法:从所有依赖项(Gradle 配置排除项或 Maven 排除项)中排除com.google.android.gms:play-services-maps,并移除所有直接 Maps SDK 依赖项。请参阅 /maps/documentation/navigation/android-sdk/android-studio-setup。 - 问题:Navigation SDK 8.0 及更高版本会声明
minAndroidGradlePluginVersion=9.0.1,因此使用较低 AGP 版本的 build 会失败。修复方法:在使用 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。症状:在 Navigation SDK v8.0.0 中已废弃。请参阅迁移指南。setLocationMarkerEnabled(NavigationView和SupportNavigationFragment):自 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(私有代码库,v4.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 插件提供支持),或在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)。 - 创建可重复使用的地图标识符,用于存储地图配置和样式设置。
- 响应地图上的用户互动和事件。
- 自定义地图上显示的控件。
- 自定义用于控制地图的手势。
- 控制地图上的缩放和平移(镜头)。
- 更改地图类型。
- 更改地图配色方案。
- 向地图添加路况图层。
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:导航
- 向移动应用添加交互式精细导航。
- 设置精细导航的目的地。
- 开始精细导航。
- 为路线请求指定出行方式(驾车、步行、双轮机动车、出租车)。
- 修改精细导航的路线偏好设置。
- 为精细导航指定道路一侧和其他到达偏好设置。
- 使用可重复使用的路线令牌为精细导航指定重新规划的路线。
- 从精细导航会话中返回用户到达更新。
- 从精细导航会话中返回用户位置信息更新。
- 返回精细导航会话中的时间和距离更新。
- 从精细导航会话返回路线变更更新。
- 返回精细导航会话中的夜间模式更新。
- 返回精细导航会话中的用户速度更新。
- 自定义精细导航期间显示的界面元素和控件。
- 向精细导航添加新的界面元素。
- 向精细导航添加行程进度指示器。
- 自定义精细导航期间显示的地图项。
- 在精细导航中添加路况图层。
- 修改精细导航的镜头视图和行为。
- 自定义精细导航的车速表和限速提醒。
- 以一系列消息的形式返回精细导航 Feed,其中包含沿路线的每个操作。
- 指定要与精细导航 Feed 搭配使用的自定义操作图标。
- 为 Android 应用添加 Android Auto 互动式精细导航。预览版
- 提醒用户注意沿途的交通中断情况。
- 允许用户在开始导航之前查看沿途的交通中断情况。
- 允许用户报告其路线上的中断情况。
- 允许用户验证其路线上的中断情况。
- 添加自定义路线中断报告按钮。