設定 Xcode 專案

啟用計費功能並建立 API 金鑰後，您就可以設定要用來開發應用程式的 Xcode 專案。

每個版本都會提供版本資訊。

步驟 1：安裝必要軟體

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

• Xcode 14.0 版以上
• Cocoapods
  注意： 雖然您可以手動安裝 Places SDK for iOS，但不一定要使用 Cocoapods，但大多數開發人員都偏好使用套件管理工具。

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

如要在新專案中安裝 API，請按照下列步驟操作：

使用 Cocoapods

Places SDK for iOS 以 CocoaPod 這個 Pod GooglePlaces 的形式提供，這個 Pod 包含所有地點功能。

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

sudo gem install cocoapods

為 Places SDK for iOS 建立 Podfile，並使用它安裝 SDK 及其依附元件：

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

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '8.2.1'
   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 更新為最新版本。

安裝 XCFramework

XCFramework 是一種二進位套件，可在多個平台上使用，包括使用 M1 晶片組安裝 Places SDK for iOS 的機器。本指南說明如何在專案中新增包含 Places SDK for iOS 的 XCFramework，並在 Xcode 中調整建構設定。

手動

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

1. 下載 SDK 來源檔案：GooglePlaces-8.2.1。
2. 將來源檔案解除封裝。前往「Frameworks」資料夾即可存取這個 XCFramework。
3. 啟動 Xcode 並開啟現有專案，或建立新專案。如果您是第一次使用 iOS，請建立新專案並選取「iOS App template」。
4. 將下列 XCFramework 拖曳至「Frameworks、Library and Embedded Content」之下，請務必選取「請勿嵌入」：
   • GooglePlaces-x.x.x/GooglePlaces.xcframework
5. 以滑鼠右鍵按一下專案中的 GooglePlaces.xcframework，然後選取「Show In Finder」。
6. 將 GooglePlaces.bundle 從 ios-arm64/GooglePlaces.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。系統提示時，請確保您未選取「Copy items into destination group's folder」。
7. 從 Project Navigator 中選取專案，然後選擇應用程式的目標。
8. 開啟「Build Phases」分頁，並在「Link Binary with Libraries」內加入下列架構和程式庫：
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

9. 選擇專案 (而不是特定目標)，然後開啟「Build Settings」分頁。

10. 在「Other Linker Flags」(其他連結器旗標) 區段中，新增 -ObjC。如果找不到這些設定，請將「Build Settings」列中的篩選器從「Basic」變更為「All」。

附卡丁車

注意： Carthage 目前不支援以最低 iOS 13 以上版本建構的程式庫。這表示最新支援的 Places SDK for iOS 版本為 6.2.1。

手動安插

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

1. 下載 SDK 來源檔案：GooglePlaces-8.2.1
2. 將來源檔案解除封裝。
3. 啟動 Xcode，接著開啟現有專案，或建立新專案。如果您是 iOS 開發新手，請建立新專案，然後選取「iOS App template」。
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 Libraries」內加入下列架構和程式庫：
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

10. 選擇專案 (而不是特定目標)，然後開啟「Build Settings」分頁。

11. 在「Other Linker Flags」(其他連結器旗標) 區段中，新增 -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：開始撰寫程式碼

下列程式碼範例示範如何取得目前地點。

請注意，由於這個範例需要存取裝置的位置資訊才能取得目前位置，因此您必須在專案的 Info.plist 檔案中設定包含適當說明文字的 NSLocationWhenInUseUsageDescription 鍵。詳情請參閱取得目前地點指南。

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 1.6.1 版。