設定 Xcode 專案

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

每個版本都有版本資訊。

步驟 1：安裝必要軟體

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

• Xcode 26.0 以上版本

步驟 2：建立 Xcode 專案並安裝 Maps SDK for iOS

注意： Maps SDK for iOS 會為特定裝置製作的應用程式，增加平均 5.7 MB 的 IPA 大小。通用應用程式的下載大小可能較大。

SDK 安裝大小不一。舉例來說，Maps SDK for iOS 9.0 版的安裝大小約為 18 MB。

注意： 自 9.2.0 版起，GoogleMapsCore 和 GoogleMapsBase 已合併至 GoogleMaps XCFramework。您不需要額外進行設定。

Maps SDK for iOS 目前不支援可合併程式庫。為避免在發布子版本時發生連結器錯誤，請確認 Xcode 專案中的「Build Mergeable Library」設定設為「No」 (預設值)。

Swift Package Manager

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

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

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

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

1. 如果您是從 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 以下版本升級)
2. 在 Xcode 中，依序前往「File」>「Packages」>「Update To Latest Package Versions」。
3. 如要驗證安裝，請前往「Project Navigator」的「Package Dependencies」部分，驗證套件及其版本。

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

如要移除使用 CocoaPods 新增的現有 Maps SDK for iOS 依附元件，請按照下列步驟操作：

1. 關閉 Xcode 工作區。開啟終端機並執行下列指令：

   sudo gem install cocoapods-deintegrate cocoapods-clean
   pod deintegrate
   pod cache clean --all

2. 如果您只在 CocoaPods 使用 Podfile、Podfile.resolved 和 Xcode workspace，請移除這些項目。

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

1. 在 Xcode 專案設定中，找出「Frameworks, Libraries, and Embedded Content」。使用減號 (-) 移除下列架構：
   • GoogleMaps
   • GoogleMapsBase (僅適用於 9.2.0 以下版本)
   • GoogleMapsCore (僅適用於 9.2.0 以下版本)
   • GoogleMapsM4B (僅適用於 9.0.0 以下版本)
2. 從 Xcode 專案的頂層目錄中，移除 GoogleMaps 組合。

手動安裝

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

1. 下載下列 SDK 二進位檔和資源檔案：
   • GoogleMaps
   • GoogleMapsResources
2. 解壓縮檔案，即可存取 XCFrameworks 和資源。
3. 如果尚未建立 Xcode 專案，請立即建立並儲存至本機電腦。如果您是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「App」範本。
   3. 在專案選項畫面中：
      1. 輸入專案名稱。
      2. 記下「軟體包 ID」欄位的值。您可以使用該值，在下方限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」。
      4. 將「Language」設為「Swift」或「Objective-C」。
4. 開啟「一般」分頁。將下列 XCFrameworks 拖曳至專案的「Frameworks, Libraries, and Embedded Content」下方。請務必選取「Do Not Embed」：
   • GoogleMaps.xcframework
5. 將 GoogleMaps.bundle 從下載的 GoogleMapsResources 複製到 Xcode 專案的頂層目錄。系統提示時，請務必選取「Copy items into destination group's folder」(將項目複製到目的地群組的資料夾)。
6. 在「Project Navigator」中選取專案，然後選擇應用程式的目標。
7. 開啟應用程式目標的「Build Phases」分頁。 在「Link Binary with Libraries」中，新增下列架構和程式庫：
   • Accelerate.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • MetricKit.framework
   • OpenGLES.framework (僅限使用 OpenGL 時)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. 選擇專案 (而非特定目標)，然後開啟「Build Settings」分頁。在「Linking - General -> Other Linker Flags」部分，將 -ObjC 新增至「Debug」和「Release」。如果看不到這些設定，請將「Build Settings」列中的篩選器從「Basic」變更為「All」。

9. 如要安裝 Places SDK for iOS XCFramework，請參閱「開始使用 Places SDK for iOS」。

步驟 3：將 API 金鑰加進專案

您先前已按照「取得 API 金鑰」的說明，為應用程式產生了 API 金鑰，現在請將金鑰加進 Xcode 專案。

請將以下範例中的 YOUR_API_KEY 替換成您的 API 金鑰。

注意： 如果您已記錄專案的軟體包 ID，或從專案屬性取得該 ID，請使用該 ID 限制 API 金鑰，僅供具有該特定軟體包 ID 的 iOS 應用程式使用。詳情請參閱「限制 API 金鑰」一文。

Swift

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

1. 新增下列匯入陳述式：

   import GoogleMaps

2. 使用 API 金鑰，將下列內容新增至 application(_:didFinishLaunchingWithOptions:) 方法：

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. 如果您也使用 Places API，請再次新增金鑰，如下所示：

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

1. 新增下列匯入陳述式：

   @import GoogleMaps;

2. 使用 API 金鑰，將下列內容新增至 application:didFinishLaunchingWithOptions: 方法：

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. 如果您也使用 Places API，請再次新增金鑰，如下所示：

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

步驟 4 (選用)：檢查 Apple 隱私權資訊清單檔案

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

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

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

步驟 5 (選用)：宣告 API 使用的網址配置

從 iOS 9 和 Xcode 7 開始，應用程式會透過在 Info.plist 檔案中指定配置，宣告要開啟的網址配置。使用者點選地圖上的 Google 標誌時，Maps SDK for iOS 會開啟 Google 地圖行動應用程式，因此您的應用程式可以宣告相關網址配置。

如要宣告 Maps SDK for iOS 使用的網址配置，請在 Info.plist 中加入下列程式碼：

 <key>LSApplicationQueriesSchemes</key>
 <array>
        <string>googlechromes</string>
        <string>comgooglemaps</string>
    </array>

下圖顯示 Xcode 使用者介面中的設定：

如果沒有上述宣告，使用者輕觸地圖上的 Google 標誌時，可能會發生下列錯誤：

• -canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
• -canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

如要消除這些錯誤，請在 Info.plist 中加入宣告。

後續步驟

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

• 加入含有標記的地圖。
• 在地圖上選取目前位置並顯示相關詳細資料。
• 反向地理編碼。
• 查看可用的程式碼範例和程式碼實驗室。
• 如需端對端解決方案，請查看可用的Maps Solutions。