設定 Xcode 專案

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

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

步驟 1:安裝必要軟體

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

  • Xcode 14.0 版或以上版本
  • Cocoapods

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

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

使用 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. 記錄「Bundle ID」欄位的值。您可以使用該值限制下方的 API 金鑰。
      3. 將專案的「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」或「Objective-C」
  2. 在專案目錄中建立名為 Podfile 的檔案。這個檔案定義了專案的依附元件。
  3. 編輯 Podfile,並新增依附元件及其versions。以下範例包含 Maps SDK for iOS 所需的依附元件:
    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '14.0'
    
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'GoogleMaps', '8.3.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 更新為最新版本。

手動安插

本指南將說明如何手動將包含 Maps SDK for iOS 的 XCFrameworks 加到專案中,並在 Xcode 中調整版本設定。XCFramework 是可用於多個平台的二進位套件,包括採用 Apple 晶片的機器。
  1. 下載下列 SDK 二進位檔和資源檔案:
  2. 將 ZIP 檔案解壓縮以存取 XCFrameworks 和資源。
  3. 如果您還沒有 Xcode 專案,請立即建立專案,並儲存至本機電腦。如果您是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS」>「應用程式」範本。
    3. 在專案選項畫面上:
      1. 輸入專案名稱
      2. 記錄「Bundle ID」欄位的值。您可以使用該值限制下方的 API 金鑰。
      3. 將專案的「Interface」設為「Storyboard」
      4. 將「Language」(語言) 設為「Swift」或「Objective-C」
  4. 將下列 XCFrameworks 拖曳至「Frameworks、Library」和「Embedded Content」專案下方。請務必為每個 XCFramework 選取「Do Not Embed」
    • GoogleMaps.xcframework
    • GoogleMapsBase.xcframework
    • GoogleMapsCore.xcframework
    • (僅限付費方案客戶) GoogleMapsM4B.xcframework
  5. 將您下載的 GoogleMapsResourcesGoogleMaps.bundle 拖曳到 Xcode 專案的頂層目錄。系統提示時,請務必選取「Copy items 如有需要」
  6. 從「Project Navigator」中選取您的專案,然後選擇應用程式的目標。
  7. 在應用程式的目標中開啟「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
  8. 選擇您的專案 (而非特定目標),然後開啟「Build Settings」分頁。在「Other Linker Flags」(其他連結器旗標) 區段中,新增 -ObjC如果找不到這些設定,請將「Build Settings」列中的篩選器從「Basic」變更為「All」

  9. 如要安裝 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:新增地圖

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 options = GMSMapViewOptions()
        options.camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
        options.frame = self.view.bounds

        let mapView = GMSMapView(options: options)
        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.
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
  options.frame = self.view.bounds;
  GMSMapView *mapView = [[GMSMapView alloc] initWithOptions:options];

  [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

步驟 5 (選用):宣告 API 使用的網址配置

從 iOS 9 和 Xcode 7 開始,應用程式可以在應用程式的 Info.plist 檔案中指定配置,藉此宣告要開啟的網址配置。使用者在地圖上點選 Google 標誌時,Maps SDK for iOS 會開啟 Google 地圖行動應用程式,而您的應用程式可宣告相關網址配置。

如要宣告 Maps SDK for iOS 使用的網址配置,請在 Info.plist 中加入下列程式碼:

LSApplicationQueriesSchemes googlechromes comgooglemaps

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

Xcode 中的 LSApplicationQuerySchemes 設定

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

-canOpenURL: failed for URL: "comgooglemaps://" - error: "這個應用程式無法

為避免這些錯誤,請在 Info.plist 中加入宣告。

後續步驟

您已取得 API 金鑰和 Xcode 專案,接下來就可以建立並執行應用程式了。Maps SDK for iOS 提供許多教學課程和範例應用程式,協助您踏出第一步。相關詳情請參閱: