設定 Xcode 專案

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

啟用帳單並建立 API 金鑰後,您就可以設定用來開發應用程式的 Xcode 專案。

步驟 1:安裝所需軟體

如要使用 Maps SDK for iOS 建立專案,您必須下載並安裝以下項目:

  • Xcode 13.0 以上版本
  • CocoaPodsCarthage

步驟 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 > App」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄 [Bundle ID] 欄位的值。 您可以使用這個值來限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」(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.1.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 更新為最新版本。

使用基地台

Maps SDK for iOS 可與 Carthage 搭配使用。這款簡易的依附元件依附元件是 Swift 和 Objective-C Cocoa 專案的集中式依附元件管理員。

  1. 安裝 Carthage。存在的方法有很多,因此請參閱 Carthage README 檔案,瞭解實際步驟。
  2. 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS > App」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄 [Bundle ID] 欄位的值。 您可以使用這個值來限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」(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.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
    • (僅限付費方案客戶) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
  10. 以滑鼠右鍵按一下專案中的 GoogleMaps.framework,然後選取 [Show in Finder]
  11. GoogleMaps.bundleResources 資料夾拖曳至 Xcode 專案的頂層目錄。出現提示時,請「不要」選取 [將項目複製到目的地群組's 資料夾]
  12. 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
  13. 開啟應用程式目標的「建構階段」分頁,然後在「連結程式庫與二進位檔」中新增下列架構和程式庫:
    • 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.1.0
  2. 將來源檔案解除封裝。
  3. 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS > App」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄 [Bundle ID] 欄位的值。 您可以使用這個值來限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」(Swift) 或「Objective-C」(目標-C)
  4. 將下列套件拖曳至專案中 (如果系統提示,請選取 [複製項目,請使用與上述相同的版本])。
    • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
    • (僅限付費方案客戶) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
  5. 以滑鼠右鍵按一下專案中的 GoogleMaps.framework,然後選取 [Show in Finder]
  6. GoogleMaps.bundleResources 資料夾拖曳至 Xcode 專案的頂層目錄。出現提示時,請「不要」選取 [將項目複製到目的地群組's 資料夾]
  7. 從「Project Navigator」中選取您的專案,然後為您的應用程式選擇目標。
  8. 開啟應用程式目標的「建構階段」分頁,然後在「連結程式庫與二進位檔」中新增下列架構和程式庫:
    • 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 搭配使用。這款簡易的依附元件依附元件是 Swift 和 Objective-C Cocoa 專案的集中式依附元件管理員。

  1. 安裝 Carthage。存在的方法有很多,因此請參閱 Carthage README 檔案,瞭解實際步驟。
  2. 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS > App」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄 [Bundle ID] 欄位的值。 您可以使用這個值來限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」(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.bundleios-arm64_x86_64-simulator/GoogleMaps.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。在系統顯示提示訊息時,確認「未」選取「複製項目」
  12. 在「專案導覽工具」中選取專案,然後選擇應用程式的目標。
  13. 開啟應用程式目標的建構階段分頁,並在使用程式庫連結二進位檔,並新增下列架構和程式庫:
    • 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.1.0-beta-xcframework
  2. 將來源檔案解除封裝。
  3. 如果您還沒有 Xcode 專案,請立即建立專案並儲存至本機電腦。如果你是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS > App」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄 [Bundle ID] 欄位的值。 您可以使用這個值來限制 API 金鑰。
      3. 將專案「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」(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.bundleios-arm64_x86_64-simulator/GoogleMaps.framework/Resources 資料夾拖曳至 Xcode 專案的頂層目錄。在系統顯示提示訊息時,確認「未」選取「複製項目」
  7. 在「專案導覽工具」中選取專案,然後選擇應用程式的目標。
  8. 開啟應用程式目標的建構階段分頁,並在使用程式庫連結二進位檔,並新增下列架構和程式庫:
    • 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 金鑰。

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 (選用):選擇使用 Metal 轉譯架構

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 的執行個體。

    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
    
          
  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 使用者介面的設定:

Xcode 中的 LSApplicationQuerySchemes 設定

如果沒有上述宣告,當使用者輕觸地圖上的 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 提供多種教學課程和範例應用程式,可協助您輕鬆上手。相關詳情請參閱: