設定 Xcode 專案

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

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

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

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

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

  1. Xcode 13.0 版或更新版本。
  2. Cocoapods 或 Carthage。

步驟 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.bundle 從 Resources 資料夾拖曳至您的專案。畫面顯示提示時，請確保您並未選取 [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.bundle 從 Resources 資料夾拖曳至您的專案。畫面顯示提示時，請確保您並未選取 [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.bundle 從 ios-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.bundle 從 ios-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。