設定 Xcode 專案

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

每個版本都提供版本資訊

步驟 1:安裝必要軟體

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

  • Xcode 14.0 版或更新版本

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

Swift 套件管理員

您可以透過 Swift Package Manager 安裝 Places SDK for iOS。如要新增 SDK,請確認您已移除所有現有的 Places SDK for iOS 依附元件。

如要將 SDK 加入新專案或現有專案,請按照下列步驟操作:

  1. 開啟 Xcode projectworkspace,然後依序前往「File」>「Add Package Dependencies」。
  2. 在網址欄位中輸入 https://github.com/googlemaps/ios-places-sdk,按下 Enter 鍵擷取套件,然後按一下「新增套件」。
  3. 如要安裝特定 version,請將「Dependency Rule」欄位設為其中一個版本型選項。如果是新專案,建議您指定最新版本並使用「精確版本」選項。完成後,按一下 [Add Package]。
  4. 在「Choose Package Products」視窗中,確認 GooglePlaces 會新增至您指定的 main 目標。完成後,按一下「Add Package」。
  5. 如要驗證安裝,請前往目標的 General 窗格。「Frameworks、程式庫和嵌入的內容」應該會顯示已安裝的套件。 您也可以查看「Project Navigator」的「Package Dependencies」部分,確認套件及其版本。

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

  1. 在 Xcode 中,依序前往「File」>「Packages」>「Update to Package Versions」。
  2. 如要驗證安裝,請前往「Project Navigator」的「Package Dependencies」部分,驗證套件及其版本。

如要移除使用 CocoaPods 新增的現有 Places SDK for iOS 依附元件,請按照下列步驟操作:

  1. 關閉 Xcode 工作區。開啟終端機並執行下列指令:
    sudo gem install cocoapods-deintegrate cocoapods-clean 
    pod deintegrate 
    pod cache clean --all
  2. 如果不想將 PodfilePodfile.resolved 和 Xcode workspace 用於 CocoaPods 以外的任何產品,請移除。

如要移除手動安裝的現有 Places SDK for iOS,請按照下列步驟操作:

  1. 在 Xcode 專案設定中,尋找「Frameworks、程式庫和嵌入的內容」。使用減號(-) 移除下列架構:
    • GooglePlaces.xcframework
  2. 從 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 及其依附元件:

  1. 如果您還沒有 Xcode 專案,請立即建立一個並儲存至本機電腦 如果您是 iOS 開發新手,請建立新專案,然後選取「iOS App Template」
  2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
  3. 編輯 Podfile,然後新增依附元件及其versions。以下範例說明如何指定應用程式目標名稱,以及 GooglePlaces Pod 的名稱:
    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '14.0'
    
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'GooglePlaces', '8.3.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 更新為最新版本。

手動安裝程式庫

本指南說明如何手動將包含 Places SDK for iOS 的 XCFramework 加進專案,並在 Xcode 中調整建構設定。XCFramework 是一種二進位檔套件,適用於多種平台,包括使用 Apple 晶片的電腦。

  1. 下載下列 SDK 二進位檔和資源檔案:
  2. 將壓縮的檔案解壓縮,以存取 XCFramework 和資源。
  3. 啟動 Xcode,接著開啟現有專案,或建立新專案。如果您是 iOS 開發新手,請建立新專案並選取「iOS App Template」
  4. 從專案中移除先前版本的所有地圖套件。
  5. 開啟「一般」分頁。將下列 XCFramework 拖曳至專案的「Frameworks、Library and Embedded Content」下方。請務必選取「Do Not Embed」
    • GooglePlaces.xcframework
  6. 從下載的 GooglePlacesResources 拖曳 GooglePlaces.bundle
  7. 從您下載的 GooglePlacesResources 複製 GooglePlaces.bundle,然後貼到 Xcode 專案的頂層目錄。出現提示時,請務必選取「將項目複製到目的地群組的資料夾」
  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」分頁。在「Linking - General」->「Other Linker Flags」部分,將 -ObjC 新增至「Debug」和「Release」。如果沒有看到這些設定,請將「Build Settings」列中的篩選器從「Basic」變更為「All」。

步驟 3:在應用程式中加入 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"];

步驟 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。