設定 Xcode 專案

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

步驟 1：安裝所需軟體

如要使用 Maps SDK for iOS 建立專案，您必須下載並安裝：

• Xcode 13.0 以上版本

• Cocoapods 或 Carthage

  注意： 雖然您可以在不使用 Cocoapods 或 Carthage 的情況下手動安裝 Maps SDK for iOS，但大多數開發人員都偏好使用套件管理員。

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

使用 CocoaPods

Maps SDK for iOS 以 CocoaPods Pod 的形式提供。CocoaPods 是一種適用於 Swift 和 Objective-C Cocoa 專案的開放原始碼依附元件管理員。

如果您還沒有 CocoaPods 工具，請在終端機上執行下列指令，即可在 macOS 中安裝這項工具。詳情請參閱 CocoaPods 入門指南。

sudo gem install cocoapods

為 Maps SDK for iOS 建立 Podfile，並使用該檔案安裝 API 及其依附元件：

1. 如果您還沒有 Xcode 專案，請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「應用程式」範本。
   3. 在專案選項畫面上：
      1. 輸入 [專案名稱]。
      2. 記錄 [軟體包 ID] 欄位的值。 您可以使用這個值來限制您的 API 金鑰。
      3. 將專案 Interface 設定為 Storyboard。
      4. 將「Language」(語言) 設為 [Swift] (切割) 或 [Objective-C] (目標 C)。
2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
3. 編輯 Podfile 並新增依附元件及其版本。以下範例說明包含 Maps SDK for iOS 所需的依附元件：

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '13.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '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

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

Maps SDK for iOS 可與 Carthage 搭配使用。這是一個專為簡易式且分散化的依附元件，專門用於 Swift 和 Objective-C Cocoa 專案。

1. 安裝 Carthage。有數種方法，請參閱 Carthage README 檔案，瞭解實際步驟。
2. 如果您還沒有 Xcode 專案，請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「應用程式」範本。
   3. 在專案選項畫面上：
      1. 輸入 [專案名稱]。
      2. 記錄 [軟體包 ID] 欄位的值。 您可以使用這個值來限制您的 API 金鑰。
      3. 將專案 Interface 設定為 Storyboard。
      4. 將「Language」(語言) 設為 [Swift] (切割) 或 [Objective-C] (目標 C)。
3. 在專案目錄中建立名為 Cartfile 的檔案。此檔案可定義專案的依附元件。
4. 編輯 Cartfile 並新增依附元件及其版本：
   

   binary "https://dl.google.com/geosdk/GoogleMaps.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. 將下列套件拖曳至專案中： (系統顯示提示時，請選取 [視需要複製項目，請使用與上述相同的版本)。)
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (僅限付費方案客戶) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
10. 以滑鼠右鍵按一下專案中的 GoogleMaps.xcframework，然後選取 [Show in Finder]。
11. 將 GoogleMaps.bundle 從 Resources 資料夾拖曳至 Xcode 專案的頂層目錄。出現系統提示時，請勿選取 [將項目複製到目標群組的資料夾]。
12. 從「Project Navigator」中選取您的專案，然後為您的應用程式選擇目標。
13. 開啟應用程式目標的「Build Phases」分頁，並在「Link Binary with library」中加入下列架構和程式庫：
    • Accelerate.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. 選擇您的專案 (而不是特定目標)，然後開啟 [Build Settings] 分頁標籤。在「Other Linker Flags」部分中，新增 -ObjC。如果您沒有看到這些設定，請將「Build Settings」列中的篩選器從「Basic」變更為「All」。

15. 如要安裝 Places SDK for iOS，請參閱「開始使用 Places SDK for iOS」一文。

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

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

手動安裝

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

1. 下載 SDK 來源檔案：GoogleMaps-7.4.0。
2. 將來源檔案解除封裝。
3. 如果您還沒有 Xcode 專案，請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「應用程式」範本。
   3. 在專案選項畫面上：
      1. 輸入 [專案名稱]。
      2. 記錄 [軟體包 ID] 欄位的值。 您可以使用這個值來限制您的 API 金鑰。
      3. 將專案 Interface 設定為 Storyboard。
      4. 將「Language」(語言) 設為 [Swift] (切割) 或 [Objective-C] (目標 C)。
4. 將下列套件拖曳至專案中： (系統顯示提示時，請選取 [視需要複製項目，請使用與上述相同的版本)。)
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (僅限付費方案客戶) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
5. 以滑鼠右鍵按一下專案中的 GoogleMaps.xcframework，然後選取 [Show in Finder]。
6. 將 GoogleMaps.bundle 從 Resources 資料夾拖曳至 Xcode 專案的頂層目錄。出現系統提示時，請勿選取 [將項目複製到目標群組的資料夾]。
7. 從「Project Navigator」中選取您的專案，然後為您的應用程式選擇目標。
8. 開啟應用程式目標的「Build Phases」分頁，並在「Link Binary with library」中加入下列架構和程式庫：
   • Accelerate.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. 選擇您的專案 (而不是特定目標)，然後開啟 [Build Settings] 分頁標籤。在「Other Linker Flags」部分中，新增 -ObjC。如果您沒有看到這些設定，請將「Build Settings」列中的篩選器從「Basic」變更為「All」。

10. 如要安裝 Places SDK for iOS，請參閱「開始使用 Places SDK for iOS」一文。

安裝 XCFramework

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

附地毯

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

1. 安裝 Carthage。有數種方法，請參閱 Carthage README 檔案，瞭解實際步驟。
2. 如果您還沒有 Xcode 專案，請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「應用程式」範本。
   3. 在專案選項畫面上：
      1. 輸入 [專案名稱]。
      2. 記錄 [軟體包 ID] 欄位的值。 您可以使用這個值來限制您的 API 金鑰。
      3. 將專案 Interface 設定為 Storyboard。
      4. 將「Language」(語言) 設為 [Swift] (切割) 或 [Objective-C] (目標 C)。
3. 在專案目錄中建立名為 Cartfile 的檔案。此檔案可定義專案的依附元件。

4. 編輯 Cartfile 並新增依附元件及其版本：

   binary "https://dl.google.com/geosdk/GoogleMaps.json" == 6.2.1-beta

5. 儲存 Cartfile。
6. 在終端機視窗中，前往包含 Cartfile 的目錄：
   

   cd <path-to-project>

7. 執行 carthage update 指令。這會安裝在 Cartfile 中指定的 API 及其所有依附元件。
8. 在 Finder 的專案目錄中，前往 Carthage/Build 下下載的已下載架構檔案。
9. 將下列 XCFrameworks 拖曳至專案的架構、程式庫和嵌入內容下。請務必為每個 XCFramework 選取「Do Embed」(不要嵌入)：
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (僅限付費方案客戶) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
10. 在專案中的 GoogleMaps.xcframework 上按一下滑鼠右鍵，然後選取「Show In Finder」。
11. 將 GoogleMaps.bundle 從 ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。當系統提示時，確認「未」選取 [視需要複製項目]。
12. 從「專案導覽工具」中選取您的專案，然後選擇應用程式的目標。
13. 開啟應用程式目標的「Build Phases」分頁，並在「Link Binary with libraries」中新增下列架構和程式庫：
    • Accelerate.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. 選擇您的專案 (而不是特定目標)，然後開啟 [Build Settings] 分頁標籤。在「其他連結器標記」部分新增 -ObjC。如果您沒有看到這些設定，請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。

15. 如要安裝 Places SDK for iOS XCFramework，請參閱開始使用 Places SDK for iOS 一文。

手動

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

1. 下載 SDK 來源檔案：GoogleMaps-7.4.0。
2. 將來源檔案解壓縮。前往 Frameworks (資料夾) 資料夾，以存取 XCFramework。
3. 如果您還沒有 Xcode 專案，請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手：
   1. 建立新專案。
   2. 選取「iOS」>「應用程式」範本。
   3. 在專案選項畫面上：
      1. 輸入 [專案名稱]。
      2. 記錄 [軟體包 ID] 欄位的值。 您可以使用這個值來限制您的 API 金鑰。
      3. 將專案 Interface 設定為 Storyboard。
      4. 將「Language」(語言) 設為 [Swift] (切割) 或 [Objective-C] (目標 C)。
4. 將下列 XCFrameworks 拖曳至專案的架構、程式庫和嵌入內容下。請務必為每個 XCFramework 選取「Do Embed」(不要嵌入)：
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (僅限付費方案客戶) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
5. 在專案中的 GoogleMaps.xcframework 上按一下滑鼠右鍵，然後選取「Show In Finder」。
6. 將 GoogleMaps.bundle 從 ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。當系統提示時，確認「未」選取 [視需要複製項目]。
7. 從「專案導覽工具」中選取您的專案，然後選擇應用程式的目標。
8. 開啟應用程式目標的「Build Phases」分頁，並在「Link Binary with libraries」中新增下列架構和程式庫：
   • Accelerate.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. 選擇您的專案 (而不是特定目標)，然後開啟 [Build Settings] 分頁標籤。在「其他連結器標記」部分新增 -ObjC。如果您沒有看到這些設定，請將「Build Settings」列中的篩選器從 [Basic] 變更為 [All]。

10. 如要安裝 Places SDK for iOS XCFramework，請參閱開始使用 Places SDK for iOS 一文。

步驟 3：將 API 金鑰加進專案

在「取得 API 金鑰」中，您已為應用程式產生 API 金鑰，現在請將該金鑰新增到您的 Xcode 專案中。

請將以下範例中的 YOUR_API_KEY 替換成您的 API 金鑰。

注意： 如果您記錄了專案的 Bundle ID 或從專案屬性中取得，您可以在 API 金鑰中限制這個 API 金鑰僅用於具有特定套件 ID 的 iOS 應用程式。詳情請參閱限制 API 金鑰。

Swift

將 API 金鑰新增到您的 AppDelegate.swift 中，如下所示：

1. 新增下列匯入陳述式：

   import GoogleMaps

2. 將 API 金鑰新增到您的 application(_:didFinishLaunchingWithOptions:) 方法中：

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. 如果您也使用了 Places API，請再次新增金鑰，如下所示：

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

將 API 金鑰新增到您的 AppDelegate.m 中，如下所示：

1. 新增下列匯入陳述式：

   @import GoogleMaps;

2. 將 API 金鑰新增到您的 application:didFinishLaunchingWithOptions: 方法中：

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. 如果您也使用了 Places API，請再次新增金鑰，如下所示：

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

步驟 4 (選用)：選擇採用金屬顯示架構

Maps SDK for iOS 可讓您選擇使用 Apple 的 Metal 轉譯架構。如要在應用程式中試用 Metal 轉譯器，請在建立任何地圖檢視前，呼叫 Objective-C 中的 [GMSServices setMetalRendererEnabled:YES] 或 Swift 中的 GMSServices.setMetalRendererEnabled(true)。

如果您要手動安裝 SDK，則必須一併在 Xcode 中新增 Metal.framework。

步驟 5：新增地圖

以下程式碼示範如何在現有的 ViewController 中新增簡易地圖：

1. 在應用程式的預設 ViewController 中新增或更新方法，以建立並初始化 GMSMapView 的執行個體。

   將範例程式碼中的 ViewController 執行個體全部替換為您的檢視控制器名稱。

   Swift

   /*
    * Copyright 2020 Google Inc. All rights reserved.
    *
    *
    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
    * file except in compliance with the License. You may obtain a copy of the License at
    *
    *     http://www.apache.org/licenses/LICENSE-2.0
    *
    * Unless required by applicable law or agreed to in writing, software distributed under
    * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
    * ANY KIND, either express or implied. See the License for the specific language governing
    * permissions and limitations under the License.
    */
   
   import UIKit
   import GoogleMaps
   
   class ViewController: UIViewController {
   
       override func viewDidLoad() {
           super.viewDidLoad()
           // Do any additional setup after loading the view.
           // Create a GMSCameraPosition that tells the map to display the
           // coordinate -33.86,151.20 at zoom level 6.
           let camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
           let mapView = GMSMapView.map(withFrame: self.view.frame, camera: camera)
           self.view.addSubview(mapView)
   
           // Creates a marker in the center of the map.
           let marker = GMSMarker()
           marker.position = CLLocationCoordinate2D(latitude: -33.86, longitude: 151.20)
           marker.title = "Sydney"
           marker.snippet = "Australia"
           marker.map = mapView
     }
   }
   
         

   Objective-C

   /*
   * Copyright 2020 Google Inc. All rights reserved.
   *
   *
   * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
   * file except in compliance with the License. You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software distributed under
   * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
   * ANY KIND, either express or implied. See the License for the specific language governing
   * permissions and limitations under the License.
   */
   
   #import "ViewController.h"
   #import <GoogleMaps/GoogleMaps.h>
   
   @interface ViewController ()
   
   @end
   
   @implementation ViewController
   
   - (void)viewDidLoad {
       [super viewDidLoad];
     // Do any additional setup after loading the view.
     // Create a GMSCameraPosition that tells the map to display the
     // coordinate -33.86,151.20 at zoom level 6.
     GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.86
                                                             longitude:151.20
                                                                  zoom:6];
     GMSMapView *mapView = [GMSMapView mapWithFrame:self.view.frame camera:camera];
     mapView.myLocationEnabled = YES;
     [self.view addSubview:mapView];
   
     // Creates a marker in the center of the map.
     GMSMarker *marker = [[GMSMarker alloc] init];
     marker.position = CLLocationCoordinate2DMake(-33.86, 151.20);
     marker.title = @"Sydney";
     marker.snippet = @"Australia";
     marker.map = mapView;
   }
   
   @end
   ViewController.m
         

2. 執行您的應用程式。您應該會看到一份地圖，上面有一個以澳洲雪梨為中心的標記。如果看到標記，但地圖未顯示，請確認是否已提供 API 金鑰。

步驟 6 (選用)：宣告 API 使用的網址配置

從 iOS 9 和 Xcode 7 開始，應用程式可以在應用程式的 Info.plist 檔案中指定配置，以宣告即將開啟的網址配置。只要使用者按一下地圖上的 Google 標誌，Maps SDK for iOS 就會開啟 Google 地圖行動應用程式，您的應用程式即可宣告相關的網址配置。

如要宣告 Maps SDK for iOS 使用的網址配置，請在 Info.plist 中新增下列程式碼：

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>googlechromes</string>
    <string>comgooglemaps</string>
</array>

以下螢幕截圖顯示 Xcode 使用者介面的設定：

如果沒有上述宣告，當使用者輕觸地圖上的 Google 標誌時，可能會發生下列錯誤：

-canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
-canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

如要排除這些錯誤，請按照上述說明在 Info.plist 中新增宣告。

後續步驟

現在您已具備 API 金鑰和 Xcode 專案，因此可以建立及執行應用程式。Maps SDK for iOS 提供許多教學課程和範例應用程式，可協助您快速上手。相關詳情請參閱：

• 程式碼範例
• 教學課程
  • 加入含有標記的地圖
  • 在地圖上選取 [目前位置] 和 [顯示詳細資訊]
  • 反向地理編碼
• 程式碼研究室
• 地圖解決方案