Home API Android SDK 版本说明

2026-02-09

  Home API 公开 Beta 版 1.7  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：26.02.34
• Google 集线器的最低固件版本：
  • 投放：
    • Nest WiFi Pro：3.76.508025
    • 所有其他基于 Cast 的 hub：3.77.510748
  • Fuchsia：29.20251023.103.2100
  • Google TV Streamer（4K）：UTTK.250729.004
• Android SDK：home.android.sdk_GHP_1_7
• Google Home 应用：1.7
• androidx.core 库：适用于任何版本
• Matter 版本：1.4.1.0，实验性支持 1.5.0。

新功能

• Automations API
  • 本地自动化操作：现在，某些自动化操作可能会在本地执行，具体取决于连接情况、设备类型和特征等条件。
• Device API
  • 在应用中启用相机开箱体验 (OOBE)。
  • 新的摄像头和门铃设备功能

    如需了解详情，请参阅 Android 的相机设备指南和 Android 的门铃设备指南。

  • 设置
    • 铃声主题。
    • 自动省电模式。
    • 电池用量偏好设置。
  • 设备状态
    • 电池充电状态。
    • 电池电量。
  • 设备信息
    • 序列号。
    • Model 的实例化类名称定义。
    • 软件版本。

Permissions API

• 借助权限查询，应用可以确定用户已向哪些设备类型授予访问权限。

其他值得注意的变更

• HomeException.unsupported 已替换为 HomeException.unimplemented，以与标准错误代码保持一致。
• 自定义特征的封装代码生成器已针对版本 1.7 发生更改。 如果开发者拥有自定义特征，则在集成 1.7 SDK 后，需要重新编译这些特征。

修复的已知问题

• History API 始终返回 nextPageToken，从而导致无限循环。
• 尝试登录新账号时出现“用户取消了权限流程”错误。

已知问题

• 对于 Nest Cam 室内/室外摄像头（电池版或有线版）和 Nest Doorbell（电池版，第 2 代），电池设置中没有“剩余电池续航时间”选项。
• 系统会忽略提示音时长设置。
• 即使设备实际上处于离线状态，Philips BLE 灯也会错误地显示为“在线”。
  • 解决方法：不要仅依赖智能家居设备类型 (SHDT) 在线状态。 对于具有 LOCAL_SYNC 源的设备，请改用目标设备状态服务 (TDSS) 映射。

2025-12-22

  Home API 公开 Beta 版版本 1.6  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.47.30
• Google 集线器的最低固件版本：
  • 投放：
    • Nest WiFi Pro：3.75.479819
    • 所有其他基于 Cast 的 hub：3.77.505721
  • Fuchsia：28.20250723.103.2100300
  • Google TV Streamer（4K）：UTTK.250729.004
• Android SDK：home.android.sdk_GHP_1_6
• Google Home 应用：1.6
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.1.0

新功能

• Automation API
  • 天气特征支持

    在自动化操作启动方式和条件中添加了对天气特征的支持。请参阅基于天气情况的启动方式。

• Device API
  • 支持更多摄像头和门铃设备功能：
    • 新设置：
      • 夜视模式开启/关闭。
      • 状态 LED 亮度。
      • 相机视口。
      • 图片方向。
      • 唤醒灵敏度。
      • 事件录制时长上限。
      • 铃声。

      如需了解详情，请参阅 Android 相机设备指南。

• 连接
  • 应用发起的 Google 登录，可让应用使用 Google 账号信息初始化 HomeClient，从而简化用户体验流程，并消除检查哪个用户正在运行应用的需求。

  • 无中枢模式

    用户现在无需使用独立 hub 即可完成某些 Matter 设备的初始配置并对其进行控制。

• Structure API
  • 新增了 Hub Activation API，可让应用发现和激活 Hub。

• Android 示例应用
  • 摄像头和门铃设置
    • 麦克风开/关。
    • 录音功能开启/关闭。
  • 预定义的自动化操作
  • 添加了对风扇和音箱设备类型的支持。
• 应用发起的 Google 登录。

已知问题

• 设备控件在长时间使用后停止工作。
  • 解决方法：重启 hub。
• Matter 设备调试可能会失败。
• 尝试在 Android 版示例应用中添加新账号时，出现“User cancelled Permission flow”错误。
  • 解决方法：通过 Android 设备设置添加 Google 账号。
• 使用 Android Home API SDK 调试的 Walmart onn 有线安防摄像头无法通过 Google Home 应用进行直播。

2025-10-23

  Home API 公开 Beta 版 1.5.1  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.41.30
• Google 集线器的最低固件版本：
  • Cast：3.76.495998
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_5_1
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.1.0

新功能

• Structure API
  • 借助 Hub 激活 API，您可以程序化地发现和激活 Google Home Hub。请参阅 Android 上的 Hub 激活 API。
    
• Android 示例应用
  • 支持的门铃设备类型：
    • OnOff
    • 直播
    • 双向对讲
  • Hub 激活 API：激活 Hub

修复的已知问题

• 示例应用未在设备视图中正确显示设备状态。

2025-09-26

  Home API 公开 Beta 版 1.5.0  

此版本引入了对相机设备的支持，包含 bug 修复，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.37.31
• Google 集线器的最低固件版本：
  • Cast：3.76.492738
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_5
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.1.0

新功能

• Automation API
  • 启动方式、条件和操作现在接受 Matter 结构作为参数。
• Device API
  • 添加了 相机设备类型。以下摄像头功能也适用于门铃设备类型：
  • 摄像头实时画面。
  • 摄像头双向对讲。
  • 相机开始和停止录制。
• Android 示例应用
  • 支持相机设备类型：
    • 摄像头实时画面。
    • 摄像头双向对讲。
    • 相机开始和停止录制。
    • 受限的设备类型权限。
  • 多管理员调试（共享已调试的设备）。
  • 预定义的 OnOff 自动化操作。

已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 由云到云支持的风扇设备类型的控制可能无法在示例应用中正常运行。

修复的已知问题

• 如果强制移除当前处于活动状态的 Hub，则在五分钟的时间内，无法控制某些设备。5 分钟后，设备控制功能会恢复。
• 用户从预设或色温选择器中选择颜色后，扩展颜色灯无法更新颜色。

2025-09-08

适用于 Android 的示例应用版本 1.4.1 已发布。

新功能

• 创建、重命名、更新和删除会议室。
• 调试到第三方 Matter 结构。

修复的已知问题

• 权限撤消页面链接现在可以正常使用。

2025-08-29

  Home API 公开 Beta 版版本 1.4.1  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.33.32
• Google 集线器的最低固件版本：
  • Cast：3.76.495998
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_4_1
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Device API
  • 定义了一个新的 DecommissionIneligibleReason，用于尝试停用多来源设备。请参阅 多来源设备。

已知问题

• 如果强制移除当前处于活动状态的 Hub，则在五分钟的时间内，无法控制某些设备。5 分钟后，设备控制功能会恢复。

修复的已知问题

• 当用户尝试将温控器设置为不支持的模式时，Android 示例应用会崩溃。

2025-07-31

  Home API 公开 Beta 版 1.4.0  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.28.34
• Google 集线器的最低固件版本：
  • Cast：3.76.486931
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_4_0
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Automation API
  • 自动化操作可以限制为最多执行有限次数。请参阅限制执行次数。

• Device API
  • 以编程方式移除 Matter 设备的功能。请参阅移除设备。
  • 以下已弃用的 HomeDevice 成员已被移除：
    1. HomeDevice.trait()。请参阅 访问 Android 设备和设备元数据。
    2. HomeDevice.isInRoom。请改用 HomeDevice.roomId。
    3. HomeDevice.isInStructure。请改用 HomeDevice.structureId。
• Structure API
  • Home.hasPermissions() 现在同时包含用户的 OAuth 授权状态（对结构的访问权限）以及应用权限授予。
• Android 示例应用
  • 替换了已弃用的 API 调用。
  • 重命名设备。
  • 删除仅支持 Matter 的设备。

已知问题

• 在手机上退出登录并重新登录后，Home API 应用无法控制设备。
  • 解决方法：关闭应用或将其置于后台，然后等待至少 10 秒再重试。

修复的已知问题

• 已放置在基座上的吸尘器设备未注册“已放置在基座上”状态。

2025-07-08

借助 Cast 固件版本 3.76.479819，Nest WiFi Pro 现在可以充当 Home API 中枢。

2025-06-26

  Home API 公开 Beta 版 1.3.2  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.23.31
• Google 集线器的最低固件版本：
  • 投放：
    • Google Home、Google Home Mini 和 Google Nest Mini：3.75.468362
    • Google Nest Audio：3.75.476451
  • Fuchsia：26.20250116.103.2900
• Android SDK：home.android.sdk_1_3_2
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• SDK 制品已分为两个单独的制品：
  • Home API SDK 框架 (play-services-home-17.0.0.aar)
  • SDK 特征和设备类型 (play-services-home-types-17.0.0.aar)

  从该版本开始，开发者需要在项目的编译时和运行时库路径中同时包含这两个制品。

Android 示例应用

• 用户可以断开与应用的关联并撤消应用的权限。
• 更新了 SDK 制品，以包含 play-services-home-17.0.0 和 play-services-home-types-17.0.0。

已知问题

• 已放置在基座上的吸尘器设备未注册“已放置在基座上”状态。

2025-06-05

  Home API 公开 Beta 版 1.3.1  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.19.32
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：26.20250116.103.2201
• Android SDK：home.android.sdk_202505_EAP_1_3_1_RC06
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

特征

• 引入了 SyntheticSwitch 特征，该特征可简化对 Matter 开关设备生成的事件的处理，并允许开关触发自动化启动器。
• ExtendedDoorLock 特征存在重大变更：user_id 字段数据类型已从 String 更改为 Long。请参阅
  • ExtendedDoorLockTrait.LockStateChange.user_id
  • ExtendedDoorLockTrait.PrivacyModeActor.user_id

  使用此特征的应用需要重新编译。

Android 示例应用

添加了用于记录结构、设备、类型、特征和自动化操作状态的函数，以便更轻松地进行调试。

已知问题

在 Android 示例应用中，创建自动化操作按钮有时需要多次点按才能触发。

修复的已知问题

• 如果在 Google Home 应用 (GHA) 中未设置住宅位置，则在创建自动化操作时，Google Home 应用会因出现 FailedPreconditionException 而崩溃（如需了解如何设置住宅位置，请参阅更改 Google 住宅地址）。
• 在 Android 示例应用中，之前向用户显示了具有 connectivityState PARTIALLY_ONLINE 的设备处于离线状态。此状态现在表示为在线。

2025-05-12

  Home API 公开 Beta 版版本 1.3  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.16.33
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：26.20250116.103.2201
• Android SDK：home.android.sdk_202504_EAP_1_3_RC00
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Automation API
  • 新增了对 周期性预定事件启动方式的支持，开发者可以使用 cron 表达式创建基于时钟时间、太阳时间和日历条件的周期性自动化操作。
• Device API
  • 新增了重命名设备的功能。请参阅更改设备的名称。
• Structure API
  • 添加了重命名聊天室的功能。请参阅更改会议室名称。

已知问题

如果在 Google Home 应用 (GHA) 中未设置住宅位置，则在创建自动化操作时，Google Home 应用会因出现 FailedPreconditionException 而崩溃（如需了解如何设置住宅位置，请参阅更改 Google 家庭住址）。

• 解决方法：在尝试创建自动化操作之前，使用 Discovery API 检查家庭住址是否存在。

修复的已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。

2025-04-09

  Home API 公开 Beta 版版本 1.2.1  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.09.33
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：24.20241009.103.1900601¹
• Android SDK：home.android.sdk_202503_EAP_1_2_1_RC02
• Google Home 应用：适用于任何版本
• androidx.core 库：1.10.0
• Matter 版本： 1.4.0.0

^{1. 此 build 目前正在向正式版渠道推出，并将于 2025 年 4 月 22 日之前面向所有设备推出。}

新功能

• 提升了从 Home Graph 加载对象时的性能。
• Automation API
  • 新增了对 实体过滤器的支持，该过滤器可让自动化操作根据自动化操作中指定的条件动态选择设备。
• Device API
  • BasicInformationTrait 中现已提供云到云设备信息。

已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。

修复的已知问题

• 如果在初始化之前或初始化完成之前调用 Discovery API，系统会抛出 HomeException，其中包含 code 14: UNKNOWN 和消息“No route found.”。
• 在包含多个结构和多个用户的环境中，切换结构和用户可能会导致未返回任何设备。

2025-03-14

  Home API 公开 Beta 版 1.2.0  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务的最低版本：25.06.32
• Google Hub 固件最低版本：
  • Cast 版本：3.75.456944
  • Fuchsia 最低版本：24.20241009.103.1900601
• Android SDK：home.android.sdk_1_2_0_RC06
• Google Home 应用最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

新功能

• Automation API：
  • 支持在自动化条件中使用日期范围和部分日期。 请参阅使用包含 between 的日期。
  • 在之前的版本中，Discovery API 本应针对某些位图字段返回 BitmapConstraint，但却返回了 NumberSetConstraint。这些字段现在会按预期返回 BitmapConstraint。这仅限于 LevelControl 特征命令中的 optionsMask 和 optionsOverride 位图。

已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。
• 如果在初始化之前或初始化完成之前调用 Discovery API，系统会抛出 HomeException，其中包含 code 14: UNKNOWN 和消息“No route found.”。
  • 解决方法：仅在实际需要自动化候选对象时才调用 Discovery API。不预提取和缓存候选实体。在实体上调用 Discovery API 方法之前，检查该实体是否处于在线状态。
• 在包含多个结构和多个用户的环境中，切换结构和用户可能会导致未返回任何设备。

修复的已知问题

• Home API 应用在启动后首次调用 HomeManager.structures() 时，即使存在一个或多个结构，也会收到零个结构。这会给人一种错误的印象，即 Google 账号未关联任何住宅。
• 在加载、创建和修改自动化操作时，用户可能需要等待很长时间。
• 从“相机”应用启动设置流程的用户需要扫描两次二维码才能完成 Matter 调试。
• 在包含 200 部以上设备的结构中，Discovery API 可能只会返回无候选设备。

2025-01-29

  Home API 公开 Beta 版 1.1.0  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务的最低版本：25.02.32
• Google Hub 固件最低版本：
  • Cast 版本：3.75.456944
  • Fuchsia 最低版本：24.20241009.103.1900500
• Android SDK：home.android.sdk_202412_EAP_1_1_RC04
• Google Home 应用最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

新功能

• Streaming API：
  • 提供事件流，用于通知已添加、更改和移除的结构、房间和设备。
  • 请参阅订阅实体关系事件。
• 批处理 API（实验性）：
  • 允许开发者批量发送多个命令，这些命令会同时执行。
  • 请参阅一次发送多条命令。

已知问题

• 在加载、创建和修改自动化操作时，用户可能需要等待很长时间。
• 从“相机”应用启动设置流程的用户需要扫描两次二维码才能完成 Matter 调试。
• 在包含 200 部以上设备的结构中，Discovery API 可能只会返回无候选设备。

修复的已知问题

• 切换已登录的 Google 账号可能会失败并导致错误。
• Google TV 设备可能无法用于使用 MediaPlayback 特征的自动化操作。
• 在仅包含 Google 集线器的结构中：
  • Matter 设备在 Google Home 应用中可能显示为离线。
  • Google 助理无法控制 Matter 设备。
  • 智能显示屏无法控制 Matter 设备或显示任何 Matter 设备的状态。
• 对于某些设备，应用可能无法始终反映准确的状态，并且您的应用报告的状态可能与 Google 应用（例如 Google Home 应用）报告的状态不同。这通常是因为设备未向 Google 报告状态。
  • 解决方法：使用 Google 应用检查状态可解决不一致问题。

2025-01-14

更新了有关 Home API 初始化的指导信息。

我们已明确指出，Home 的实例应初始化为上下文单例。这样可确保在您的应用中提供更顺畅的用户体验，并避免因会话无效而导致错误。

2025-01-07

  Home API 公开 Beta 版发布  

在公开开发者 Beta 版期间，所有开发者都可以开始构建和测试自己的应用。

此版本包含 bug 修复，并提升了 Home API Android SDK 的 Beta 版质量，包括改进了对 Google Nest Audio 和 Google TV 设备的支持。

最低版本

• Google Play 服务最低版本：24.45.34
• Google Hub 固件最低版本：
  • Cast 版本：3.74.444798
  • Fuchsia 最低版本：22.20240805.103.161
• Android SDK：home.android.sdk_202411_EAP_1_0_1_RC00
• Google Home 应用 (GHA) 最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

已知问题

• 切换已登录的 Google 账号可能会失败并导致错误。
  • 解决方法：重新运行权限流程或重启应用。
• Google TV 设备可能无法用于使用 MediaPlayback 特征的自动化操作。
• 在仅包含 Google 集线器的结构中：
  • Matter 设备在 Google Home 应用 (GHA) 中可能显示为离线。
  • Google 助理无法控制 Matter 设备。
  • 智能显示屏无法控制 Matter 设备，也无法显示任何 Matter 设备的状态。
• 对于某些设备，应用可能无法始终反映准确的状态，并且您的应用报告的状态可能与 Google 应用（例如 Google Home 应用 [GHA]）报告的状态不同。这通常是因为设备未向 Google 报告状态。
  • 解决方法：使用 Google 应用检查状态可解决不一致问题。

修复的已知问题

• 如果在调试过程中将应用最小化，调试可能会失败。
  • 解决方法：使用 suppressHalfSheetNotification() API 在应用中使用 Commissioning API 时禁止显示半页通知。
• 服务器端问题可能会导致“Ok Google”启动器无法在自动化操作中正常运行。
• 使用运行 Fuchsia 且结构中没有任何 Matter 设备的 hub 时，如果 hub 处于空闲状态超过 3 小时，调试第一个 Matter 设备会导致该 Matter 设备处于离线状态。
• 在对中枢执行恢复出厂设置后，即使设备报告为在线，向新调试的设备发送的命令也可能会失败。