請按照本指南中的步驟下載 Places SDK for iOS、將程式庫及其依附元件加入應用程式,並免費取得 API 金鑰。
每個發布版本都提供版本資訊。
步驟 1:取得最新版本的 Xcode
如要使用 Places SDK for iOS 建立專案,您需要:
步驟 2:安裝 SDK
如要在新專案中安裝 API,請按照下列步驟操作:使用 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 安裝 SDK 及其依附元件:
- 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本。
- 在專案目錄中建立名為
Podfile
的檔案。這個檔案定義了專案的依附元件。 - 編輯
Podfile
並新增依附元件及其版本。以下範例說明如何指定應用程式目標名稱及GooglePlaces
pod 的名稱:source 'https://github.com/CocoaPods/Specs.git' platform :ios, '13.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GooglePlaces', '7.4.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 更新為最新版本。
使用 Carthage
Places SDK for iOS 可與 Carthage 搭配使用。Scartage 是簡易的集中式依附元件管理工具,適用於 Swift 和 Objective-C Cocoa 專案。
- 安裝 Carthage。有數種方法,請參閱 Carthage README 檔案,瞭解實際步驟。
- 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本。
- 在專案目錄中建立名為
Cartfile
的檔案。此檔案可定義專案的依附元件。 - 編輯
Cartfile
並新增依附元件及其版本:
binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1
請務必定期執行carthage outdated
,以偵測是否有新版本,以確保您隨時都能使用最新版本。 - 儲存
Cartfile
。 - 在終端機視窗中,前往包含
Cartfile
的目錄:
cd <path-to-project>
- 執行
carthage update
指令。此動作會安裝Cartfile
中指定的 API 及其所有依附元件。 - 在 Finder 的專案目錄中,前往
Carthage/Build/iOS
底下下載的架構檔案。 - 將下列套件拖曳至專案中 (如果系統提示,請選取 [Copy items if needed]):
GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
- 以滑鼠右鍵按一下專案中的
GooglePlaces.xcframework
,然後選取 [Show in Finder]。 - 將
GooglePlaces.bundle
從Resources
資料夾拖曳至您的專案。畫面顯示提示時,請確保您並未選取 [Copy items into destination group's folder]。 - 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
- 開啟 [Build Phases] (建構階段) 分頁,然後在 [Link Binary with library] (連結二進位檔與程式庫) 中新增下列架構和程式庫:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。
- 在「其他連結器標記」部分新增
-ObjC
。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。
如要更新現有專案的 API,請按照下列步驟操作:
- 開啟終端機並前往包含
Cartfile
的專案目錄。 - 執行
carthage update
指令。這會將Cartfile
中指定的所有 API 更新為最新版本。
手動安裝
本指南說明如何手動將 GooglePlaces 架構新增至專案,並在 Xcode 中調整建構設定。
- 下載 SDK 來源檔案:GooglePlaces-7.4.0
- 將來源檔案解除封裝。
- 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本。
- 從專案中移除先前版本的所有地圖組合。
- 將下列套件拖曳至專案中 (如果系統提示,請選取 [Copy items if needed]):
GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
- 以滑鼠右鍵按一下專案中的
GooglePlaces.xcframework
,然後選取 [Show in Finder]。 - 將
GooglePlaces.bundle
從Resources
資料夾拖曳至您的專案。畫面顯示提示時,請確保您並未選取 [Copy items into destination group's folder]。 - 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
- 開啟 [Build Phases] (建構階段) 分頁,然後在 [Link Binary with library] (連結二進位檔與程式庫) 中新增下列架構和程式庫:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。
- 在「其他連結器標記」部分新增
-ObjC
。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。
安裝 XCFramework
XCFramework 是二進位套件,可以在多個平台上使用,包括使用 M1 晶片組的機器,用於安裝 Places SDK for iOS。本指南說明如何將含有 Places SDK for iOS 的 XCFramework 新增至專案,並在 Xcode 中調整建構設定。
附地毯
Places SDK for iOS 可與 Carthage 搭配使用。Scartage 是簡易的集中式依附元件管理工具,適用於 Swift 和 Objective-C Cocoa 專案。
- 安裝 Carthage。有數種方法,請參閱 Carthage README 檔案,瞭解實際步驟。
- 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本。
- 在專案目錄中建立名為
Cartfile
的檔案。這個檔案定義了專案的依附元件。 編輯
Cartfile
並新增依附元件及其版本:binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1-beta
- 儲存
Cartfile
。 在終端機視窗中,前往含有
Cartfile
的目錄:cd <path-to-project>
- 執行
carthage update
指令。這會安裝在Cartfile
中指定的 API 及其所有依附元件。 - 在 Finder 的專案目錄中,前往
Carthage/Build
下下載的已下載架構檔案。 - 將下列 XCFramework 拖曳到「架構、程式庫和嵌入內容」下的專案中。請務必選取 [不要嵌入]:
GooglePlaces-x.x.x/GooglePlaces.xcframework
- 在專案中的
GooglePlaces.xcframework
上按一下滑鼠右鍵,然後選取「Show In Finder」。 - 將
GooglePlaces.bundle
從ios-arm64/GooglePlaces.framework/Resources
資料夾拖曳至 Xcode 專案的頂層目錄。當系統出現提示時,請確認未選取 [將項目複製到目標群組的資料夾]。 - 從「專案導覽工具」中選取您的專案,然後選擇應用程式的目標。
- 開啟「Build Phases」分頁,並在「Link Binary with libraries」中加入下列架構和程式庫:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。
- 在「其他連結器標記」部分新增
-ObjC
。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。
手動
本指南說明如何手動將 Maps SDK for iOS 新增至專案,並在 Xcode 中調整建構設定。
- 下載 SDK 來源檔案:GooglePlaces-7.4.0。
- 將來源檔案解壓縮。前往 Frameworks (資料夾) 資料夾,以存取 XCFramework。
- 啟動 Xcode 並開啟現有專案,或建立新專案。如果您是 iOS 新手,請建立新專案並選取 iOS 應用程式範本。
- 將下列 XCFramework 拖曳到「架構、程式庫和嵌入內容」下的專案中。請務必選取 [不要嵌入]:
GooglePlaces-x.x.x/GooglePlaces.xcframework
- 在專案中的
GooglePlaces.xcframework
上按一下滑鼠右鍵,然後選取「Show In Finder」。 - 將
GooglePlaces.bundle
從ios-arm64/GooglePlaces.framework/Resources
資料夾拖曳至 Xcode 專案的頂層目錄。當系統出現提示時,請確認未選取 [將項目複製到目標群組的資料夾]。 - 從「專案導覽工具」中選取您的專案,然後選擇應用程式的目標。
- 開啟「Build Phases」分頁,並在「Link Binary with libraries」中加入下列架構和程式庫:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。
- 在「其他連結器標記」部分新增
-ObjC
。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。
步驟 3:在應用程式中加入 API 金鑰
請將以下範例中的 YOUR_API_KEY
替換成您的 API 金鑰。
Swift
將 API 金鑰新增到您的 AppDelegate.swift
中,如下所示:
- 新增下列匯入陳述式:
import GooglePlaces
- 將以下內容新增到您的
application(_:didFinishLaunchingWithOptions:)
方法中,並將 YOUR_API_KEY 替換為您的 API 金鑰:GMSPlacesClient.provideAPIKey("YOUR_API_KEY")
Objective-C
將 API 金鑰新增到您的 AppDelegate.m
中,如下所示:
- 新增下列匯入陳述式:
@import GooglePlaces;
- 將以下內容新增到您的
application:didFinishLaunchingWithOptions:
方法中,並將 YOUR_API_KEY 替換為您的 API 金鑰:[GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
步驟 4:開始撰寫程式碼
下列程式碼範例示範如何取得目前地點。
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
後續步驟
專案設定完成後,您可以探索範例應用程式。您需要安裝 Cocoapods v1.6.1。