啟用計費功能並建立 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 加入新專案或現有專案,請按照下列步驟操作:
-
開啟 Xcode
project
或workspace
,然後依序前往「File」>新增套件依附元件。 - 輸入 https://github.com/googlemaps/ios-maps-sdk 做為網址,然後按下 Enter 鍵 來提取套件,然後點選「Add Package」
-
如要安裝特定
version
,請將「Dependency Rule」(依附元件規則) 欄位設為 版本化選項如果是新專案,建議您指定最新版本 使用「完全比對版本」如果有需要 SQL 指令的分析工作負載 則 BigQuery 可能是最佳選擇完成後,點選「新增套件」。 -
在「Choose Package Products」視窗中驗證
GoogleMaps
(如果為 9.0.0 以下版本,請確認GoogleMaps
、GoogleMapsBase
和GoogleMapsCore
) 將會加入 您指定的main
目標完成後,點選「新增套件」。 -
如要驗證安裝狀態,請前往目標的
General
窗格。 「Frameworks、Library and Embedded Content」應會顯示已安裝的套件。 您也可以查看「套件依附元件」「專案導覽器」的 驗證套件及其版本
如要更新現有專案的 package
,請按照下列步驟操作:
如果要升級的是 9.0.0 以下版本,請務必移除 下列依附元件:
GoogleMapsBase
、GoogleMapsCore
和 升級後的費用為GoogleMapsM4B
。請勿移除以下項目的依附元件:GoogleMaps
。詳情請參閱 9.0.0 版本資訊。在 Xcode 專案配置設定中,找到「Frameworks, libraries」 和嵌入內容請使用減號(-) 移除下列架構:
GoogleMapsBase
(僅適用於 9.0.0 以下版本的升級作業)GoogleMapsCore
(僅適用於 9.0.0 以下版本的升級作業)GoogleMapsM4B
(僅適用於 9.0.0 以下版本的升級作業)
- 在 Xcode 中,前往 [檔案] >套裝行程 >更新至最新套件版本」。
- 如要驗證安裝狀態,請前往「Project Navigator」的「Package Dependencies」部分 驗證套件及其版本
如要移除現有的 Maps SDK for iOS 依附元件,請使用
CocoaPods
,請按照下列步驟操作:
- 關閉 Xcode 工作區。開啟終端機並執行下列指令:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
移除
Podfile
、Podfile.resolved
和 如果不是 CocoaPods,則使用 Xcodeworkspace
。
-
在 Xcode 專案配置設定中,找到「Frameworks, libraries」
和嵌入內容請使用減號(-) 移除下列架構:
GoogleMaps
GoogleMapsBase
(僅適用於安裝作業 早於 9.0.0 版)GoogleMapsCore
(僅適用於安裝作業 早於 9.0.0 版)GoogleMapsM4B
(僅適用於安裝作業 早於 9.0.0 版)
-
從 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 及其依附元件:
- 如果還沒有 Xcode 專案,請立即建立並儲存到
本機電腦如果您是 iOS 開發新手:
- 建立新專案。
- 選取「iOS」>「App 範本。
- 在專案選項畫面中:
- 輸入專案名稱。
- 記錄「Bundle ID」欄位的值。 您可以在下方使用該值限制 API 金鑰。
- 將專案「Interface」設為「Storyboard」。
- 將「Language」(語言) 設為「Swift」或「Objective-C」。
- 在專案目錄中建立名為
Podfile
的檔案。這個檔案定義了專案的依附元件。 - 編輯
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
以偵測是否有更新 版本,確保隨時使用最新版本。如有需要,請升級至最新版本。 - 儲存
Podfile
。 開啟終端機並前往包含
Podfile
的目錄:cd <path-to-project>
執行
pod install
指令。此動作會安裝Podfile
中指定的 API 及其所有依附元件。pod install
關閉 Xcode,接著按兩下來開啟專案的
.xcworkspace
檔案來啟動 Xcode。從現在起,您必須使用.xcworkspace
檔案來開啟專案。
如要更新現有專案的 API,請按照下列步驟操作:
- 開啟終端機,然後前往包含
Podfile
的專案目錄。 - 執行
pod update
指令。這會更新所有 API 在Podfile
中指定的是最新版本。
手動安裝
本指南說明如何手動將包含 Maps SDK for iOS 的 XCFrameworks 新增至專案,並在 Xcode 中調整版本設定。XCFramework 是一種二進位套件,可用於多種平台,包括使用 Apple 晶片的機器。- 下載以下 SDK 二進位檔和資源檔案:
- 請解壓縮檔案以存取 XCFrameworks 和資源。
- 如果還沒有 Xcode 專案,請立即建立並儲存到
本機電腦如果您是 iOS 開發新手:
- 建立新專案。
- 選取「iOS」>「App 範本。
- 在專案選項畫面中:
- 輸入專案名稱。
- 記錄「Bundle ID」欄位的值。 您可以在下方使用該值限制 API 金鑰。
- 將專案「Interface」設為「Storyboard」。
- 將「Language」(語言) 設為「Swift」或「Objective-C」。
-
開啟「一般」分頁。將下列 XCFrameworks 拖曳至專案
。請確認
為每個 XCFramework 選取「Do Not Embed」:
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
-
從 GoogleMapsResources 複製
GoogleMaps.bundle
您下載到 Xcode 專案的頂層目錄請務必選取 依系統提示將項目複製到目的地群組的資料夾。 - 從「Project Navigator」中選取專案,然後選擇 並指定應用程式的目標
-
開啟應用程式目標的「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
-
選擇專案 (而非特定目標) 並開啟 「Build Settings」分頁。在「連結 - 一般」部分其他連結器 Flags 區段,將
-ObjC
新增至「Debug」和「發布」如果這些 變更未顯示設定,請在「Build Settings」列中變更篩選器 從「基本」改為「全部」。 -
如要安裝 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
中,如下所示:
- 新增下列匯入陳述式:
import GoogleMaps
- 請將以下內容新增到您的
application(_:didFinishLaunchingWithOptions:)
方法,使用 API 金鑰:GMSServices.provideAPIKey("YOUR_API_KEY")
- 如果您也使用 Places API,請再次新增金鑰,如下所示:
GMSPlacesClient.provideAPIKey("YOUR_API_KEY")
Objective-C
將 API 金鑰新增到您的 AppDelegate.m
中,如下所示:
- 新增下列匯入陳述式:
@import GoogleMaps;
- 請將以下內容新增到您的
application:didFinishLaunchingWithOptions:
方法,使用 API 金鑰:[GMSServices provideAPIKey:@"YOUR_API_KEY"];
- 如果您也使用 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
:
以下螢幕截圖顯示 Xcode 使用者介面中的設定:
如果沒有上述宣告,使用者輕觸頁面時可能會發生下列錯誤 地圖上的 Google 標誌:
- -canOpenURL:無法輸入網址:「comgooglemaps://」- 錯誤:「這個應用程式不是 可以查詢 comgooglemaps 的架構」
- -canOpenURL:網址失敗:「googlechromes://」- 錯誤:「這個應用程式不是 允許查詢 googlechrome"
如要避免這些錯誤,請在 Info.plist
中加入宣告。
後續步驟
取得 API 金鑰並設定 Xcode 專案後,接下來請建立並執行應用程式。 iOS 版 Navigation SDK 提供許多教學課程和範例應用程式, 生成式 AI 模型相關詳情請參閱: