设置 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 > 应用模板。
    3. 在项目选项屏幕上:
      1. 输入项目名称
      2. 记录软件包标识符字段的值。 您可以使用下面的值来限制您的 API 密钥。
      3. 将项目 Interface 设置为 Storyboard
      4. 语言设置为 SwiftObjective-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.2.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

Maps SDK for iOS 可与 Carthage 配合使用,Carthage 是一个适用于 Swift 和 Objective-C Cocoa 项目的简单、分散式依赖项管理器。

  1. 安装 Carthage。有多种方法,请参阅 Carthage README 文件,了解具体步骤。
  2. 如果您还没有 Xcode 项目,请立即创建一个并将其保存到您的本地机器。如果您是 iOS 开发新手:
    1. 创建新项目。
    2. 依次选择 iOS > 应用模板。
    3. 在项目选项屏幕上:
      1. 输入项目名称
      2. 记录软件包标识符字段的值。 您可以使用下面的值来限制您的 API 密钥。
      3. 将项目 Interface 设置为 Storyboard
      4. 语言设置为 SwiftObjective-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 项目的顶层目录中。出现提示时,确保选择将项目复制到目标组的文件夹中
  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”(构建设置)标签页。在“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.2.0
  2. 解压缩源文件。
  3. 如果您还没有 Xcode 项目,请立即创建一个并将其保存到您的本地机器。如果您是 iOS 开发新手:
    1. 创建新项目。
    2. 依次选择 iOS > 应用模板。
    3. 在项目选项屏幕上:
      1. 输入项目名称
      2. 记录软件包标识符字段的值。 您可以使用下面的值来限制您的 API 密钥。
      3. 将项目 Interface 设置为 Storyboard
      4. 语言设置为 SwiftObjective-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 项目的顶层目录中。出现提示时,确保选择将项目复制到目标组的文件夹中
  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”(构建设置)标签页。在“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 中配置您的构建设置。

带 Carthage

Maps SDK for iOS 可与 Carthage 配合使用,Carthage 是一个适用于 Swift 和 Objective-C Cocoa 项目的简单、分散式依赖项管理器。

  1. 安装 Carthage。有多种方法,请参阅 Carthage README 文件,了解具体步骤。
  2. 如果您还没有 Xcode 项目,请立即创建一个并将其保存到您的本地机器。如果您是 iOS 开发新手:
    1. 创建新项目。
    2. 依次选择 iOS > 应用模板。
    3. 在项目选项屏幕上:
      1. 输入项目名称
      2. 记录软件包标识符字段的值。 您可以使用下面的值来限制您的 API 密钥。
      3. 将项目 Interface 设置为 Storyboard
      4. 语言设置为 SwiftObjective-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 项目的顶层目录中。出现提示时,请确保选择 Copy items if needed
  12. 从 Project Navigator 中选择您的项目,然后选择应用的目标。
  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 标签页。在 Other Linker Flags(其他链接器标记)部分中,添加 -ObjC。如果看不到这些设置,请将构建设置栏中的过滤条件从基本更改为全部

  15. 要安装 Places SDK for iOS XCFramework,请参阅开始使用 Places SDK for iOS

手动

本指南介绍了如何将 Maps SDK for iOS 手动添加到您的项目中,并配置 Xcode 中的构建设置。

  1. 下载 SDK 源文件:GoogleMaps-7.2.0-beta-xcframework
  2. 解压缩源文件。
  3. 如果您还没有 Xcode 项目,请立即创建一个并将其保存到您的本地机器。如果您是 iOS 开发新手:
    1. 创建新项目。
    2. 依次选择 iOS > 应用模板。
    3. 在项目选项屏幕上:
      1. 输入项目名称
      2. 记录软件包标识符字段的值。 您可以使用下面的值来限制您的 API 密钥。
      3. 将项目 Interface 设置为 Storyboard
      4. 语言设置为 SwiftObjective-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 项目的顶层目录中。出现提示时,请确保选择 Copy items if needed
  7. 从 Project Navigator 中选择您的项目,然后选择应用的目标。
  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 标签页。在 Other Linker Flags(其他链接器标记)部分中,添加 -ObjC。如果看不到这些设置,请将构建设置栏中的过滤条件从基本更改为全部

  10. 要安装 Places SDK for iOS XCFramework,请参阅开始使用 Places SDK for iOS

第 3 步:将您的 API 密钥添加到项目中

获取 API 密钥中,您为应用生成了 API 密钥。现在,您需要将该密钥添加到您的 Xcode 项目中。

在以下示例中,将 YOUR_API_KEY 替换为您的 API 密钥。

Swift

按照以下方法向 AppDelegate.swift 添加 API 密钥:

  1. 添加以下 import 语句:
    import GoogleMaps
  2. 使用 API 密钥将以下代码添加到 application(_:didFinishLaunchingWithOptions:) 方法中:
    GMSServices.provideAPIKey("YOUR_API_KEY")
  3. 如果您也使用 Places API,请按如下所示重新添加密钥:
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

按照以下方法向 AppDelegate.m 添加 API 密钥:

  1. 添加以下 import 语句:
    @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 提供了许多可帮助您入门的教程和示例应用。如需了解详情,请参阅以下资源: