请按照本指南将 Navigation SDK for iOS 集成到 iOS 应用中。
前提条件
- 在开始使用 Navigation SDK for iOS 之前,请确保您的项目已关联结算帐号并且启用了 Maps SDK for iOS。我们建议创建多个项目所有者和结算管理员,确保您的团队中始终有人担任这些角色。如需了解详情,请参阅设置您的 Google Cloud 项目。
- 如需使用 Navigation SDK for iOS 构建项目,您需要 15.0 或更高版本的 Xcode。
- 导航 SDK 的最低目标 iOS 版本是 15.0。
第 1 步:安装 SDK
Swift Package Manager
Navigation SDK 可通过 Swift Package Manager 安装。如需添加 SDK,请确保您已移除所有现有的 Navigation SDK 依赖项。
要将 SDK 添加到新项目或现有项目,请按以下步骤操作:
-
打开 Xcode
project
或workspace
,然后前往 File(文件)> Add Package Dependencies(添加软件包依赖项)。 - 输入 https://github.com/googlemaps/ios-navigation-sdk 作为网址,按 Enter 键拉取软件包,然后点击“Add Package”(添加软件包)。
-
如需安装特定的
version
,请将依赖项规则字段设置为某个基于版本的选项。对于新项目,我们建议指定最新版本并使用“确切版本”选项。完成后,点击“添加文件包”。 -
在 Choose Package Products 窗口中,确认
GoogleNavigation
会添加到指定的main
目标。完成后,点击“添加软件包”。 -
如需验证安装,请前往目标的
General
窗格。在框架、库和嵌入式内容中,您应该会看到已安装的软件包。 您还可以查看“项目导航器”的“软件包依赖项”部分,以验证软件包及其版本。
如需更新现有项目的 package
,请按以下步骤操作:
如果要从 9.0.0 之前的版本升级,则必须在升级后移除以下依赖项:
GoogleMapsBase
、GoogleMapsCore
和GoogleMapsM4B
。请勿移除对GoogleMaps
的依赖项。如需了解详情,请参阅 9.0.0 版版本说明。在 Xcode 项目配置设置中,找到 Frameworks、Libraries, and Embedded Content。使用减号(-) 移除以下框架:
GoogleMapsBase
(仅适用于从 9.0.0 之前的版本升级而来)GoogleMapsCore
(仅适用于从 9.0.0 之前的版本升级而来)GoogleMapsM4B
(仅适用于从 9.0.0 之前的版本升级而来)
- 在 Xcode 中,转到“File(文件)> Packages”(软件包)>“Update To Latest Package Versions”(更新软件包版本)”。
- 如需验证安装,请前往项目导航器的软件包依赖项部分,验证软件包及其版本。
如需移除使用 CocoaPods
添加的现有 Navigation SDK 依赖项,请按以下步骤操作:
- 关闭 Xcode 工作区。打开终端并执行以下命令:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
如果您不将
Podfile
、Podfile.resolved
和 Xcodeworkspace
用于 CocoaPods 以外的其他用途,请移除它们。
-
在 Xcode 项目配置设置中,找到 Frameworks、Libraries, and Embedded Content。使用减号(-) 移除以下框架:
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
-
从 Xcode 项目的顶级目录中,移除
GoogleMaps
软件包。
CocoaPods
Navigation SDK for iOS 以 CocoaPods pod 的形式提供。 CocoaPods 是一种用于 Swift 和 Objective-C Cocoa 项目的开源依赖项管理器。
如果您尚未安装 CocoaPods 工具,请在 macOS 上从终端运行以下命令进行安装。如需了解详情,请参阅 CocoaPods 入门指南。
sudo gem install cocoapods
为 Navigation SDK for iOS 创建 Podfile
,并使用它来安装 API 及其依赖项:
- 如果您还没有 Xcode 项目,请立即创建一个并将其保存到您的本地机器。如果您是 iOS 开发新手:
- 创建新项目。
- 依次选择 iOS > 应用模板。
- 在项目选项屏幕上:
- 输入项目名称。
- 记录 Bundle identifier 字段的值。 您可以在下方使用该值来限制您的 API 密钥。
- 将项目 Interface 设置为 Storyboard。
- 将语言设置为 Swift 或 Objective-C。
- 在您的项目目录中创建一个名为
Podfile
的文件。此文件可定义您项目的依赖项。 - 修改
Podfile
并添加您的依赖项及其versions。以下示例包含 Navigation SDK for iOS 所需的依赖项: # Cocoapods 安装参考编号source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleNavigation', '9.0.0' end
确保定期运行pod outdated
以检测较新版本。如有必要,请升级到最新版本。 - 保存
Podfile
。 打开终端并转到包含
Podfile
的目录:cd <path-to-project>
运行
pod install
命令。这会安装Podfile
中指定的 API 以及所有依赖项。pod install
关闭 Xcode,然后打开(双击)您项目的
.xcworkspace
文件以启动 Xcode。从此刻开始,您必须使用.xcworkspace
文件打开项目。
如需更新现有项目的 API,请按以下步骤操作:
- 打开终端并转到包含
Podfile
的项目目录。 - 运行
pod update
命令。这会将Podfile
中指定的所有 API 更新到最新版本。
手动安装
本指南介绍了如何将包含 Navigation SDK for iOS 的 XCFrameworks 和 Maps SDK for iOS 手动添加到您的项目中,以及如何在 Xcode 中配置构建设置。XCFramework 是一个可在多个平台(包括使用 M1 芯片组的机器)上使用的二进制软件包
如需安装适用于 Navigation SDK for iOS 的 XCFrameworks 和 Maps SDK for iOS,请按以下步骤操作:
- 下载以下 SDK 二进制文件和资源文件:
- 启动 Xcode,并打开现有的项目或创建新项目。如果您是 iOS 新手,请创建一个新项目,然后选择 iOS App template(iOS 应用模板)。
- 从项目中移除所有现有的地图、导航和地点引用。
- 将以下 XCFrameworks 拖到 Frameworks、 Libraries, and Embedded Content 下,以便同时安装 Maps SDK 和 Navigation SDK(出现提示时,请选择 Copy items if needed):
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
- 将
GoogleMaps.bundle
从您下载的 GoogleMapsResources 拖到 Xcode 项目的顶层目录中。出现提示时,请确保选中 Copy items if needed。 - 将
GoogleNavigation.bundle
从您下载的 GoogleNavigationResources 拖到 Xcode 项目的顶级目录中。出现提示时,请确保已选中 Copy items into destination group's folder。 - 从项目导航器中选择您的项目,然后选择应用的目标。
- 打开 Build Phases(构建阶段)标签页,并在 Link Binary with Libraries(将二进制文件与库相关联)中添加以下框架和库:
Accelerate.framework
AudioToolbox.framework
AVFoundation.framework
Contacts.framework
CoreData.framework
CoreGraphics.framework
CoreImage.framework
CoreLocation.framework
CoreTelephony.framework
CoreText.framework
GLKit.framework
ImageIO.framework
libc++.tbd
libxml2.tbd
libz.tbd
Metal.framework
OpenGLES.framework
QuartzCore.framework
Security.framework
SystemConfiguration.framework
UIKit.framework
UserNotifications.framework
WebKit.framework
- 在应用的目标中,选择 Capabilities 标签页,开启 Background Modes(后台模式)并启用以下模式:
- 音频、AirPlay 和画中画
- 位置信息更新
- 选择您的项目(而不是特定目标),并打开 Build Settings 标签页。在 Other Linker Flags 部分中,为 debug 和 release 添加
‑ObjC
。 如果看不到这些设置,请将 Build Settings 栏中的过滤条件从 Basic 更改为 All。 - 打开
Info.plist
并添加以下键值对:- 键:
NSLocationWhenInUseUsageDescription
(隐私权 - 使用时的位置信息说明)
值:“此应用需要获得相关权限才能使用您的位置信息进行精细导航。” - 键:
NSLocationAlwaysAndWhenInUseUsageDescription
(“隐私权 - 始终使用位置信息以及使用时的位置信息”说明)
值:“此应用需要获得相关权限才能使用您的位置信息进行精细导航。”
- 键:
第 2 步:检查 Apple 隐私清单文件
Apple 要求针对 App Store 中的应用提供应用隐私权详细信息。如需了解最新动态和更多信息,请访问 Apple App Store 隐私权详细信息页面。
Apple 隐私清单文件包含在 SDK 的资源包中。如需验证是否已包含 Privacy 清单文件并检查其内容,请为您的应用创建归档,并根据该归档生成隐私报告。
第 3 步:向您的项目添加 API 密钥
以下示例展示了如何在 Xcode 中为您的项目添加 API 密钥:
Swift
按照以下方法向 AppDelegate.swift
添加 API 密钥:
- 添加以下 import 语句:
import GoogleMaps import GoogleNavigation
- 将以下代码添加到
application(_:didFinishLaunchingWithOptions:)
方法中:GMSServices.provideAPIKey("YOUR_API_KEY")
Objective-C
按照以下方法向 AppDelegate.m
添加 API 密钥:
- 添加以下 import 语句:
@import GoogleMaps; @import GoogleNavigation;
- 将以下代码添加到
application:didFinishLaunchingWithOptions:
方法中:[GMSServices provideAPIKey:@"YOUR_API_KEY"];
第 4 步:添加地图
此代码演示了如何向现有 ViewController
添加简单的地图,其中包括一些导航初始设置。
用户必须同意条款及条件,然后才能启用导航。如需提示用户,请调用 GMSNavigationServices.showTermsAndConditionsDialogIfNeeded()
,然后检查用户是否已接受条款。如果用户拒绝这些条款,mapView.isNavigationEnabled = true
不会产生任何效力,且 mapView.navigator
为 nil。
Swift
import UIKit import GoogleNavigation class ViewController: UIViewController { var mapView: GMSMapView! var locationManager: CLLocationManager! override func loadView() { locationManager = CLLocationManager() locationManager.requestAlwaysAuthorization() let camera = GMSCameraPosition.camera(withLatitude: 47.67, longitude: -122.20, zoom: 14) mapView = GMSMapView.map(withFrame: CGRect.zero, camera: camera) // Show the terms and conditions. let companyName = "Ride Sharing Co." GMSNavigationServices.showTermsAndConditionsDialogIfNeeded( withCompanyName: companyName) { termsAccepted in if termsAccepted { // Enable navigation if the user accepts the terms. self.mapView.isNavigationEnabled = true } else { // Handle the case when the user rejects the terms and conditions. } } view = mapView } // TODO: Add navigation code. }
Objective-C
#import "ViewController.h" @import GoogleNavigation; @interface ViewController () @end @implementation ViewController GMSMapView *_mapView; CLLocationManager *_locationManager; - (void)loadView { _locationManager = [[CLLocationManager alloc] init]; [_locationManager requestAlwaysAuthorization]; GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.67 longitude:-122.20 zoom:14]; _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera]; // Show the terms and conditions. NSString *companyName = @"Ride Sharing Co."; [GMSNavigationServices showTermsAndConditionsDialogIfNeededWithCompanyName:companyName callback:^(BOOL termsAccepted) { if (termsAccepted) { // Enable navigation if the user accepts the terms. _mapView.navigationEnabled = YES; } else { // Handle the case when the user rejects the terms and conditions. } }]; self.view = _mapView; } // TODO: Add navigation code. @end
运行应用。您应该会看到一张以华盛顿州柯克兰为中心的地图。 如果看不到地图,请确认您提供的 API 密钥是否正确。
如果您是移动服务客户
如果您是移动服务客户,请参阅移动文档了解结算方式。如需详细了解如何记录交易,请参阅设置结算信息。如需了解如何向 Navigation SDK 实现添加交易 ID,请参阅将您的服务使用情况与 Mobility 交易相关联。