Navigation SDK for iOS 可将 Google 地图精细导航功能添加到 iOS 应用中,并提供界面自定义和路线配置功能。它扩展了 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 地图精细导航功能,以便用户无需切换应用。
- 您需要在导航期间自定义导航界面、地图样式、镜头或布局,以契合您的品牌。
- 您需要使用 Routes API 或 Route Optimization API 中的路线偏好设置、多个航点或路线令牌。
- 您需要行程事件(位置、到达、路线变更、预计到达时间)或精细导航数据 Feed,才能实现自定义导航界面或 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(隐私 - 动作使用说明)添加到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:导航
- 向移动应用添加交互式精细导航。
- 设置精细导航的目的地。
- 开始精细导航。
- 为路线请求指定出行方式(驾车、步行、双轮机动车、出租车)。
- 修改精细导航的路线偏好设置。
- 为精细导航指定道路一侧和其他到达偏好设置。
- 使用可重复使用的路线令牌为精细导航指定重新规划的路线。
- 从精细导航会话中返回用户到达更新。
- 从精细导航会话中返回用户位置信息更新。
- 返回精细导航会话中的时间和距离更新。
- 从精细导航会话返回路线变更更新。
- 返回精细导航会话中的夜间模式更新。
- 返回精细导航会话中的用户速度更新。
- 自定义精细导航期间显示的界面元素和控件。
- 向精细导航添加新的界面元素。
- 向精细导航添加行程进度指示器。
- 自定义精细导航期间显示的地图项。
- 在精细导航中添加路况图层。
- 修改精细导航的镜头视图和行为。
- 自定义精细导航的车速表和限速提醒。
- 以一系列消息的形式返回精细导航 Feed,其中包含沿路线的每个操作。
- 指定要与精细导航 Feed 搭配使用的自定义操作图标。
- 为 iOS 应用添加适用于 CarPlay 的交互式精细导航。预览版
- 提醒用户注意沿途的交通中断情况。
- 允许用户在开始导航之前查看沿途的交通中断情况。
- 允许用户报告其路线上的中断情况。
- 允许用户验证其路线上的中断情况。
- 添加自定义路线中断报告按钮。