設定 Xcode 專案

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

版本資訊 版本。

步驟 1:安裝必要軟體

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

  • Xcode 15.0 以上版本

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

Swift 套件管理工具

您可以透過 安裝 Maps SDK for iOS Swift 套件管理工具。如要新增 SDK,請確認您具備 已移除所有現有的 Maps SDK for iOS 依附元件。

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

  1. 開啟 Xcode projectworkspace,然後依序前往「File」>新增套件依附元件
  2. 輸入 https://github.com/googlemaps/ios-maps-sdk 做為網址,然後按下 Enter 鍵 來提取套件,然後點選「Add Package」
  3. 如要安裝特定 version,請將「Dependency Rule」(依附元件規則) 欄位設為 版本化選項對於新專案,建議您指定最新版本並使用「Exact Version」選項。完成後,按一下「新增套件」。
  4. 在「Choose Package Products」視窗中驗證 GoogleMaps (如果為 9.0.0 以下版本,請確認 GoogleMapsGoogleMapsBaseGoogleMapsCore) 將會加入 您指定的main目標完成後,按一下「新增套件」。
  5. 如要驗證安裝狀態,請前往目標的 General 窗格。 在「架構、程式庫和嵌入內容」中,您應該會看到已安裝的套件。 您也可以查看「套件依附元件」「專案導覽器」的 驗證套件及其版本

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

  1. 如果要升級的是 9.0.0 以下版本,請務必移除 下列依附元件:GoogleMapsBaseGoogleMapsCore 和 升級後的費用為 GoogleMapsM4B。請勿移除以下項目的依附元件: GoogleMaps。詳情請參閱 9.0.0 版本資訊

    在 Xcode 專案配置設定中,找到「Frameworks, libraries」 和嵌入內容請使用減號(-) 移除下列架構:

    • GoogleMapsBase (僅適用於從 9.0.0 以下版本升級)
    • GoogleMapsCore (僅適用於 9.0.0 以下版本的升級作業)
    • GoogleMapsM4B (僅適用於 9.0.0 以下版本的升級作業)
  2. 在 Xcode 中,依序前往「File」>「Packages」>「Update To Latest Package Versions」。
  3. 如要驗證安裝狀態,請前往「Project Navigator」的「Package Dependencies」部分 驗證套件及其版本
,瞭解如何調查及移除這項存取權。

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

  1. 關閉 Xcode 工作區。開啟終端機並執行下列指令:
    sudo gem install cocoapods-deintegrate cocoapods-clean 
    pod deintegrate 
    pod cache clean --all
  2. 移除 PodfilePodfile.resolved 和 如果不是 CocoaPods,則使用 Xcode workspace

如要移除手動安裝的現有 Maps SDK for iOS,請按照下列步驟操作:
  1. 在 Xcode 專案配置設定中,找到「Frameworks, libraries」 和嵌入內容請使用減號(-) 移除下列架構:
    • GoogleMaps
    • GoogleMapsBase (僅適用於安裝作業 早於 9.0.0 版)
    • GoogleMapsCore (僅適用於安裝作業 早於 9.0.0 版)
    • GoogleMapsM4B (僅適用於安裝作業 早於 9.0.0 版)
  2. 從 Xcode 專案的頂層目錄中移除 GoogleMaps 套件。

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

手動安裝

本指南將說明如何手動將含有 Maps SDK for iOS 的 XCFramework 新增至專案,並在 Xcode 中完成建構設定。XCFramework 是一種二進位套件,可用於多種平台,包括使用 Apple 晶片的機器。
  1. 下載以下 SDK 二進位檔和資源檔案:
  2. 請解壓縮檔案以存取 XCFrameworks 和資源。
  3. 如果還沒有 Xcode 專案,請立即建立並儲存到 本機電腦如果您是 iOS 開發新手:
    1. 建立新專案。
    2. 選取「iOS」>「App 範本。
    3. 在專案選項畫面中:
      1. 輸入專案名稱
      2. 記下「Bundle identifier」欄位的值。 您可以在下方使用該值限制 API 金鑰。
      3. 將專案的「介面」設為「分鏡表」
      4. 將「Language」(語言) 設為「Swift」或「Objective-C」
  4. 開啟「一般」分頁。將下列 XCFrameworks 拖曳至專案 。請確認 為每個 XCFramework 選取「Do Not Embed」
    • GoogleMaps.xcframework
    • GoogleMapsBase.xcframework
    • GoogleMapsCore.xcframework
  5. GoogleMapsResources 複製 GoogleMaps.bundle 您下載到 Xcode 專案的頂層目錄請務必選取 依系統提示將項目複製到目的地群組的資料夾
  6. 從「Project Navigator」中選取專案,然後選擇 並指定應用程式的目標
  7. 開啟應用程式目標的「Build Phases」分頁。 在「Link Binary with Libraries」中,新增以下內容 架構和程式庫:
    • Accelerate.framework
    • Contacts.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 (僅限使用 OpenGL)
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework
  8. 選擇專案 (而非特定目標) 並開啟 「Build Settings」分頁。在「Linking - General -> Other Linker Flags」部分中,將 -ObjC 新增至「Debug」和「Release」。如果這些 變更未顯示設定,請在「Build Settings」列中變更篩選器 從「基本」改為「全部」。

  9. 如要安裝 Places SDK for iOS XCFramework,請參閱: 開始使用 Places SDK for iOS

步驟 3:檢查 Apple 隱私權資訊清單檔案

Apple 要求 App Store 中的應用程式提供應用程式隱私權詳細資料。如需最新消息和更多資訊,請造訪 Apple App Store 隱私權詳細資訊頁面

Apple 隱私權資訊清單檔案已納入 SDK 的資源套件。如要確認隱私權資訊清單檔案已納入並檢查其中的內容,請建立應用程式的封存檔案,然後從封存檔中產生隱私權報告

步驟 4:將 API 金鑰加進專案

在「取得 API 金鑰」一節中, 一組產生的 API 金鑰現在請將金鑰加進 Xcode 專案,

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

Swift

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

  1. 新增下列匯入陳述式:
    import GoogleMaps
  2. 請將以下內容新增到您的 application(_:didFinishLaunchingWithOptions:) 方法,使用 API 金鑰:
    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"];

步驟 5:新增地圖

Swift

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

#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 檔案中指定配置,藉此開啟應用程式。 Maps SDK for iOS 會在使用者點擊時開啟 Google 地圖行動應用程式 地圖上的 Google 標誌,您的應用程式就可以宣告相關網址 例如,您可以看到

如要宣告 Maps SDK for iOS 使用的網址配置,請將下列行程式碼行新增至 Info.plist

LSApplicationQueriesSchemes googlechromes comgooglemaps

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

LSApplicationQuerySchemes 設定
Xcode

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

  • -canOpenURL:無法輸入網址:「comgooglemaps://」- 錯誤:「這個應用程式不是 可以查詢 comgooglemaps 的架構」
  • -canOpenURL:網址失敗:「googlechromes://」- 錯誤:「這個應用程式不是 允許查詢 googlechrome"

如要排除這些錯誤,請在 Info.plist 中加入宣告。

後續步驟

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