設定 Xcode 專案

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

每次發布版本都會提供版本資訊。

步驟 1：安裝必要軟體

如要使用 Places SDK for iOS 建立專案，您需要：

• Xcode 16.0 以上版本

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

Swift Package Manager

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

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

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

1. 開啟 Xcode project 或 workspace，然後依序前往「File」>「Add Package Dependencies」。
2. 輸入 https://github.com/googlemaps/ios-places-sdk 做為網址，按下 Enter 鍵 即可提取套件，然後按一下「Add Package」(新增套件)。
3. 如要安裝特定 version，請將「Dependency Rule」(依附元件規則) 欄位設為其中一個版本選項。如果是新專案，建議您指定最新版本，並使用「確切版本」選項。完成後，按一下「新增套裝組合」。
4. 在「選擇套件產品」視窗中，確認 GooglePlaces、GooglePlacesSwift 或兩者都會新增至指定的主要目標。完成後，按一下「新增套裝組合」。

   如果您要從已淘汰的 GitHub 網址更新 Google Places Swift

   重要事項：自 0.3.0 版起，存取 Google Places Swift 的 GitHub 網址已變更。如果您要更新透過舊網址 (https://github.com/googlemaps/ios-places-swift-sdk) 存取的 GooglePlacesSwift 版本，請從 Xcode 的套件依附元件部分移除該版本。

5. 如要驗證安裝作業，請前往目標的「一般」窗格。在「Frameworks, Libraries, and Embedded Content」(架構、程式庫和內嵌內容) 中，您應該會看到已安裝的套件。您也可以查看「Project Navigator」的「Package Dependencies」部分，驗證套件及其版本。

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

1. 在 Xcode 中，依序前往「File」>「Packages」>「Update To Latest Package Versions」。

   如果您要從已淘汰的 GitHub 網址更新 Google Places Swift

   重要事項：自 0.3.0 版起，存取 Google Places Swift 的 GitHub 網址已變更。如果您要更新透過舊網址 https://github.com/googlemaps/ios-places-swift-sdk 存取的 GooglePlacesSwift 版本，請從 Xcode 的套件依附元件部分移除該版本。

2. 如要驗證安裝作業，請前往「專案導覽器」的「套件依附元件」部分，驗證套件及其版本。

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

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

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

手動安裝程式庫

本指南將說明如何將包含 Places SDK for iOS 和 Places Swift SDK for iOS 的 XCFrameworks 手動新增到專案，並在 Xcode 中完成建構設定。XCFramework 是二進位檔套件，可在多個平台使用，包括使用 Apple 晶片的電腦。您可以選擇加入 Places SDK for iOS、Places Swift SDK for iOS，或兩者都加入。

1. 下載下列 SDK 二進位檔和資源檔：
   • GooglePlaces
   • GooglePlacesResources
2. 如要安裝 Places Swift SDK for iOS，請安裝下列檔案：
   • GooglePlacesSwift
   • GooglePlacesSwiftResources
3. 解壓縮檔案，存取 XCFramework 和資源。
4. 啟動 Xcode，接著開啟現有專案，或建立新專案。如果您是 iOS 開發新手，請建立新專案，並選取「iOS App template」。
5. 從專案中移除先前版本的所有 Maps 套件。
6. 開啟「一般」分頁。將下列 XCFramework 拖曳至專案的「Frameworks, Libraries, and Embedded Content」(架構、程式庫和內嵌內容) 下方。請務必選取「不要嵌入」：
   • GooglePlaces.xcframework
   如果您要安裝 Places Swift SDK，請將下列 XCFramework 拖曳至專案的「Frameworks, Libraries, and Embedded Content」下方。請務必選取「不要嵌入」：
   • GooglePlacesSwift.xcframework
7. 將下載的 GooglePlacesResources 中的 GooglePlaces.bundle 複製到 Xcode 專案的頂層目錄。系統顯示提示時，請務必選取「Copy items into destination group's folder」。
   
   如果您要安裝 Places Swift SDK，請將下載的 GooglePlacesSwiftResources 中的 GooglePlacesSwift.bundle 複製到 Xcode 專案的頂層目錄。系統顯示提示時，請務必選取「Copy items into destination group's folder」。
8. 從「Project Navigator」中選取您的專案，然後為您的應用程式選擇目標。
9. 開啟「Build Phases」分頁標籤。在「Link Binary with Libraries」內加入下列架構和程式庫：
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

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

CocoaPods

Places SDK for iOS 和 Places Swift SDK for iOS 以 CocoaPod Pod 的形式提供，分別是 GooglePlaces 和 GooglePlacesSwift。

CocoaPods 是一種適用於 Swift 和 Objective-C Cocoa 專案的開放原始碼依附元件管理員。如果您還沒有 CocoaPods 工具，請在終端機上執行下列指令，即可在 macOS 中安裝這項工具。詳情請參閱 CocoaPods 入門指南。

sudo gem install cocoapods

建立 Podfile，安裝 SDK 及其依附元件：

1. 如果您還沒有 Xcode 專案，請立即建立一個並儲存至本機電腦 如果您是 iOS 開發新手，請建立新專案，並選取「iOS App template」。
2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
3. 編輯 Podfile，並新增依附元件及其版本。以下範例會指定應用程式目標名稱，以及 GooglePlaces 和 GooglePlacesSwift Pod 的名稱：

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '10.1.0'
     pod 'GooglePlacesSwift', '10.1.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 金鑰

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

GooglePlacesSwift

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

• 新增下列匯入陳述式：

  import GooglePlacesSwift

• 將以下內容新增到您的 application(_:didFinishLaunchingWithOptions:) 方法中，並以您的 API 金鑰取代「YOUR_API_KEY」YOUR_API_KEY：

  PlacesClient.provideAPIKey("YOUR_API_KEY")

Swift

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

• 新增下列匯入陳述式：

  import GooglePlaces

• 將以下內容新增到您的 application(_:didFinishLaunchingWithOptions:) 方法中，並以您的 API 金鑰取代「YOUR_API_KEY」YOUR_API_KEY：

  GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

• 新增下列匯入陳述式：

  @import GooglePlaces;

• 將以下內容新增到您的 application:didFinishLaunchingWithOptions: 方法中，並以您的 API 金鑰取代「YOUR_API_KEY」YOUR_API_KEY：

  [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

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

注意：下列內容適用於將應用程式部署至網路商店的情況。

根據 Apple 規定，App Store 上的應用程式必須提供應用程式隱私權詳細資料。如需最新資訊和詳細資料，請前往 Apple App Store 隱私權詳細資料頁面。

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

後續步驟

• 開始編寫程式碼。建議您先實作可取得使用者目前位置的入門應用程式。
• 專案設定完成後，即可探索範例應用程式。
• 使用 App Check 保護 API 金鑰。