构建 iOS 示例应用

此示例 iOS 应用使用了 Google Home API。请参阅本指南，首次构建并运行应用。

前提条件

确保您满足使用 Home API for iOS 的最低要求。

如需构建和安装示例应用，您需要一台安装了 Xcode 15.3 或更高版本的计算机。

下载 Xcode

如需测试该应用，您需要：

  1. Google 账号。
  2. 已注册 Apple Developer Program 的 Apple ID，用于生成实体设备配置文件。如果尚未创建，注册会产生额外费用，并且最多可能需要 48 小时才能完成。
  3. 搭载 iOS 16.4 或更高版本且设置了测试账号的 iOS 设备（而非模拟器）。
  4. Wi-Fi 网络。
  5. 支持 Home API 的 Google Hub。
  6. 如果您的设备需要 Thread，而您的 Hub 不具备该功能，则需要 Thread Border Router (TBR)。
  7. 至少一种受支持的设备类型。

如需进行开发，您需要一台满足以下要求的 Mac：

  • macOS Sonoma 或更高版本
  • Xcode 15.3 或更高版本

创建 Apple 部署配置文件

首先，应用需要启用 App Attest 功能。因此，它无法部署到模拟器设备。为此，您需要创建具有 App Attest 权限的预配配置文件。

其次，它需要启用应用群组，以便在应用和 MatterExtension 之间进行通信。这需要您注册应用组标识符。

如需了解详情，请参阅 Apple 关于预配配置文件的创建开发预配配置文件。

以下概述了部署应用所需的最少步骤：

  1. 为您的应用创建一个应用组标识符，以便与 MatterExtension 通信。
    1. 登录 Apple Developer Portal。
    2. 添加应用组标识符。例如，其格式可以为 group.com.company.commissioning。
  2. 将测试设备注册到开发者账号。

  3. 为应用目标创建配置文件。

    1. 为您的应用确定一个应用软件包标识符。该标识符应具有唯一性和描述性。例如，其格式可以为 com.company.HomeApiSample。本部分的其余部分将使用此标识符。
    2. 注册您的应用 ID。 在系统提示时，添加 App Attest 和 App Groups 功能。

    3. 修改新创建的应用 ID，并配置应用组功能以添加已注册的应用组标识符。

    4. 为应用开发创建开发预配配置文件。将其与您新创建的应用 ID 和所选测试设备相关联。确保您有开发者证书，可用于对应用进行签名。

  4. 为 MatterExtension 目标创建配置文件。

    1. 为您的 MatterExtension 确定应用软件包标识符。 该标识符应继承自应用标识符。例如，其格式可以为 com.company.HomeApiSample.MatterExtension。
    2. 注册您的应用 ID。 出现提示时，添加应用组功能。
    3. 修改新创建的应用 ID，并配置应用组功能，以添加在前面步骤中创建的已注册应用组标识符。
    4. 为 MatterExtension 创建开发预配配置文件。

生成 OAuth 客户端 ID 并启用 Home API

您的应用需要一个 OAuth 客户端 ID，以便向 Google 的身份验证后端标识自身。对于 iOS 应用，OAuth 客户端 ID 应用类型必须配置为 iOS。该应用还会调用 Home API。如需启用此功能，必须在 Google Cloud 项目中启用该 API。

生成 OAuth 客户端 ID

  1. 在 Google Cloud 控制台中，前往项目选择器信息中心，然后选择要用于创建 OAuth 凭证的项目。
  2. 依次点击左上角的菜单按钮 > 查看所有产品 > API 和服务，前往“API 和服务”页面。
  3. 在导航菜单中，点击凭证。

  4. 如果您尚未为此 Google Cloud 项目配置权限请求页面，系统会显示配置权限请求页面按钮。在这种情况下，请按照以下步骤配置权限请求页面。如果您的 OAuth 权限请求页面已配置，并且其发布状态为测试，请确保将您要使用的测试账号添加到测试用户群组。否则，请继续执行下一步。

    1. 根据您的应用场景，选择内部或外部，然后点击创建。系统会显示 OAuth 权限请求页面窗格。
    2. 根据屏幕上的说明在应用信息页面上输入信息，然后点击保存并继续。系统会显示“范围”窗格。
    3. 您无需添加任何范围，因此请点击保存并继续。系统会显示测试用户窗格。
    4. 如果您选择创建内部权限请求页面，则必须添加用户来测试对应用的访问权限。点击添加用户。系统会显示添加用户窗格。测试用户有权在您的应用中授予权限。在空白字段中，添加一个或多个 Google 账号邮箱，然后点击添加。
    5. 点击保存并继续。系统随即会显示摘要窗格。
    6. 查看您的 OAuth 权限请求页面信息，然后点击返回信息中心。

  5. 在左侧菜单面板中，点击凭据以创建 OAuth 客户端 ID。

    设置 OAuth 界面

    1. 点击创建凭证按钮，然后选择 OAuth 客户端 ID。
      1. 在应用类型下，选择 iOS。
    2. 输入软件包 ID，其中包含您的应用标识符和 Apple 开发者团队 ID。 其他字段为选填字段，可以留空。
    3. 点击创建，然后记下创建的客户端 ID 或下载 PLIST。稍后，您将使用此功能来启用权限流程功能。如需了解详情，请参阅创建授权凭据部分。

启用 Home API

启用对 Home API 的访问权限。

  1. 在 API 和服务标签页中，点击已启用的 API 和服务。
  2. 点击页面顶部的启用 API 和服务。
  3. 搜索 HOME API 并将其选中。
  4. 在 Home API 详情页面中，点击启用。

下载源代码

示例应用的源代码可在 GitHub 上找到。

前往您想保存项目的位置，然后克隆项目：

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

如需在 Xcode 中加载项目，请依次点击 File > Open，然后在克隆的代码库的根目录中选择 GoogleHomeAPISampleIOS.xcodeproj。

将 SDK 添加到项目中

示例应用项目需要一些额外信息才能构建。 这包括在本地添加 SDK 框架文件、填充开发者账号标识符信息以及填充 OAuth 客户端 ID。

构建应用

如需下载 Home API iOS SDK，您必须先登录 Google Home Developers。

立即登录！

为示例应用配置 Xcode 项目：

  1. 将下载的 SDK 解压缩到相对于项目根目录的 ThirdParty/GoogleHomeSDK 目录中。
  2. 配置开发者 ID 和 OAuth 客户端 ID：
    1. 在导航窗格中，找到 GoogleHomeAPISampleIOS 文件夹，然后打开 Info.plist 文件进行修改。

  3. 在 Info.plist 文件中，使用您的 OAuth 客户端 ID（请参阅设置 OAuth 同意部分）填充 GIDClientID，使用与您的云项目对应的云项目编号填充 Cloud Project Number，并使用 OAuth 注册过程中所用开发者账号的 Apple 开发者团队 ID 填充 GIDTeamID。

  4. 添加 App Attest 功能：

    1. 在 Xcode 导航窗格中，选择 GoogleHomeAPISampleIOS 项目文件以修改项目配置。
    2. 点击顶部的 Signing and Capabilities（签名和功能）标签页，然后在左侧的“TARGETS”（目标）部分下选择目标 GoogleHomeAPISampleIOS。
    3. 在“Signing and Capabilities”（签名和功能）标签页的正下方，点击 + Capability（添加功能），然后搜索 App Attest。
    4. 点击 App Attest 进行添加。如果搜索结果中未显示此功能，则表示项目可能已添加此功能。

  5. 添加 App Groups 功能。

    添加应用组

    1. 前往 GoogleHomeAPISampleIOS 项目 > GoogleHomeAPISampleIOS 目标。
    2. 依次点击 Signing & Capabilities（签名和功能）> + Capability（添加功能）。
    3. 选择 App Groups（应用组）功能。
    4. 点击 App Groups 下的 + 图标，然后添加您在 Apple 开发者门户中为应用添加的应用组标识符。
    5. 对 MatterAddDeviceExtension 目标重复上述步骤，将其添加到 App Groups。

  6. 更新软件包标识符

    1. 如需使用开发者证书和预配配置文件在硬件上成功运行和部署示例应用，您需要提供唯一的软件包标识符。此标识符应与您的 OAuth 客户端凭证关联（见上文）。
    2. 在 Xcode 导航窗格中，选择 GoogleHomeAPISampleIOS 项目文件以修改项目配置。
    3. 点击顶部的 Signing and Capabilities（签名和功能）标签页，然后在左侧的“TARGETS”（目标）部分下选择目标 GoogleHomeAPISampleIOS。
    4. 在签名部分中选择“Bundle Identifier”（软件包标识符）字段，然后输入应用的唯一标识符。
    5. 选择或安装与该软件包相关且具有所需授权的预配配置文件。
    6. 对 MatterAddDeviceExtension 目标重复上述步骤，以输入扩展程序的软件包标识符并导入其已注册的预配配置文件。

  7. 在代码中更新已注册的应用群组标识符。

    1. 应用需要配置 SDK 实例，以便使用应用组标识符来实现设备调试等功能。更新应用，以使用在 Apple 开发者门户中注册的应用群组 ID，方法是搜索字符串 HOME_API_TODO_ADD_APP_GROUP 并将其替换为该 ID。

    这些配置在以下文件中进行：

    • GoogleHomeAPISampleIOS.swift（在 SDK 初始化时）。
    • RequestHandler.swift
    • CommissioningManager.swift

  8. 在 GoogleHomeAPISampleIOS.swift 中配置 OAuth 范围。默认情况下，示例应用源代码使用 https://www.googleapis.com/auth/home.platform.v2 范围。示例应用中的许多功能都受 home.platform.v2 范围限制，需要获得合作伙伴批准才能访问。如需使用标准 https://www.googleapis.com/auth/home.platform.selected.devices 范围运行示例应用，请打开 GoogleHomeAPISampleIOS.swift，并将 Home.configure 中的 homePlatformOAuthScope 更改为 HomePlatformOAuthScope.v1：

    Home.configure {
  $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
  $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
  ...
}