設定 Xcode 專案

啟用計費功能並建立 API 金鑰後，即可設定要用來開發應用程式的 Xcode 專案。

每個版本都有版本資訊。

步驟 1：安裝必要軟體

如要使用 Navigation SDK for iOS 建構專案，請務必下載並安裝：

• Xcode 26.0 以上版本

步驟 2：建立 Xcode 專案並安裝 Navigation SDK

Swift Package Manager

您可以透過 Swift Package Manager 安裝 Navigation SDK。如要新增 SDK，請務必移除所有現有的 Navigation SDK 依附元件。

如要將 SDK 新增至新專案或現有專案，請按照下列步驟操作：

1. 開啟 Xcode project 或 workspace，然後依序前往「File」>「Add Package Dependencies」。
2. 輸入 https://github.com/googlemaps/ios-navigation-sdk 做為網址，按下 Enter 鍵提取套件，然後按一下「Add Package」。
3. 如要安裝特定 version，請將「Dependency Rule」欄位設為其中一個版本選項。如果是新專案，建議指定最新版本，並使用「Exact Version」選項。完成後，按一下「新增套裝方案」。
4. 在「Choose Package Products」視窗中，確認 GoogleNavigation 會新增至指定的 main 目標。完成後，按一下「新增套裝方案」。
5. 如要驗證安裝，請前往目標的「General」窗格。 在「Frameworks, Libraries, and Embedded Content」中，您應該會看到已安裝的套件。 您也可以查看「Project Navigator」的「Package Dependencies」部分，確認套件及其版本。

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

1. 在 Xcode 中，依序前往「File」(檔案) >「Packages」(套件) >「Update To Latest Package Versions」(更新至最新套件版本)。
2. 如要驗證安裝，請前往「Project Navigator」的「Package Dependencies」部分，驗證套件及其版本。

重要事項：有時構件無法解析或可能發生錯誤，在這種情況下，請依序選取「File」>「Packages」>「Reset Package Cache」。

如要移除手動安裝的現有 Navigation SDK for iOS，請按照下列步驟操作：

1. 在 Xcode 專案設定中，找出「Frameworks, Libraries, and Embedded Content」。使用減號(-) 移除下列架構：
   • GoogleMaps.xcframework
   • GoogleNavigation.xcframework
2. 從 Xcode 專案的頂層目錄中，移除 GoogleMaps 組合。

手動安裝程式庫

本指南說明如何手動將包含 Navigation SDK for iOS 和 Maps SDK for iOS 的 XCFrameworks 新增至專案，並在 Xcode 中調整建構設定。XCFramework 是二進位檔套件，可在多個平台上使用，包括採用 M1 晶片組的機器

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

1. 下載下列 SDK 二進位檔和資源檔案：
   • GoogleMaps
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. 啟動 Xcode，接著開啟現有專案，或建立新專案。如果您是 iOS 新手，請建立新專案，然後選取「iOS App template」(iOS 應用程式範本)。
3. 從專案中移除所有現有的 Maps、Navigation 和 Places 參照。
   重要事項：Navigation SDK for iOS 不含 Places SDK for iOS，必須另外安裝。Places SDK for iOS 5.0 版起即是如此。Google 建議您下載並安裝相同版本的 Places SDK for iOS 和 Navigation SDK for iOS。請參閱「安裝 Places SDK for iOS」。
4. 將下列 XCFrameworks 拖曳至專案的「Frameworks, Libraries, and Embedded Content」下方，即可同時安裝 Maps 和 Navigation SDK (出現提示時，請選取「Copy items if needed」)：
   • GoogleMaps.xcframework
   • GoogleNavigation.xcframework
5. 將 GoogleMaps.bundle 從下載的 GoogleMapsResources 拖曳至 Xcode 專案的頂層目錄。出現提示時，請確認已選取「Copy items if needed」。
6. 將 GoogleNavigation.bundle 從下載的 GoogleNavigationResources 拖曳至 Xcode 專案的頂層目錄。系統提示時，請確認已選取「將項目複製到目的地群組的資料夾」。
7. 在「Project Navigator」中選取專案，然後選擇應用程式的目標。
8. 開啟「Build Phases」分頁，然後在「Link Binary with Libraries」中新增下列架構和程式庫：
   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • CarPlay.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
   • MapKit.framework
   • 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」部分，為「debug」和「release」新增 ‑ObjC。如果看不到這些設定，請將「Build Settings」列中的篩選器從「Basic」變更為「All」。
    重要事項：SDK 包含 Swift 符號。如果您建立的是純 Objective-C 專案，也必須在專案中建立空白的 .swift 檔案，或在 Xcode 專案的「Other Linker Flags」部分加入下列內容。

    -L$(DEVELOPER_DIR)/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/$(PLATFORM_NAME)

11. 開啟 Info.plist 並新增下列鍵/值組合：
    • 鍵： NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)
      值：「這個應用程式需要權限，才能使用您的位置資訊提供即時路況導航。」
    • 鍵： NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description)
      值：「這個應用程式需要位置資訊存取權，才能提供即時路況導航。」

步驟 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 (選用)：檢查 Apple 隱私權資訊清單檔案

注意：以下內容適用於將應用程式部署至線上應用程式商店的情況。

Apple 規定，在 App Store 上架的應用程式必須提供隱私權詳細資料。如需最新資訊和詳情，請造訪 Apple App Store 隱私權詳細資料頁面。

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

如果您是 Mobility Services 客戶

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

後續步驟

您已取得 API 金鑰並設定 Xcode 專案，接下來可以建立並執行應用程式。Navigation SDK for iOS 提供教學課程，協助您踏出第一步。相關詳情請參閱：

• 教學課程
  • 沿著路線導航
  • 監聽導覽事件
• 使用 App Check 保護 API 金鑰
• 程式碼範例和程式碼實驗室