Home API Android 示例应用

示例应用展示了适用于 Android 的 Google Home API 的基本功能。

前提条件

如需构建、安装和测试应用，您需要满足以下几项前提条件：

  • Android Studio 2024.2.1 版（“Ladybug”）或更高版本。 请注意，早于此版本的版本可能无法与 Home APIs SDK 正常搭配使用。

    下载 Android Studio

  • Android 调试程序 (adb)。

    安装 adb。

    这可以通过 SDK 管理器完成。

如需测试 Home API，您需要：

  • 一部搭载 Android 10 或更高版本的 Android 设备，该设备已设置您打算用于开发的 Google 账号。确保已安装最新版本的 Android Studio，并使用此开发者账号登录。
  • Wi-Fi 网络。
  • 如需访问和控制 Matter 设备，您还需要一个支持 Home API 的 Google Hub。如需了解详情，请参阅 Android 上的连接 。

  • 住宅中至少有一台受支持的设备。如果此设备（或您要测试的任何其他设备）使用 Thread，则 hub 也必须是 Thread Border Router (TBR)。Android 示例应用支持以下设备类型和特征：

    • 色温灯（开关、亮度）
    • 接触传感器（布尔值状态）
    • 可调光灯（开关、亮度）
    • 门锁
    • 扩展彩色灯（开和关、亮度）
    • 通用开关
    • Google 边界路由器
    • Google 相机
    • Google 门铃
    • 在家/外出传感器（在家/外出感知）
    • 开关灯（开和关、亮度）
    • 电灯开关
    • 开关插接单元（开和关）
    • 开/关传感器

下载源代码

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

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

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

设置 SDK

此公开 Beta 版中的 Home API for Android 尚未纳入 Google 提供的标准开发库。如需使用 Home API 开发 Android 应用，您需要在本地下载并托管这些库。

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

立即登录！

构建应用

  1. 打开 Android Studio，然后打开克隆到本地机器的 google-home-api-sample-app-android 项目文件夹。

  2. 在首次设置期间，Android Studio 最多可能需要 10 分钟才能下载所有项目依赖项并完成 Gradle 构建。

  3. 通过 USB 线将计算机连接到实体 Android 手机，并在开发者选项中启用 ADB。确保 Android Studio 可以通过 ADB 连接到 Android 手机。

  4. 将示例应用的软件包名称更改为之前未注册过的新名称，例如基于贵组织名称的名称：

    1. 打开项目。
    2. 展开来源层次结构。
    3. 选择要更改的软件包部分，即 com.example。
    4. 右键点击该软件包，然后依次选择 Refactor > Rename… “Refactor”>“Rename”菜单
    5. 输入新名称，然后点击 Refactor。
    6. 修改 build.gradle.kts 文件，将 android namespace 和 applicationId 更改为新的软件包名称。

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

    val homeConfig = HomeConfig(
  coroutineContext = Dispatchers.IO,
  factoryRegistryProvider = {
    FactoryConstants.factoryRegistryAllTraitsAllTypes
  },
  homePlatformScope =
    HomeConfig.HomePlatformScope.HOME_PLATFORM_SCOPE_VERSION_1
)

此外，在 HomeClientProvider.kt 的 switchAccount() 中将 homePlatformScope 更新为 HOME_PLATFORM_SCOPE_VERSION_1。否则，选择个人资料图标切换账号会将应用还原为 HOME_PLATFORM_SCOPE_VERSION_2。

  1. 下载完所有必需的库并完成 Gradle 同步后，点击 Run 按钮以构建并运行应用。当应用在手机上成功运行后，您会看到示例应用主页面。

创建签名证书

当您在 Android Studio 中运行或调试应用时，它会自动生成一个用于开发和调试的调试证书。如需查看完整说明，请参阅 Android Studio：为调试 build 签名。

  1. 通过在 Android Studio 中运行应用来生成调试应用签名证书。当您在 Android Studio 中运行或调试应用时，Android Studio 会自动生成一个用于开发和调试的应用签名证书。如需查看完整说明，请参阅 Android Studio：为调试 build 签名。

    将移动设备连接到本地机器。 Android Studio 会按型号列出已连接的设备。从列表中选择您的设备，然后点击 Run project。这会在您的移动设备上构建并安装示例应用。

    如需了解更详细的说明，请参阅 Android 开发者网站上的在硬件设备上运行应用。

    现在，停止正在运行的应用。

  2. 按照 Google Cloud 控制台帮助网站上的管理 OAuth 客户端 / 应用类型 / 原生应用 / Android 中详述的说明，获取调试证书的 SHA-1 指纹。

  1. 在 Google Cloud 控制台中，前往项目选择器信息中心，然后选择要用于创建 OAuth 凭证的项目。
  2. 前往 API 和服务页面，然后点击导航菜单中的凭证。

  3. 如果您尚未为此 Google Cloud 项目配置权限请求页面，系统会显示配置权限请求页面按钮。在这种情况下，请按照以下步骤配置权限请求页面。否则，请继续阅读下一部分。

    1. 点击配置权限请求页面。系统会显示 OAuth 权限请求页面。
    2. 根据您的应用场景，选择内部或外部，然后点击创建。系统会显示 OAuth 权限请求页面窗格。
    3. 根据屏幕上的说明在应用信息页面上输入信息，然后点击保存并继续。系统会显示范围窗格。
    4. 您无需添加任何范围，因此请点击保存并继续。系统会显示测试用户窗格。
    5. 点击目标对象，然后点击 + 添加用户按钮。
    6. 输入您的测试用户邮箱，然后点击保存按钮。
    7. 点击保存并继续。系统随即会显示摘要窗格。
    8. 查看您的 OAuth 权限请求页面信息，然后点击返回信息中心。

如需了解完整详情，请参阅 Google Cloud 控制台帮助网站上的设置 OAuth 权限请求页面。 请务必先添加至少一个测试用户，然后再继续。

设置 OAuth 凭证

  1. 按照设置 OAuth 2.0 中的说明，为 OAuth 2.0 注册示例应用并创建 OAuth 凭据。
    1. 指明应用类型，即原生/Android 应用。
    2. 按照 Google Cloud 控制台帮助网站上的设置 OAuth 2.0 / 原生应用 / Android 中的说明，将 SHA-1 指纹添加到 OAuth 客户端。在整个开发过程中，您应通过默认的 Android Studio 密钥生成 SHA-1 密钥。

运行应用

  1. 将移动设备连接到本地机器后，再次点击 Run project（运行项目），在移动设备上运行示例应用。

安装后，该应用会在您的移动设备上显示为 Home API 示例应用。