构建 iOS 示例应用

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

前提条件

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

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

下载 Xcode

如需测试该应用，您需要满足以下条件：

  1. 在 Home API EAP 中注册的 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 功能。因此，它无法部署到模拟器设备。这需要您创建具有应用认证权限的配置文件。

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

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

以下概述了部署应用至少需要完成的一些步骤：

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

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

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

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

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

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

    1. 为 MatterExtension 确定应用软件包标识符。 该标识符应从应用标识符继承。例如，其格式可以为 com.company.HomeApiSample.MatterExtension。
    2. 注册您的应用 ID。出现提示时，添加应用群组 capability。
    3. 修改新创建的应用 ID，并配置应用群组 capability，以添加在上一步中创建的已注册应用群组标识符。
    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 开发者。

立即登录！

为示例应用配置 Xcode 项目：

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

    设置 SDK 示例应用

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

  3. 向下滚动，直到您看到 Frameworks, Libraries, and Embedded Content（框架、库和嵌入内容）部分。您应该会看到两个 Home API 框架。

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

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

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

    嵌入并签名

  7. 点击目标下的 MatterAddDeviceExtension 以修改其目标。

  8. 向下滚动，直到看到 Frameworks and Libraries 部分。您应该会看到 GoogleHomeSDK.xcframework 列出。

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

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

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

  11. 在 Info.plist 文件中，使用您的 OAuth 客户端 ID（请参阅设置 OAuth 意见征求部分）填充 GIDClientID，并使用 OAuth 注册流程中使用的开发者账号的 Apple 开发者团队 ID 填充 GIDTeamID。

  12. 配置构建系统：

    添加链接器标志

    1. 在 Xcode 导航窗格中，选择 GoogleHomeAPISampleIOS 项目文件以修改项目配置。
    2. 点击顶部的 Build Settings（构建设置）标签页，然后选择左侧“TARGETS”（目标）部分下的目标 GoogleHomeAPISampleIOS。
    3. 搜索 Other Linker Flags（其他链接器标志），然后添加两个条目：
      • -lc++
      • -ObjC

  13. 添加 App Attest 功能：

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

  14. 添加 App Groups 功能。

    添加应用组

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

  15. 更新软件包标识符

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

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

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

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

    • 在 SDK 初始化时调用 GoogleHomeAPISampleIOS.swift。
    • RequestHandler.swift
    • CommissioningManager.swift