啟用計費功能並建立 API 金鑰後,您就可以設定要用來開發應用程式的 Xcode 專案。
每個版本都提供版本資訊。
步驟 1:安裝必要軟體
如要使用 Places SDK for iOS 建立專案,您需要:
- Xcode 15.0 版或更新版本
步驟 2:建立 Xcode 專案並安裝 Places SDK for iOS
Swift 套件管理員
您可以透過 Swift Package Manager 安裝 Places SDK for iOS。如要新增 SDK,請確認您已移除所有現有的 Places SDK for iOS 依附元件。
如要將 SDK 加入新專案或現有專案,請按照下列步驟操作:
-
開啟 Xcode
project
或workspace
,然後依序前往「File」>「Add Package Dependencies」。 - 在網址欄位中輸入 https://github.com/googlemaps/ios-places-sdk,按下 Enter 鍵擷取套件,然後按一下「新增套件」。
-
如要安裝特定
version
,請將「Dependency Rule」欄位設為其中一個版本型選項。如果是新專案,建議您指定最新版本並使用「精確版本」選項。完成後,按一下 [Add Package]。 -
在「Choose Package Products」視窗中,確認
GooglePlaces
會新增至您指定的main
目標。完成後,按一下「Add Package」。 -
如要驗證安裝,請前往目標的
General
窗格。「Frameworks、程式庫和嵌入的內容」應該會顯示已安裝的套件。 您也可以查看「Project Navigator」的「Package Dependencies」部分,確認套件及其版本。
如要更新現有專案的 package
,請按照下列步驟操作:
如果您是從 9.0.0 以下版本升級,必須在升級後移除下列依附元件:
GoogleMapsBase
、GoogleMapsCore
,以及GoogleMapsM4B
。請勿移除GoogleMaps
的依附元件。詳情請參閱 9.0.0 版版本資訊。在 Xcode 專案設定中,尋找「Frameworks、程式庫和內嵌內容」。使用減號(-) 移除下列架構:
GoogleMapsBase
(僅適用於 9.0.0 以下版本的升級)GoogleMapsCore
(僅適用於 9.0.0 以下版本的升級)GoogleMapsM4B
(僅適用於 9.0.0 以下版本的升級)
- 在 Xcode 中,依序前往「File」>「Packages」>「Update to Package Versions」。
- 如要驗證安裝,請前往「Project Navigator」的「Package Dependencies」部分,驗證套件及其版本。
如要移除使用 CocoaPods
新增的現有 Places SDK for iOS 依附元件,請按照下列步驟操作:
- 關閉 Xcode 工作區。開啟終端機並執行下列指令:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
如果不想將
Podfile
、Podfile.resolved
和 Xcodeworkspace
用於 CocoaPods 以外的任何產品,請移除。
-
在 Xcode 專案設定中,尋找「Frameworks、程式庫和內嵌內容」。使用減號(-) 移除下列架構:
GooglePlaces.xcframework
-
從 Xcode 專案的頂層目錄中,移除
GooglePlaces
套件。
CocoaPods
Places SDK for iOS 以 CocoaPod Pod GooglePlaces 的形式提供,其中包含所有地點的功能。
CocoaPods 是 Swift 和 Objective-C Cocoa 專案的開放原始碼依附元件管理工具。如果您還沒有 CocoaPods 工具,請從終端機執行下列指令,以在 macOS 上安裝該工具。詳情請參閱 CocoaPods 入門指南。
sudo gem install cocoapods
為 Places SDK for iOS 建立 Podfile
,然後用來安裝 SDK 及其依附元件:
- 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是 iOS 開發新手,請建立新專案,然後選取「iOS App Template」。
- 在專案目錄中建立名為
Podfile
的檔案。這個檔案定義了專案的依附元件。 - 編輯
Podfile
,然後新增依附元件及其versions。以下範例說明如何指定應用程式目標名稱,以及GooglePlaces
Pod 的名稱:source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GooglePlaces', '8.3.0' end
請務必定期執行pod outdated
來偵測是否有較新版本,確保您隨時都能取得最新版本。 - 儲存
Podfile
。 開啟終端機並前往包含
Podfile
的目錄:cd <path-to-project>
執行
pod install
指令。此動作會安裝Podfile
中指定的 API 及其所有依附元件。pod install
關閉 Xcode,接著按兩下來開啟專案的
.xcworkspace
檔案來啟動 Xcode。從現在起,您必須使用.xcworkspace
檔案來開啟專案。
如要更新現有專案的 API,請按照下列步驟操作:
- 開啟終端機並前往包含
Podfile
的專案目錄。 - 執行
pod update
指令。這麼做會將Podfile
中指定的所有 API 更新為最新版本。
手動安裝程式庫
本指南說明如何手動將包含 Places SDK for iOS 的 XCFramework 加進專案,並在 Xcode 中調整建構設定。XCFramework 是一種二進位檔套件,適用於多種平台,包括使用 Apple 晶片的電腦。
- 下載下列 SDK 二進位檔和資源檔案:
- 解壓縮檔案,以存取 XCFramework 和資源。
- 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是 iOS 開發新手,請建立新專案並選取「iOS App Template」。
- 請從專案中移除先前版本的所有地圖套件。
-
開啟「一般」分頁。將下列 XCFramework 拖曳至專案的「Frameworks、Library and Embedded Content」下方。請務必選取「Do Not Embed」:
GooglePlaces.xcframework
從下載的 GooglePlacesResources 拖曳 -
從您下載的 GooglePlacesResources 複製
GooglePlaces.bundle
,然後貼到 Xcode 專案的頂層目錄。出現提示時,請務必選取「將項目複製到目的地群組的資料夾」。 - 從「Project Navigator」中選取專案,並選擇應用程式的目標。
-
開啟「Build Phases」分頁。在「Link Binary with Libraries」中,加入下列架構和程式庫:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
-
選擇您的專案 (而不是特定目標),然後開啟「Build Settings」分頁。在「Linking - General」->「Other Linker Flags」部分,將
-ObjC
新增至「Debug」和「Release」。如果沒有看到這些設定,請將「Build Settings」列中的篩選器從「Basic」變更為「All」。
GooglePlaces.bundle
GooglePlacesSwift
您可以使用 Swift Package Manager、CocoaPods 或手動安裝 GooglePlacesSwift (預先發布版) SDK。所有程序中安裝的步驟會與 Places SDK for iOS 列出的步驟相對應,但有以下差異:
- 必須提供 Xcode 15.3。
- 若是 Swift Package Manager,請一併將執行個體
GooglePlaces
替換為GooglePlacesSwift
。包括匯入陳述式。 - 將版本號碼更新為 0.1.0。
- 將 https://github.com/googlemaps/ios-places-sdk 的執行個體替換為 https://github.com/googlemaps/ios-places-swift-sdk。
- 如要手動安裝,除了 GooglePlaces XCFramework 和資源檔案之外,您還需要新增
GooglePlacesSwift
XCFramework 和資源檔案。
舉例來說,如果使用 CocoaPods,編輯後的 Podfile
會是:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.3' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GooglePlacesSwift', '0.1.0' end
步驟 3:檢查 Apple Privacy 資訊清單檔案
Apple 要求 App Store 的應用程式隱私權詳細資料。如需最新資訊和更多資訊,請造訪 Apple App Store 隱私權詳細資料頁面。
Apple 隱私權資訊清單檔案內含於 SDK 的資源套件。如要確認隱私權資訊清單檔案是否已納入,並檢查其中內容,請建立應用程式封存檔,然後從封存檔產生隱私權報告。
步驟 4:在應用程式中加入 API 金鑰
請將以下範例中的 YOUR_API_KEY
替換成您的 API 金鑰。
Swift
將 API 金鑰新增到您的 AppDelegate.swift
中,如下所示:
- 新增下列匯入陳述式:
import GooglePlaces
- 將以下內容加入
application(_:didFinishLaunchingWithOptions:)
方法中,並以您的 API 金鑰取代 YOUR_API_KEY:GMSPlacesClient.provideAPIKey("YOUR_API_KEY")
Objective-C
將 API 金鑰新增到您的 AppDelegate.m
中,如下所示:
- 新增下列匯入陳述式:
@import GooglePlaces;
- 將以下內容加入
application:didFinishLaunchingWithOptions:
方法中,並以您的 API 金鑰取代 YOUR_API_KEY:[GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
GooglePlacesSwift
將 API 金鑰新增到您的 AppDelegate.swift
中,如下所示:
- 新增下列匯入陳述式:
import GooglePlacesSwift
- 將以下內容加入
application(_:didFinishLaunchingWithOptions:)
方法中,並以您的 API 金鑰取代 YOUR_API_KEY:PlacesClient.shared.provideAPIKey("YOUR_API_KEY")
步驟 5:開始編寫程式碼
下列程式碼範例示範如何取得目前位置。
Swift
import GooglePlaces import UIKit class GetStartedViewController : UIViewController { // Add a pair of UILabels in Interface Builder, and connect the outlets to these variables. @IBOutlet private var nameLabel: UILabel! @IBOutlet private var addressLabel: UILabel! private var placesClient: GMSPlacesClient! override func viewDidLoad() { super.viewDidLoad() placesClient = GMSPlacesClient.shared() } // Add a UIButton in Interface Builder, and connect the action to this function. @IBAction func getCurrentPlace(_ sender: UIButton) { let placeFields: GMSPlaceField = [.name, .formattedAddress] placesClient.findPlaceLikelihoodsFromCurrentLocation(withPlaceFields: placeFields) { [weak self] (placeLikelihoods, error) in guard let strongSelf = self else { return } guard error == nil else { print("Current place error: \(error?.localizedDescription ?? "")") return } guard let place = placeLikelihoods?.first?.place else { strongSelf.nameLabel.text = "No current place" strongSelf.addressLabel.text = "" return } strongSelf.nameLabel.text = place.name strongSelf.addressLabel.text = place.formattedAddress } } }
Objective-C
#import "GetStartedViewController.h" @import GooglePlaces; @interface GetStartedViewController () // Add a pair of UILabels in Interface Builder and connect the outlets to these variables @property (weak, nonatomic) IBOutlet UILabel *nameLabel; @property (weak, nonatomic) IBOutlet UILabel *addressLabel; @end @implementation GetStartedViewController { GMSPlacesClient *_placesClient; } - (void)viewDidLoad { [super viewDidLoad]; _placesClient = [GMSPlacesClient sharedClient]; } // Add a pair of UILabels in Interface Builder and connect the outlets to these variables. - (IBAction)getCurrentPlace:(UIButton *)sender { GMSPlaceField placeFields = (GMSPlaceFieldName | GMSPlaceFieldFormattedAddress); __weak typeof(self) weakSelf = self; [_placesClient findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:placeFields callback:^(NSArray<GMSPlaceLikelihood *> * _Nullable likelihoods, NSError * _Nullable error) { __typeof__(self) strongSelf = weakSelf; if (strongSelf == nil) { return; } if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } GMSPlace *place = likelihoods.firstObject.place; if (place == nil) { strongSelf.nameLabel.text = @"No current place"; strongSelf.addressLabel.text = @""; return; } strongSelf.nameLabel.text = place.name; strongSelf.addressLabel.text = place.formattedAddress; }]; } @end
GooglePlacesSwift
struct ContentView: View { @State var place: Place? var body: some View { Button("Get Place") { // A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" let fetchPlaceRequest = FetchPlaceRequest( placeID: placeID, placeProperties: [.displayName, .formattedAddress] ) Task { switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): self.place = place case .failure(let placesError): // Handle error } Text(swiftPlace?.displayName ?? "No place yet") .padding() Text(swiftPlace?.formattedAddress ?? "No place yet") .padding() } }
後續步驟
專案設定完成後,即可探索範例應用程式。