Home APIs Android SDK 版本資訊

2025-09-08

Android 專用範例應用程式 1.4.1 版已發布。

新功能

• 建立、重新命名、更新及刪除聊天室。
• 調試至第三方 Matter Fabric。

修正的已知問題

• 權限撤銷頁面連結現在可正常運作。

2025-08-29

  Home API 公開 Beta 版 1.4.1  

這個版本修正了錯誤，並提升 Android 版 Home API 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。請參閱 多來源裝置。

已知問題

• 強制移除目前啟用的中樞裝置後，有五分鐘的時間無法控制部分裝置。五分鐘後，你就能再次控制裝置。

已修正的已知問題

• 使用者嘗試將恆溫器設為不支援的模式時，Android 範例應用程式會當機。

2025-07-31

  Home API 公開 Beta 版 1.4.0  

這個版本修正了錯誤，並提升 Android 版 Home API 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  

這個版本修正了錯誤，並提升 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  

這個版本修正了錯誤，並提升 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 Switch 裝置產生的事件，並允許切換開關觸發自動化啟動器。
• 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  

這個版本修正了錯誤，並提升 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 應用程式中設定住家位置，建立自動化動作時，Google Home 應用程式會顯示 FailedPreconditionException 並當機 (如要瞭解如何設定，請參閱「變更 Google 住家地址」一文)。

• 解決方法：嘗試建立自動化動作前，請先使用 Discovery API 確認住家地址是否存在。

修正的已知問題

• 從 Wi-Fi 切換至行動網路時，裝置控制延遲可能會增加。
• 中樞裝置恢復原廠設定後，裝置可能會顯示為離線。

2025-04-09

  Home API 公開 Beta 版 1.2.1  

這個版本修正了錯誤，並提升 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. 這個版本目前正在正式版中推出，並將於 2025 年 4 月 22 日前在所有裝置上提供。}

新功能

• 提升從住家圖表載入物件時的效能。
• 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  

這個版本修正了錯誤，並提升 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：
  • 自動化條件支援日期範圍和部分日期。 請參閱「使用日期範圍」。
  • 在先前的版本中，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 帳戶沒有相關聯的結構。
• 載入、建立及編輯自動化動作時，使用者可能需要等待較長時間。
• 如果使用者從「相機」應用程式啟動設定流程，必須掃描 QR code 兩次，才能完成 Matter 委派程序。
• 如果結構包含超過 200 部裝置，Discovery API 可能只會傳回候選裝置。

2025-01-29

  Home API 公開 Beta 版 1.1.0  

這個版本修正了錯誤，並提升 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 裝置類型和叢集。

新功能

• 串流 API：
  • 提供事件串流，通知已新增、變更及移除的結構、房間和裝置。
  • 請參閱「訂閱實體關係事件」。
• 批次處理 API (實驗性)：
  • 開發人員可以批次傳送多個指令，並同時執行。
  • 請參閱「一次傳送多個指令」。

已知問題

• 載入、建立及編輯自動化動作時，使用者可能需要等待較長時間。
• 如果使用者從「相機」應用程式啟動設定流程，必須掃描 QR code 兩次，才能完成 Matter 委派程序。
• 如果結構包含超過 200 部裝置，Discovery API 可能只會傳回候選裝置。

已修正的已知問題

• 切換登入的 Google 帳戶可能會失敗並導致錯誤。
• 如果自動化動作使用 MediaPlayback 特徵，Google TV 裝置可能無法執行。
• 在只包含 Google Hub 的住家中：
  • 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 版期間，所有開發人員都可以開始建構及測試應用程式。

這個版本修正了錯誤，並提升了 Android 版 Home API 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 帳戶可能會失敗並導致錯誤。
  • 解決方法：重新執行權限流程或重新啟動應用程式。
• 如果自動化動作使用 MediaPlayback 特徵，Google TV 裝置可能無法執行。
• 在只包含 Google Hub 的結構中：
  • Google Home 應用程式 (GHA) 可能會顯示 Matter 裝置離線。
  • Google 助理無法控制 Matter 裝置。
  • 智慧螢幕無法控制 Matter 裝置，也無法顯示任何 Matter 裝置的狀態。
• 在某些裝置上，應用程式可能無法一律反映準確狀態，且應用程式回報的狀態可能與 Google 應用程式 (例如 Google Home 應用程式 (GHA)) 回報的狀態不同。這通常是因為裝置未向 Google 回報狀態。
  • 解決方法：使用 Google 應用程式檢查狀態，即可解決不符問題。

已修正的已知問題

• 如果在設定程序期間將應用程式縮到最小，設定可能會失敗。
  • 解決方法：在應用程式中使用 Commissioning API 時，請使用 suppressHalfSheetNotification() API 停用半頁式通知。
• 伺服器端問題可能會導致「Ok Google」啟動器無法在自動化動作中使用。
• 如果使用執行 Fuchsia 的中樞，且結構中沒有任何 Matter 裝置，中樞閒置超過 3 小時後，委派第一個 Matter 裝置會導致該裝置離線。
• 中樞裝置恢復原廠設定後，即使裝置顯示為連線狀態，對新委派裝置發出的指令仍可能會失敗。