构建 iOS 示例应用

此示例 iOS 应用使用 Google Home API。请按照本指南首次构建和运行该应用。

前提条件

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

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

下载 Xcode

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

  1. 一个 Google 账号。
  2. 已注册 Apple Developer Program 的 Apple ID， 用于生成实体设备配置文件。如果尚未创建，注册会产生额外费用，并且可能需要长达 48 小时才能完成。
  3. 已使用测试账号设置的 iOS 设备（而非模拟器），且运行 iOS 16.4 或更高版本。
  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 Portal。
    2. 添加应用群组标识符。例如，它可以采用 group.com.company.commissioning 格式。
  2. 将测试设备注册到开发者 账号。

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

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

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

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

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

    1. 为您的 MatterExtension 确定应用软件包标识符。 该标识符应继承自应用标识符。例如，它可以采用 com.company.HomeApiSample.MatterExtension 格式。
    2. 注册您的应用 ID。 系统提示时，添加 App Group 功能。
    3. 修改新创建的应用 ID，并配置 App Groups 功能以添加在上一步中创建的已注册应用群组标识符。
    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. 输入包含应用标识符和 Apple 开发者 团队 ID 的 软件包 ID。 其他字段是可选的，可以留空。
    3. 点击创建 ，并记下创建的客户端 ID 或 下载 PLIST。稍后将使用此 ID 来启用权限流功能。如需了解详情，请参阅创建授权 凭据 部分。

启用 Home API

启用对 Home API 的访问权限。

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

下载源代码

GitHub 上提供了示例应用的 source code 源代码。

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

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 开发者。

立即登录！

为示例应用配置 Xcode 项目：

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

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

  4. 添加 App Attest 功能：

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

  5. 添加 App Groups 功能。

    添加应用组

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

  6. 更新软件包标识符

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

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

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

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

    • 初始化 SDK 时，为 GoogleHomeAPISampleIOS.swift。
    • RequestHandler.swift
    • CommissioningManager.swift