設定專案

請按照本指南的說明,將適用於 iOS 的 Navigation SDK 整合至 iOS 應用程式。

先備知識

  • 您必須擁有已連結帳單帳戶的專案,並啟用 Maps SDK for iOS,才能開始使用 Navigation SDK for iOS。建議您建立多個專案擁有者和帳單管理員,這樣您的團隊隨時都有擔任這些角色的成員可處理相關事務。詳情請參閱「設定 Google Cloud 專案」一文。
  • 如要使用 Navigation SDK for iOS 建立專案,需要使用 Xcode 15.0 版或更新版本。
  • 導覽 SDK 的最低目標 iOS 版本為 15.0。

步驟 1:安裝 SDK

Swift 套件管理工具

您可以透過 Swift 套件管理工具安裝 Navigation SDK。如要新增 SDK,請確認您已移除所有現有的 Navigation SDK 依附元件。

如要將 SDK 加入新專案或現有專案,請按照下列步驟操作:

  1. 開啟 Xcode projectworkspace,然後依序前往「File」>「Add Package Dependencies」
  2. 輸入 https://github.com/googlemaps/ios-navigation-sdk 做為網址,按下 Enter 鍵提取套件,然後按一下「Add Package」。
  3. 如要安裝特定的 version,請將「依附元件規則」欄位設為其中一個以版本為基礎的選項。如果是新專案,建議您指定最新版本並使用「精確版本」選項。完成後,按一下「新增套件」。
  4. 在「選擇套件產品」視窗中,確認 GoogleNavigation 會新增至指定的 main 目標。完成後,按一下「新增套件」。
  5. 如要驗證安裝狀態,請前往目標的 General 窗格。在「Frameworks、Library and Embedded Content」中應會顯示已安裝的套件。您也可以查看「Project Navigator」的「Package Dependencies」部分,確認套件及其版本。

如要更新現有專案的 package,請按照下列步驟操作:

  1. 如果您要從 9.0.0 以下版本升級,必須在升級後移除下列依附元件:GoogleMapsBaseGoogleMapsCoreGoogleMapsM4B。請勿移除 GoogleMaps 的依附元件。詳情請參閱 9.0.0 版本資訊

    在 Xcode 專案設定設定中,找到「Frameworks、Library 和 Embedded Content」。請使用減號(-) 移除下列架構:

    • GoogleMapsBase (僅適用於 9.0.0 以下版本的升級作業)
    • GoogleMapsCore (僅適用於 9.0.0 以下版本的升級作業)
    • GoogleMapsM4B (僅適用於 9.0.0 以下版本的升級作業)
  2. 在 Xcode 中,前往 [檔案] > [套件] > [更新至最新套件版本]。
  3. 如要驗證安裝狀態,請前往「Project Navigator」的「Package Dependencies」部分,檢查套件及其版本。

如要移除使用 CocoaPods 新增的現有 Navigation SDK 依附元件,請按照下列步驟操作:

  1. 關閉 Xcode 工作區。開啟終端機並執行下列指令:
    sudo gem install cocoapods-deintegrate cocoapods-clean 
    pod deintegrate 
    pod cache clean --all
  2. 如果您未在 CocoaPods 以外的地方使用 PodfilePodfile.resolved 和 Xcode workspace,請移除這些項目。

如要移除已手動安裝的 iOS 版 Navigation SDK,請按照下列步驟操作:
  1. 在 Xcode 專案設定設定中,找到「Frameworks、Library 和 Embedded Content」。請使用減號(-) 移除下列架構:
    • GoogleMaps.xcframework
    • GoogleMapsBase.xcframework
    • GoogleMapsCore.xcframework
    • GoogleNavigation.xcframework
  2. 在 Xcode 專案的頂層目錄中,移除 GoogleMaps 軟體包。

CocoaPods

iOS 版 Navigation SDK 以 CocoaPods Pod 的形式提供。CocoaPods 是一種適用於 Swift 和 Objective-C Cocoa 專案的開放原始碼依附元件管理員。

如果您還沒有 CocoaPods 工具,請在終端機上執行下列指令,即可在 macOS 中安裝這項工具。詳情請參閱 CocoaPods 入門指南

sudo gem install cocoapods

為 Navigation SDK for iOS 建立 Podfile,並使用該 SDK 安裝 API 及其依附元件:

  1. 如果您尚未建立 Xcode 專案,請立即建立專案,並儲存至本機電腦。如果您是 iOS 開發新手:
    1. 建立新專案。
    2. 依序選取「iOS」>「App」範本。
    3. 在專案選項畫面中:
      1. 輸入專案名稱
      2. 記錄「Bundle ID」欄位的值。您可以在下方使用該值限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」或「Objective-C」
  2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
  3. 編輯 Podfile,新增依附元件及其versions。以下範例包含適用於 iOS 的 Navigation SDK 依附元件: # 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 以偵測較新版本。如有需要,請升級至最新版本
  4. 儲存 Podfile
  5. 開啟終端機並前往包含 Podfile 的目錄:

    cd <path-to-project>
  6. 執行 pod install 指令。這會安裝 Podfile 中指定的 API 以及所有依附元件。

    pod install
  7. 關閉 Xcode,接著按兩下來開啟專案的 .xcworkspace 檔案來啟動 Xcode。從現在起,您必須使用 .xcworkspace 檔案來開啟專案。

如要更新現有專案的 API,請按照下列步驟操作:

  1. 開啟終端機,然後前往包含 Podfile 的專案目錄。
  2. 執行 pod update 指令。這會將 Podfile 中指定的所有 API 更新為最新版本。

手動安裝程式庫

本指南說明如何在專案中手動新增包含 Navigation SDK for iOS 的 XCFrameworks 以及 Maps SDK for iOS,並在 Xcode 中設定建構設定。XCFramework 是一種二進位套件,可用於多種平台,包括使用 M1 晶片組的機器

請按照下列步驟安裝 Navigation SDK for iOS 和 Maps SDK for iOS 的 XCFrameworks:

  1. 下載下列 SDK 二進位檔和資源檔案:
  2. 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是 iOS 新手,請建立新專案並選取「iOS App Template」
  3. 從專案中移除所有現有的地圖、導航和地點參照。
  4. 將下列 XCFrameworks 拖曳到專案「Frameworks、Library and Embedded Content」下方,並安裝 Maps SDK 和 Navigation SDK (系統提示時,請選取「複製所需項目」):
    • GoogleMaps.xcframework
    • GoogleMapsBase.xcframework
    • GoogleMapsCore.xcframework
    • GoogleNavigation.xcframework
  5. 將您下載的 GoogleMapsResources 中的 GoogleMaps.bundle 拖曳到 Xcode 專案的頂層目錄。系統提示時,請確保已選取 [Copy items if needed]
  6. 將下載的 GoogleNavigationResources 中的 GoogleNavigation.bundle 拖曳至 Xcode 專案的頂層目錄。系統提示時,請務必選取 [Copy items to destination group's folder]
  7. 從專案導覽器中選取專案,然後選擇應用程式目標。
  8. 開啟「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
  9. 在應用程式的目標中選取「Capabilities」分頁標籤,開啟「Background Modes」,然後啟用下列模式:
    • 音訊、AirPlay 和子母畫面
    • 最新位置
  10. 選擇您的專案 (而非特定目標),然後開啟「Build Settings」分頁。在「Other Linker Flags」區段中,為 debugrelease 新增 ‑ObjC。如未顯示這些設定,請將「Build Settings」列中的篩選器從「Basic」變更為「All」
  11. 開啟 Info.plist 並新增下列鍵/值組合:
    • 索引鍵: NSLocationWhenInUseUsageDescription (「隱私權 - 使用時位置資訊」說明)
      值:「這個應用程式需要相關權限,才能使用即時路線導航功能。」
    • 索引鍵: NSLocationAlwaysAndWhenInUseUsageDescription (隱私權 - 一律定位和使用時說明)
      值:「這個應用程式需要存取你的位置資訊,才能使用即時路線導航功能。」

步驟 2:檢查 Apple 隱私權資訊清單檔案

Apple 要求在 App Store 上架應用程式,要求取得應用程式隱私權詳細資訊。如需最新資訊和其他資訊,請前往 Apple App Store 隱私權詳細資料頁面

Apple 隱私權資訊清單檔案包含在 SDK 資源套件中。如要確認隱私權資訊清單檔案已納入並檢查其中的內容,請建立應用程式的封存檔案,然後從封存檔中產生隱私權報告

步驟 3:在專案中新增 API 金鑰

以下範例說明如何在 Xcode 中將 API 金鑰加進專案:

Swift

將 API 金鑰新增到您的 AppDelegate.swift 中,如下所示:

  1. 新增下列匯入陳述式:
    import GoogleMaps
    import GoogleNavigation
  2. 請將以下內容新增到 application(_:didFinishLaunchingWithOptions:) 方法:
    GMSServices.provideAPIKey("YOUR_API_KEY")

Objective-C

將 API 金鑰新增到您的 AppDelegate.m 中,如下所示:

  1. 新增下列匯入陳述式:
    @import GoogleMaps;
    @import GoogleNavigation;
  2. 請將以下內容新增到 application:didFinishLaunchingWithOptions: 方法:
    [GMSServices provideAPIKey:@"YOUR_API_KEY"];

步驟 4:新增地圖

這段程式碼示範如何在現有的 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 金鑰正確無誤。

如果您是行動管理服務客戶

如果您是 Mobility Services 客戶,請參閱行動性說明文件,瞭解帳單相關資訊。如要進一步瞭解如何記錄交易,請參閱「設定帳單資訊」。如要瞭解如何在 Navigation SDK 實作中加入交易 ID,請參閱「將服務使用情形與行動交易交易建立關聯」。