Home APIs Android SDK 版本資訊

2026-02-09

  Home API 公開 Beta 版 1.7  

這個版本修正了錯誤，並提升了 Android 版 Home API SDK 的 Beta 版品質。

最低版本

• Google Play 服務：26.02.34
• Google 中樞裝置的最低韌體版本：
  • 投放：
    • Nest Wifi Pro：3.76.508025
    • 所有其他支援 Cast 的中樞裝置：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 Indoor/Outdoor (電池版或有線版) 和 Nest Doorbell (電池版，第 2 代) 的「電池設定」中不會顯示「剩餘電量」選項。
• 系統會忽略鈴聲時間長度設定。
• 即使裝置實際處於離線狀態，Philips BLE 燈仍會錯誤顯示為「連線」。
  • 解決方法：請勿只依賴智慧住宅裝置類型 (SHDT) 的線上狀態。 請改用 Target Device State Service (TDSS) 對應檔，適用於具有 LOCAL_SYNC 來源的裝置。

2025-12-22

  Home API 公開 Beta 版 1.6  

這個版本修正了錯誤，並提升了 Android 版 Home API SDK 的 Beta 版品質。

最低版本

• Google Play 服務：25.47.30
• Google 中樞裝置的最低韌體版本：
  • 投放：
    • Nest Wifi Pro：3.75.479819
    • 所有其他支援 Cast 的中樞裝置：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，簡化使用者體驗流程，並免除檢查執行應用程式的使用者。

  • 無中樞模式

    使用者現在可以加入及控制特定 Matter 裝置，不必使用獨立中樞裝置。

• Structure API
  • 新的 Hub Activation API，可讓應用程式探索及啟用中樞裝置。

• Android 範例應用程式
  • 攝影機和門鈴設定
    • 開啟/關閉麥克風。
    • 開啟/關閉錄音功能。
  • 預先定義的自動化動作
  • 新增支援風扇和音箱裝置類型。
• 應用程式啟動的 Google 登入。

已知問題

• 長時間使用後，裝置控制項會停止運作。
  • 解決方法：重新啟動中樞裝置。
• 可能無法調試 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 發布  

這個版本修正了錯誤，並提升了 Android 版 Home API 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
  • 中樞裝置啟用 API 可讓您以程式輔助方式探索及啟用 Google Home 中樞裝置。請參閱「Android 上的 Hub 啟用 API」。
    
• Android 範例應用程式
  • 支援的門鈴裝置類型：
    • OnOff
    • 直播
    • 對講
  • Hub Activation API：啟用 Hub

已修正的已知問題

• 範例應用程式無法在「Device」(裝置) 檢視畫面中正確顯示裝置狀態。

2025-09-26

  Home API 公開 Beta 版 1.5.0 發布  

這個版本支援攝影機裝置、修正錯誤，並提升 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 切換至行動網路時，裝置控制延遲可能會增加。
• 由 Cloud-to-Cloud 支援的風扇裝置類型可能無法在範例應用程式中控制。

已修正的已知問題

• 強制移除目前啟用的中樞裝置後，有五分鐘的時間無法控制部分裝置。五分鐘後，你就能再次控制裝置。
• 使用者從預設顏色或色溫挑選器選取顏色後，擴展色光無法更新顏色。

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 應用程式中設定住家位置，建立自動化動作時，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 library：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 的結構中：
  • Matter 裝置可能會在 Google Home 應用程式 (GHA) 中顯示為離線。
  • Google 助理無法控制 Matter 裝置。
  • 智慧螢幕無法控制 Matter 裝置，也無法顯示任何 Matter 裝置的狀態。
• 對於部分裝置，應用程式可能無法一律反映準確狀態，且應用程式回報的狀態可能與 Google 應用程式 (例如 Google Home 應用程式 (GHA)) 回報的狀態不同。這通常是因為裝置未向 Google 回報狀態。
  • 解決方法：使用 Google 應用程式檢查狀態，即可解決不符問題。

已修正的已知問題

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