构建 iOS 示例应用

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

前提条件

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

如需构建和安装示例应用，您需要一台安装了 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 中枢。
6. 如果设备需要使用 Thread，但中枢不具备该功能，则需要使用 Thread 边界路由器。
7. 至少一种受支持的设备类型。

对于开发，您需要一台满足以下要求的 Mac：

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

创建 Apple 部署配置文件

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

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

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

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

1. 为应用创建应用组标识符，以便与 MatterExtension 通信。
   1. 登录 Apple Developer 门户。
   2. 添加应用组标识符。例如，可以采用 group.com.company.commissioning 格式。
2. 向开发者账号注册测试设备。

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

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

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

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

      • 如果您尚未创建，请参阅创建开发者 ID 证书以获取相关说明。

4. 为 MatterExtension 目标创建个人资料。

   1. 为 MatterExtension 确定应用软件包标识符。 标识符应继承自应用标识符。例如，它可以采用 com.company.HomeApiSample.MatterExtension 格式。
   2. 注册您的应用 ID。 出现提示时，添加 App Group 功能。
   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。

   

   

   1. 点击创建凭据按钮，然后选择 OAuth 客户端 ID。
      1. 在应用类型下，选择 iOS。
   2. 输入包含应用标识符和 Apple 开发者团队 ID 的软件包 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 上加载项目，请依次点击文件 > 打开，然后在克隆的代码库的根目录中选择 GoogleHomeAPISampleIOS.xcodeproj。

设置 SDK

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

构建应用

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

立即登录！

为示例应用配置 Xcode 项目：

1. 在 Xcode 导航窗格中，选择 GoogleHomeAPISampleIOS 文件以修改项目配置。

   

   

2. 点击顶部的常规标签页，然后选择左侧的目标 GoogleHomeAPISampleIOS。

3. 向下滚动，直到看到框架、库和嵌入内容部分。您应该会看到列出的两个 Home API 框架。

4. 在嵌入列中，为 GoogleHomeSDK.xcframework 选择嵌入和签名。另一个框架 GoogleHomeTypes.xcframework 应保留为 不嵌入。

5. 点击列表底部的 + 图标。

6. 出现提示时，搜索 SafariServices.framework，然后点击添加。确保相应条目的嵌入列设置为不嵌入。

   

   

7. 点击目标下的 MatterAddDeviceExtension 以修改相应目标的定位条件。

8. 向下滚动，直到看到框架和库部分。您应该会看到列出的 GoogleHomeSDK.xcframework。

9. 在嵌入列中，选择不嵌入。

10. 配置开发者和 OAuth 客户端 ID：

    1. 在导航窗格中，找到 GoogleHomeAPISampleIOS 文件夹，然后打开 Info.plist 文件进行修改。

11. 在 Info.plist 文件中，使用您的 OAuth 客户端 ID（请参阅设置 OAuth 许可部分）、与您的云项目对应的 Cloud Project Number 以及在 OAuth 注册过程中使用的开发者账号的 Apple Developer Team ID 填充 GIDClientID 和 GIDTeamID。

12. 添加 App Attest 功能：

    1. 在 Xcode 导航窗格中，选择 GoogleHomeAPISampleIOS 项目文件以修改项目配置。
    2. 点击顶部的签名和功能标签页，然后在左侧的“目标平台”部分下选择目标 GoogleHomeAPISampleIOS。
    3. 在“签名和功能”标签页下方，点击 + 功能，然后搜索 App Attest。
    4. 点击 App Attest 以添加。如果搜索中缺少此功能，则表示项目可能已添加此功能。

13. 添加 App Groups 功能。

    

    

    1. 前往 GoogleHomeAPISampleIOS 项目 > GoogleHomeAPISampleIOS 目标。
    2. 依次点击 Signing & Capabilities > + Capability。
    3. 选择 App Groups 功能。
    4. 点击应用组下方的 + 图标，然后添加您在 Apple Developer Portal 中添加的应用的应用组标识符。
    5. 针对 MatterAddDeviceExtension 目标重复上述步骤，将其添加到 App Groups。

14. 更新软件包标识符

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

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

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

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

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