請依照本指南,將 iOS 版 Navigation SDK 整合至 iOS 應用程式。
必要條件
- 您必須擁有已連結帳單帳戶的專案,並啟用 Maps SDK for iOS,才能開始使用 iOS 版 Navigation SDK。建議您建立多個專案擁有者和帳單管理員,這樣您的團隊隨時都有擔任這些角色的成員可處理相關事務。詳情請參閱「設定 Google Cloud 專案」一文。
- 如要使用 iOS 版 Navigation SDK 建構專案,需使用 Xcode 15.0 以上版本。
- Navigation SDK 的最低目標 iOS 版本為 14.0。
安裝 SDK
Swift 套件管理員
您可以透過 Swift Package Manager 安裝 Navigation SDK。如要新增 SDK,請確認您已移除所有現有的 Navigation SDK 依附元件。
如要將 SDK 加入新專案或現有專案,請按照下列步驟操作:
-
開啟 Xcode
project
或workspace
,然後依序前往「File」>「Add Package Dependencies」。 - 在網址中輸入 https://github.com/googlemaps/ios-navigation-sdk,按下 Enter 鍵擷取套件,然後按一下「新增套件」。
-
如要安裝特定
version
,請將「Dependency Rule」欄位設為其中一個版本型選項。如果是新專案,建議您指定最新版本並使用「精確版本」選項。完成後,按一下 [Add Package]。 -
在「Choose Package Products」視窗中,確認
GoogleNavigation
會新增至您指定的main
目標。完成後,按一下「Add Package」。 -
如要驗證安裝,請前往目標的
General
窗格。「Frameworks、程式庫和嵌入的內容」應該會顯示已安裝的套件。 您也可以查看「Project Navigator」的「Package Dependencies」部分,確認套件及其版本。
如要更新現有專案的 package
,請按照下列步驟操作:
- 在 Xcode 中,依序前往「File」>「Packages」>「Update to Package Versions」。
- 如要驗證安裝,請前往「Project Navigator」的「Package Dependencies」部分,驗證套件及其版本。
如要移除使用 CocoaPods
新增的現有 Navigation SDK 依附元件,請按照下列步驟操作:
- 關閉 Xcode 工作區。開啟終端機並執行下列指令:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
如果不想將
Podfile
、Podfile.resolved
和 Xcodeworkspace
用於 CocoaPods 以外的任何產品,請移除。
-
在 Xcode 專案設定中,尋找「Frameworks、程式庫和內嵌內容」。使用減號(-) 移除下列架構:
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
-
從 Xcode 專案的頂層目錄中,移除
GoogleMaps
套件。
CocoaPods
iOS 版 Navigation SDK 以 CocoaPods Pod 的形式提供。CocoaPods 是一種適用於 Swift 和 Objective-C Cocoa 專案的開放原始碼依附元件管理員。
如果您還沒有 CocoaPods 工具,請在終端機上執行下列指令,即可在 macOS 中安裝這項工具。詳情請參閱 CocoaPods 入門指南。
sudo gem install cocoapods
為 iOS 版 Navigation SDK 建立 Podfile
,然後用來安裝 API 及其依附元件:
- 如果您還沒有 Xcode 專案,請立即建立專案,並儲存至本機電腦。如果您是 iOS 開發新手:
- 建立新專案。
- 依序選取「iOS」>「App」範本。
- 在專案選項畫面中:
- 在「Project Name」中輸入專案名稱。
- 記錄「Bundle ID」欄位的值。您可以使用該值來限制下方的 API 金鑰。
- 將專案「Interface」設為「Storyboard」。
- 將「Language」(語言) 設為「Swift」或「Objective-C」。
- 在專案目錄中建立名為
Podfile
的檔案。這個檔案定義了專案的依附元件。 - 編輯
Podfile
,然後新增依附元件及其versions。以下範例包含 Navigation SDK for iOS 所需的依附元件: # Cocoapods 安裝參考編號 #source 'https://github.com/CocoaPods/Specs.git' platform :ios, '14.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleNavigation', '5.3.1' 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 晶片組的機器
請按照下列步驟,安裝適用於 iOS 版 Navigation SDK 和 Maps SDK for iOS 的 XCFrameworks:
- 下載下列 SDK 二進位檔和資源檔案:
- 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是 iOS 新手,請建立新專案並選取「iOS App Template」。
- 從專案中移除所有現有的地圖、導覽和地點參照。
- 將下列 XCFrameworks 拖曳至「架構、程式庫和嵌入的內容」下方的專案中,即可同時安裝地圖和 Navigation SDK (系統顯示提示時,請選取「Copy items if needed」):
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
- 將您下載的 GoogleMapsResources 中的
GoogleMaps.bundle
拖曳到 Xcode 專案的頂層目錄。系統提示時,請務必選取「Copy items if needed」。 - 將您下載的 GoogleNavigationResources 中的
GoogleNavigation.bundle
拖曳到 Xcode 專案的頂層目錄。出現提示訊息時,請確認已選取「將項目複製到目的地群組的資料夾」。 - 從「Project Navigator」中選取專案,並選擇應用程式的目標。
- 開啟「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
- 在應用程式的目標中選取「功能」分頁標籤,開啟「背景模式」,並啟用下列模式:
- 音訊、AirPlay 和子母畫面
- 最新位置
- 選擇您的專案 (而不是特定目標),然後開啟「Build Settings」分頁。在「Other Linker Flags」部分中,為「debug」和「release」新增
‑ObjC
。如果沒有看到這些設定,請將「Build Settings」列中的篩選器從「Basic」變更為「All」。 - 開啟
Info.plist
並新增下列鍵/值組合:- 鍵:
NSLocationWhenInUseUsageDescription
(「使用隱私 - 使用時的位置資訊」)
值:「這個應用程式需要取得位置資訊才能使用即時路線導航功能。」 - 鍵:
NSLocationAlwaysAndWhenInUseUsageDescription
(「隱私權 - 位置永遠和使用時」說明)
值:「這個應用程式需要取得位置資訊才能使用即時路線導航功能。」
- 鍵:
新增 Apple 隱私權資訊清單檔案
- 下載適用於 iOS 的 Navigation SDK 隱私權資訊清單套件:GoogleNavigationPrivacy。
- 解壓縮檔案即可存取
GoogleNavigationPrivacy.bundle
。 - 使用其中一種方法,將
GoogleNavigationPrivacy.bundle
新增至 Xcode 專案導覽器。確認您已針對應用程式的目標勾選「新增至目標」方塊。新增後,PrivacyInfo 檔案會顯示在專案導覽器中,方便您檢查相關值。 - 請建立應用程式封存檔,然後從封存檔案產生隱私權報告,確認已新增隱私權資訊清單。
在專案中新增 API 金鑰
以下範例說明如何在 Xcode 中將 API 金鑰新增至專案:
Swift
將 API 金鑰新增到您的 AppDelegate.swift
中,如下所示:
- 新增下列匯入陳述式:
import GoogleMaps import GoogleNavigation
- 請將以下內容加入
application(_:didFinishLaunchingWithOptions:)
方法中:GMSServices.provideAPIKey("YOUR_API_KEY")
Objective-C
將 API 金鑰新增到您的 AppDelegate.m
中,如下所示:
- 新增下列匯入陳述式:
@import GoogleMaps; @import GoogleNavigation;
- 請將以下內容加入
application:didFinishLaunchingWithOptions:
方法中:[GMSServices provideAPIKey:@"YOUR_API_KEY"];
新增地圖
這個程式碼示範如何在現有的 ViewController
中新增簡易地圖,包括一些導覽的初始設定。
使用者必須同意條款及細則,才能啟用導覽。如要提示使用者,請呼叫 GMSNavigationServices.showTermsAndConditionsDialogIfNeeded()
,然後檢查是否已接受條款。如果使用者拒絕條款,mapView.isNavigationEnabled = true
不會有任何作用,mapView.navigator
則不會。
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 金鑰是否正確。
如果您是行動管理服務客戶
如果您是行動管理服務客戶,請參閱「行動管理服務」說明文件中的計費方式。如要進一步瞭解如何記錄交易,請參閱「設定帳單資訊」。如要瞭解如何將交易 ID 新增至 Navigation SDK 實作項目,請參閱「將服務使用情形與行動性交易建立關聯」一文。