設定 Xcode 專案

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

請按照本指南中的步驟下載 Places SDK for iOS、將程式庫及其依附元件加入應用程式,並免費取得 API 金鑰。

每個發布版本都提供版本資訊

步驟 1:取得最新版本的 Xcode

如要使用 Places SDK for iOS 建立專案,您需要:

  1. Xcode 13.0 版或更新版本。
  2. CocoapodsCarthage

步驟 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 及其依附元件:

  1. 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本
  2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
  3. 編輯 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 來偵測是否有較新的版本何時出現,以便隨時取得最新版本。
  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 更新為最新版本。

使用 Carthage

Places SDK for iOS 可與 Carthage 搭配使用。Scartage 是簡易的集中式依附元件管理工具,適用於 Swift 和 Objective-C Cocoa 專案。

  1. 安裝 Carthage。有數種方法,請參閱 Carthage README 檔案,瞭解實際步驟。
  2. 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本
  3. 在專案目錄中建立名為 Cartfile 的檔案。此檔案可定義專案的依附元件。
  4. 編輯 Cartfile 並新增依附元件及其版本
     binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1
    請務必定期執行 carthage outdated,以偵測是否有新版本,以確保您隨時都能使用最新版本。
  5. 儲存 Cartfile
  6. 在終端機視窗中,前往包含 Cartfile 的目錄:
    cd <path-to-project>
  7. 執行 carthage update 指令。此動作會安裝 Cartfile 中指定的 API 及其所有依附元件。
  8. 在 Finder 的專案目錄中,前往 Carthage/Build/iOS 底下下載的架構檔案。
  9. 將下列套件拖曳至專案中 (如果系統提示,請選取 [Copy items if needed]):
    • GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
  10. 以滑鼠右鍵按一下專案中的 GooglePlaces.xcframework,然後選取 [Show in Finder]
  11. GooglePlaces.bundleResources 資料夾拖曳至您的專案。畫面顯示提示時,請確保您並選取 [Copy items into destination group's folder]
  12. 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
  13. 開啟 [Build Phases] (建構階段) 分頁,然後在 [Link Binary with library] (連結二進位檔與程式庫) 中新增下列架構和程式庫:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  14. 選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。

  15. 在「其他連結器標記」部分新增 -ObjC。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]

如要更新現有專案的 API,請按照下列步驟操作:

  1. 開啟終端機並前往包含 Cartfile 的專案目錄。
  2. 執行 carthage update 指令。這會將 Cartfile 中指定的所有 API 更新為最新版本。

手動安裝

本指南說明如何手動將 GooglePlaces 架構新增至專案,並在 Xcode 中調整建構設定。

  1. 下載 SDK 來源檔案:GooglePlaces-7.4.0
  2. 將來源檔案解除封裝。
  3. 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本
  4. 從專案中移除先前版本的所有地圖組合。
  5. 將下列套件拖曳至專案中 (如果系統提示,請選取 [Copy items if needed]):
    • GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
  6. 以滑鼠右鍵按一下專案中的 GooglePlaces.xcframework,然後選取 [Show in Finder]
  7. GooglePlaces.bundleResources 資料夾拖曳至您的專案。畫面顯示提示時,請確保您並選取 [Copy items into destination group's folder]
  8. 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
  9. 開啟 [Build Phases] (建構階段) 分頁,然後在 [Link Binary with library] (連結二進位檔與程式庫) 中新增下列架構和程式庫:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  10. 選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。

  11. 在「其他連結器標記」部分新增 -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 專案。

  1. 安裝 Carthage。有數種方法,請參閱 Carthage README 檔案,瞭解實際步驟。
  2. 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果您是第一次使用 iOS 開發作業,請建立新專案並選取 iOS 應用程式範本
  3. 在專案目錄中建立名為 Cartfile 的檔案。這個檔案定義了專案的依附元件。
  4. 編輯 Cartfile 並新增依附元件及其版本

    binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1-beta
  5. 儲存 Cartfile
  6. 在終端機視窗中,前往含有 Cartfile 的目錄:

    cd <path-to-project>
  7. 執行 carthage update 指令。這會安裝在 Cartfile 中指定的 API 及其所有依附元件。
  8. 在 Finder 的專案目錄中,前往 Carthage/Build 下下載的已下載架構檔案。
  9. 將下列 XCFramework 拖曳到「架構、程式庫和嵌入內容」下的專案中。請務必選取 [不要嵌入]
    • GooglePlaces-x.x.x/GooglePlaces.xcframework
  10. 在專案中的 GooglePlaces.xcframework 上按一下滑鼠右鍵,然後選取「Show In Finder」
  11. GooglePlaces.bundleios-arm64/GooglePlaces.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。當系統出現提示時,請確認選取 [將項目複製到目標群組的資料夾]
  12. 從「專案導覽工具」中選取您的專案,然後選擇應用程式的目標。
  13. 開啟「Build Phases」分頁,並在「Link Binary with libraries」中加入下列架構和程式庫:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  14. 選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。

  15. 在「其他連結器標記」部分新增 -ObjC。如果您沒有看到這些設定,請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]

手動

本指南說明如何手動將 Maps SDK for iOS 新增至專案,並在 Xcode 中調整建構設定。

  1. 下載 SDK 來源檔案:GooglePlaces-7.4.0
  2. 將來源檔案解壓縮。前往 Frameworks (資料夾) 資料夾,以存取 XCFramework。
  3. 啟動 Xcode 並開啟現有專案,或建立新專案。如果您是 iOS 新手,請建立新專案並選取 iOS 應用程式範本
  4. 將下列 XCFramework 拖曳到「架構、程式庫和嵌入內容」下的專案中。請務必選取 [不要嵌入]
    • GooglePlaces-x.x.x/GooglePlaces.xcframework
  5. 在專案中的 GooglePlaces.xcframework 上按一下滑鼠右鍵,然後選取「Show In Finder」
  6. GooglePlaces.bundleios-arm64/GooglePlaces.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。當系統出現提示時,請確認選取 [將項目複製到目標群組的資料夾]
  7. 從「專案導覽工具」中選取您的專案,然後選擇應用程式的目標。
  8. 開啟「Build Phases」分頁,並在「Link Binary with libraries」中加入下列架構和程式庫:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  9. 選擇您的專案 (而不是特定目標),然後開啟 [Build Settings] 分頁標籤。

  10. 在「其他連結器標記」部分新增 -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。