設定 Xcode 專案

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

每個版本都會提供版本資訊。

步驟 1：安裝必要軟體

如要使用 Maps SDK for iOS 建立專案，您必須下載並安裝：

• Xcode 15.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。不需要額外設定。

Swift Package Manager

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

重要事項：這些操作說明假設您使用 Xcode 15 以上版本，但適用於先前版本的 Xcode。

如要將 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」選項。完成後，按一下「新增套件」。

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

1. 如果您要從 9.0.0 以下版本升級，則必須在升級後移除下列依附元件：GoogleMapsBase、GoogleMapsCore 和 GoogleMapsM4B。請勿移除 GoogleMaps 的依附元件。詳情請參閱「第 9.0.0 版版本資訊」。

   在 Xcode 專案設定中，找出「Frameworks、Libraries 和 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 和 Embedded Content」。使用減號(-) 移除下列架構：
   • GoogleMaps
   • GoogleMapsBase (僅適用於 9.2.0 以下版本的裝置)
   • GoogleMapsCore (僅適用於 9.2.0 以下版本的裝置)
   • GoogleMapsM4B (僅適用於 9.0.0 以下版本的安裝作業)
2. 從 Xcode 專案的頂層目錄中移除 GoogleMaps 套件。

手動安裝

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

1. 下載下列 SDK 二進位檔和資源檔案：
   • GoogleMaps
   • GoogleMapsM4B
   • GoogleMapsResources
2. 解壓縮檔案，存取 XCFramework 和資源。
3. 如果您還沒有 Xcode 專案，請立即建立一個並儲存至本機電腦 如果您是 iOS 開發新手：
   1. 建立新專案。
   2. 依序選取「iOS」>「App」範本。
   3. 在專案選項畫面中：
      1. 輸入「專案名稱」。
      2. 記下「Bundle identifier」欄位的值。 您可以使用該值限制下方的 API 金鑰。
      3. 將專案的「介面」設為「分鏡表」。
      4. 將「Language」設為「Swift」或「Objective-C」。
4. 開啟「一般」分頁。將下列 XCFramework 拖曳至「Framework、Library 和嵌入式內容」下方的專案中。請務必選取「Do Not Embed」：
   • GoogleMaps.xcframework
5. 將您下載的 GoogleMapsResources 中的 GoogleMaps.bundle 複製到 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
   • OpenGLES.framework (僅限使用 OpenGL 時)
   • QuartzCore.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」。

CocoaPods

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

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

sudo gem install cocoapods

為 Maps SDK for iOS 建立 Podfile，並使用該檔案安裝 API 及其依附元件：

1. 如果您還沒有 Xcode 專案，請立即建立一個並儲存至本機電腦 如果您是 iOS 開發新手：
   1. 建立新專案。
   2. 依序選取「iOS」>「App」範本。
   3. 在專案選項畫面中：
      1. 輸入「專案名稱」。
      2. 記下「Bundle identifier」欄位的值。 您可以使用該值限制下方的 API 金鑰。
      3. 將專案的「介面」設為「分鏡表」。
      4. 將「Language」設為「Swift」或「Objective-C」。
2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
3. 編輯 Podfile，並新增依附元件和版本。以下範例包含 Maps SDK for iOS 所需的依附元件：

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '9.2.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 更新為最新版本。

步驟 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 提供許多教學課程和範例應用程式，協助您踏出第一步。相關詳情請參閱：

• 建議您先從下列教學課程開始學習：
  • 加入含有標記的地圖。
  • 在地圖上選取目前位置並顯示相關詳細資料。
  • 反向地理編碼。
• 請查看可用的程式碼範例和程式碼研究室。
• 如需端對端解決方案，請查看可用的 Google 地圖解決方案。