Ghi chú phát hành SDK Android cho API Home

2025-09-08

Ứng dụng mẫu cho Android phiên bản 1.4.1 đã được phát hành.

Tính năng mới

• Tạo, đổi tên, cập nhật và xoá phòng.
• Thiết lập cho một mạng lưới Matter của bên thứ ba.

Khắc phục các vấn đề đã biết

• Đường liên kết đến trang thu hồi quyền hiện đã hoạt động.

2025-08-29

  Home API Phiên bản thử nghiệm công khai 1.4.1  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.33.32
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Cast: 3.76.495998
  • Fuchsia: 27.20250422.103.3600
• Android SDK: home.android.sdk_1_4_1
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: hoạt động với mọi phiên bản
• Phiên bản Matter: 1.4.0.0

Tính năng mới

• Device API
  • Một DecommissionIneligibleReason mới được xác định để cố gắng ngừng hoạt động một thiết bị có nhiều nguồn. Hãy xem phần Thiết bị có nhiều nguồn.

Vấn đề đã biết

• Khi trung tâm hiện đang hoạt động bị xoá bắt buộc, sẽ có một khoảng thời gian 5 phút mà bạn không thể điều khiển một số thiết bị. Sau 5 phút, bạn có thể điều khiển các thiết bị trở lại.

Khắc phục các vấn đề đã biết

• Ứng dụng mẫu Android gặp sự cố khi người dùng cố gắng đặt chế độ cho máy điều nhiệt mà chế độ đó không hỗ trợ.

2025-07-31

  Home API Phiên bản thử nghiệm công khai 1.4.0  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.28.34
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Cast: 3.76.486931
  • Fuchsia: 27.20250422.103.3600
• Android SDK: home.android.sdk_1_4_0
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: hoạt động với mọi phiên bản
• Phiên bản Matter: 1.4.0.0

Tính năng mới

• Automation API
  • Bạn có thể giới hạn số lần thực hiện tự động hoá. Xem phần Giới hạn số lần thực thi.

• Device API
  • Khả năng xoá thiết bị Matter theo phương thức lập trình. Xem phần Xoá thiết bị.
  • Các thành phần HomeDevice không dùng nữa sau đây đã bị xoá:
    1. HomeDevice.trait(). Xem phần Truy cập vào các thiết bị và siêu dữ liệu thiết bị cho Android.
    2. HomeDevice.isInRoom. Sử dụng HomeDevice.roomId thay thế.
    3. HomeDevice.isInStructure. Sử dụng HomeDevice.structureId thay thế.
• Structure API
  • Home.hasPermissions() hiện kết hợp cả trạng thái uỷ quyền OAuth cho người dùng (quyền truy cập vào cấu trúc) cũng như các quyền được cấp cho ứng dụng.
• Ứng dụng mẫu Android
  • Thay thế các lệnh gọi API không dùng nữa.
  • Đổi tên thiết bị.
  • Xoá các thiết bị chỉ hỗ trợ Matter.

Vấn đề đã biết

• Sau khi đăng xuất khỏi điện thoại rồi đăng nhập lại, ứng dụng Home APIs không thể điều khiển các thiết bị.
  • Giải pháp: Đóng hoặc chuyển ứng dụng xuống nền, sau đó đợi ít nhất 10 giây trước khi thử lại.

Khắc phục các vấn đề đã biết

• Các thiết bị hút bụi đã được gắn vào đế sạc sẽ không đăng ký trạng thái Đã gắn vào đế sạc.

2025-07-08

Với phiên bản phần mềm Cast 3.76.479819, Nest Wifi Pro hiện có thể hoạt động như một trung tâm Home API.

2025-06-26

  Bản phát hành công khai thử nghiệm 1.3.2 của Home API  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.23.31
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Truyền:
    • Google Home, Google Home Mini và Google Nest Mini: 3.75.468362
    • Google Nest Audio: 3.75.476451
  • Fuchsia: 26.20250116.103.2900
• SDK Android: home.android.sdk_1_3_2
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: hoạt động với mọi phiên bản
• Phiên bản Matter: 1.4.0.0

Tính năng mới

• Cấu phần phần mềm SDK đã được chia thành 2 cấu phần phần mềm riêng biệt:
  • Khung SDK Home APIs (play-services-home-17.0.0.aar)
  • Đặc điểm của SDK và các loại thiết bị (play-services-home-types-17.0.0.aar)

  Kể từ bản phát hành này, nhà phát triển cần đưa cả hai cấu phần phần mềm vào đường dẫn thư viện thời gian biên dịch và thời gian chạy của dự án.

Ứng dụng mẫu Android

• Người dùng có thể ngắt kết nối và thu hồi quyền của ứng dụng.
• Cập nhật cấu phần phần mềm SDK để thêm play-services-home-17.0.0 và play-services-home-types-17.0.0.

Vấn đề đã biết

• Các thiết bị hút bụi đã được gắn vào đế sạc sẽ không đăng ký trạng thái Đã gắn vào đế sạc.

2025-06-05

  Bản phát hành công khai thử nghiệm 1.3.1 của Home API  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.19.32
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Truyền: 3.75.468222
  • Fuchsia: 26.20250116.103.2201
• SDK Android: home.android.sdk_202505_EAP_1_3_1_RC06
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: hoạt động với mọi phiên bản
• Phiên bản Matter: 1.4.0.0

Tính năng mới

Đặc điểm

• Giới thiệu đặc điểm SyntheticSwitch giúp đơn giản hoá việc xử lý các sự kiện do thiết bị Matter Switch tạo ra và cho phép các công tắc kích hoạt chế độ bắt đầu tự động hoá.
• Đặc điểm ExtendedDoorLock có một thay đổi mang tính đột phá: kiểu dữ liệu của trường user_id đã thay đổi từ String thành Long. Xem
  • ExtendedDoorLockTrait.LockStateChange.user_id
  • ExtendedDoorLockTrait.PrivacyModeActor.user_id

  Bạn cần biên dịch lại những ứng dụng sử dụng đặc điểm này.

Ứng dụng mẫu Android

Thêm các hàm để ghi nhật ký trạng thái của cấu trúc, thiết bị, loại, đặc điểm và quy trình tự động hoá để gỡ lỗi dễ dàng hơn.

Vấn đề đã biết

Trong Ứng dụng mẫu Android, đôi khi bạn phải nhấn nhiều lần vào nút Tạo quy trình tự động hoá để kích hoạt.

Khắc phục các vấn đề đã biết

• Ứng dụng Google Home gặp sự cố và xuất hiện biểu tượng FailedPreconditionException khi tạo quy trình tự động hoá nếu bạn chưa đặt vị trí nhà trong ứng dụng Google Home (GHA) (Xem phần Thay đổi địa chỉ nhà trên Google để biết cách đặt vị trí của nhà).
• Trong Ứng dụng mẫu Android, một thiết bị có connectivityState PARTIALLY_ONLINE trước đây được hiển thị cho người dùng ở trạng thái ngoại tuyến. Giờ đây, trạng thái này được biểu thị là online.

2025-05-12

  Home APIs Phiên bản thử nghiệm công khai 1.3  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.16.33
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Truyền: 3.75.468222
  • Fuchsia: 26.20250116.103.2201
• SDK Android: home.android.sdk_202504_EAP_1_3_RC00
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: hoạt động với mọi phiên bản
• Phiên bản Matter: 1.4.0.0

Tính năng mới

• Automation API
  • Đã thêm tính năng hỗ trợ các trình khởi chạy sự kiện theo lịch biểu định kỳ. Tính năng này cho phép nhà phát triển tạo các quy trình tự động hoá chạy định kỳ dựa trên thời gian thực, thời gian mặt trời và các điều kiện dựa trên lịch, bằng cách sử dụng các biểu thức cron.
• Device API
  • Thêm chức năng đổi tên thiết bị. Xem phần Thay đổi tên thiết bị.
• Structure API
  • Thêm chức năng đổi tên phòng. Xem phần Đổi tên phòng.

Vấn đề đã biết

Ứng dụng Google Home gặp sự cố với biểu tượng FailedPreconditionException khi tạo quy trình tự động hoá nếu bạn chưa đặt vị trí nhà trong ứng dụng Google Home (GHA) (Xem phần Thay đổi địa chỉ nhà trên Google để biết cách thực hiện).

• Giải pháp: Kiểm tra để đảm bảo địa chỉ nhà xuất hiện bằng Discovery API trước khi cố gắng tạo quy trình tự động hoá.

Khắc phục các vấn đề đã biết

• Có thể xảy ra tình trạng tăng độ trễ khi điều khiển thiết bị khi chuyển từ Wi-Fi sang mạng di động.
• Sau khi bạn đặt lại trung tâm về trạng thái ban đầu, các thiết bị có thể xuất hiện ở trạng thái ngoại tuyến.

2025-04-09

  Home API Phiên bản beta công khai 1.2.1  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Dịch vụ Google Play: 25.09.33
• Phiên bản tối thiểu của chương trình cơ sở cho trung tâm Google:
  • Truyền: 3.75.468222
  • Fuchsia: 24.20241009.103.1900601¹
• SDK Android: home.android.sdk_202503_EAP_1_2_1_RC02
• Ứng dụng Google Home: hoạt động với mọi phiên bản
• Thư viện androidx.core: 1.10.0
• Phiên bản Matter: 1.4.0.0

^{1. Bản dựng này hiện đang được triển khai cho phiên bản chính thức và sẽ có trên tất cả các thiết bị muộn nhất vào ngày 22 tháng 4 năm 2025.}

Tính năng mới

• Cải thiện hiệu suất khi tải các đối tượng từ Home Graph.
• Automation API
  • Thêm chế độ hỗ trợ cho bộ lọc thực thể, cho phép các quy trình tự động hoá chọn thiết bị một cách linh hoạt dựa trên tiêu chí được chỉ định trong quy trình tự động hoá.
• Device API
  • Thông tin thiết bị trên đám mây hiện có trong BasicInformationTrait.

Vấn đề đã biết

• Có thể xảy ra tình trạng tăng độ trễ khi điều khiển thiết bị khi chuyển từ Wi-Fi sang mạng di động.
• Sau khi bạn đặt lại trung tâm về trạng thái ban đầu, các thiết bị có thể xuất hiện ở trạng thái ngoại tuyến.

Khắc phục các vấn đề đã biết

• Nếu Discovery API được gọi trước khi khởi chạy hoặc trước khi quá trình khởi chạy hoàn tất, thì HomeException với code 14: UNKNOWN và thông báo "No route found" (Không tìm thấy tuyến đường) sẽ được gửi.
• Trong môi trường có nhiều cấu trúc và nhiều người dùng, việc chuyển đổi giữa các cấu trúc và người dùng có thể dẫn đến việc không có thiết bị nào được trả về.

2025-03-14

  Bản phát hành thử nghiệm công khai 1.2.0 của Home API  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Phiên bản tối thiểu của Dịch vụ Google Play: 25.06.32
• Phiên bản chương trình cơ sở tối thiểu của trung tâm Google:
  • Phiên bản Cast: 3.75.456944
  • Phiên bản Fuchsia tối thiểu: 24.20241009.103.1900601
• Android SDK: home.android.sdk_1_2_0_RC06
• Phiên bản tối thiểu của ứng dụng Google Home: hoạt động với mọi phiên bản
• androidx.core phiên bản tối thiểu của thư viện: 1.10.0
• Phiên bản Matter: 1.3.0.0
  • Lưu ý: Các loại và cụm thiết bị Matter tạm thời không được hỗ trợ.

Tính năng mới

• Automation API:
  • Hỗ trợ phạm vi ngày và ngày một phần trong các điều kiện tự động hoá. Xem phần Sử dụng ngày với khoảng thời gian.
  • Trong các bản phát hành trước, Discovery API đã trả về NumberSetConstraint cho một số trường bitmap khi đáng lẽ phải trả về BitmapConstraint. Những trường này hiện trả về một BitmapConstraint như dự kiến. Điều này chỉ giới hạn ở các bitmap optionsMask và optionsOverride trong các lệnh đặc điểm LevelControl.

Vấn đề đã biết

• Có thể xảy ra tình trạng tăng độ trễ khi điều khiển thiết bị khi chuyển từ Wi-Fi sang mạng di động.
• Sau khi bạn đặt lại trung tâm về trạng thái ban đầu, các thiết bị có thể xuất hiện ở trạng thái ngoại tuyến.
• Nếu Discovery API được gọi trước khi khởi chạy hoặc trước khi quá trình khởi chạy hoàn tất, thì HomeException với code 14: UNKNOWN và thông báo "No route found" (Không tìm thấy tuyến đường) sẽ được gửi.
  • Giải pháp: Chỉ gọi Discovery API khi bạn thực sự cần các đề xuất tự động hoá. Không tìm nạp trước và lưu vào bộ nhớ đệm các thực thể đề xuất. Kiểm tra xem một thực thể có đang trực tuyến hay không trước khi gọi các phương thức Discovery API trên thực thể đó.
• Trong môi trường có nhiều cấu trúc và nhiều người dùng, việc chuyển đổi giữa các cấu trúc và người dùng có thể dẫn đến việc không có thiết bị nào được trả về.

Khắc phục các vấn đề đã biết

• Lần đầu tiên một ứng dụng Home APIs gọi HomeManager.structures() sau khi được chạy, ứng dụng đó sẽ nhận được 0 cấu trúc, ngay cả khi có một hoặc nhiều cấu trúc. Điều này tạo ấn tượng sai lầm rằng không có cấu trúc nào được liên kết với Tài khoản Google.
• Khi tải, tạo và chỉnh sửa quy trình tự động hoá, người dùng có thể gặp phải thời gian chờ lâu.
• Người dùng bắt đầu quy trình thiết lập từ ứng dụng Camera phải quét mã QR hai lần để hoàn tất quy trình thiết lập Matter.
• Trong một cấu trúc chứa hơn 200 thiết bị, Discovery API có thể chỉ trả về không có đề xuất nào.

2025-01-29

  Bản phát hành thử nghiệm công khai 1.1.0 của Home API  

Bản phát hành này sửa các lỗi và nâng cao chất lượng của phiên bản beta cho Home API Android SDK.

Phiên bản tối thiểu

• Phiên bản tối thiểu của Dịch vụ Google Play: 25.02.32
• Phiên bản chương trình cơ sở tối thiểu của trung tâm Google:
  • Phiên bản Cast: 3.75.456944
  • Phiên bản Fuchsia tối thiểu: 24.20241009.103.1900500
• SDK Android: home.android.sdk_202412_EAP_1_1_RC04
• Phiên bản tối thiểu của ứng dụng Google Home: hoạt động với mọi phiên bản
• androidx.core phiên bản tối thiểu của thư viện: 1.10.0
• Phiên bản Matter: 1.3.0.0
  • Lưu ý: Các loại và cụm thiết bị Matter tạm thời không được hỗ trợ.

Tính năng mới

• Streaming API:
  • Cung cấp các luồng sự kiện thông báo về những cấu trúc, phòng và thiết bị đã được thêm, thay đổi và xoá.
  • Xem phần Đăng ký nhận sự kiện về mối quan hệ giữa các thực thể.
• API theo lô (Thử nghiệm):
  • Cho phép nhà phát triển gửi nhiều lệnh theo lô được thực thi đồng thời.
  • Xem phần Gửi nhiều lệnh cùng một lúc.

Vấn đề đã biết

• Khi tải, tạo và chỉnh sửa quy trình tự động hoá, người dùng có thể gặp phải thời gian chờ lâu.
• Người dùng bắt đầu quy trình thiết lập từ ứng dụng Camera phải quét mã QR hai lần để hoàn tất quy trình thiết lập Matter.
• Trong một cấu trúc chứa hơn 200 thiết bị, Discovery API có thể chỉ trả về không có đề xuất nào.

Khắc phục các vấn đề đã biết

• Việc chuyển đổi Tài khoản Google đã đăng nhập có thể không thành công và dẫn đến lỗi.
• Các thiết bị Google TV có thể không hoạt động đối với những quy trình tự động hoá sử dụng đặc điểm MediaPlayback.
• Trong một cấu trúc chỉ chứa một trung tâm Google:
  • Các thiết bị Matter có thể xuất hiện ở trạng thái không kết nối mạng trong ứng dụng Google Home.
  • Trợ lý Google không thể điều khiển các thiết bị Matter.
  • Màn hình thông minh không thể điều khiển các thiết bị Matter hoặc hiển thị trạng thái của bất kỳ thiết bị Matter nào.
• Đối với một số thiết bị, ứng dụng có thể không phải lúc nào cũng phản ánh trạng thái chính xác và ứng dụng của bạn có thể báo cáo một trạng thái khác với trạng thái do một ứng dụng của Google báo cáo, chẳng hạn như ứng dụng Google Home. Điều này thường là do các thiết bị không báo cáo trạng thái cho Google.
  • Giải pháp: Kiểm tra trạng thái bằng một ứng dụng của Google sẽ giải quyết vấn đề không khớp.

2025-01-14

Hướng dẫn mới về việc khởi chạy API Home.

Chúng tôi đã làm rõ hơn rằng một thực thể của Home phải được khởi tạo dưới dạng một singleton theo bối cảnh. Điều này giúp đảm bảo trải nghiệm mượt mà hơn cho người dùng trong ứng dụng của bạn và tránh các lỗi liên quan đến phiên không hợp lệ.

2025-01-07

  Phát hành phiên bản thử nghiệm công khai của Home API  

Trong giai đoạn thử nghiệm beta công khai dành cho nhà phát triển, tất cả nhà phát triển đều có thể bắt đầu tạo và kiểm thử ứng dụng của mình.

Bản phát hành này chứa các bản sửa lỗi và nâng cao chất lượng beta cho SDK Android Home API, bao gồm cả khả năng hỗ trợ tốt hơn cho các thiết bị Google Nest Audio và Google TV.

Phiên bản tối thiểu

• Phiên bản tối thiểu của Dịch vụ Google Play: 24.45.34
• Phiên bản chương trình cơ sở tối thiểu của trung tâm Google:
  • Phiên bản Cast: 3.74.444798
  • Phiên bản Fuchsia tối thiểu: 22.20240805.103.161
• SDK Android: home.android.sdk_202411_EAP_1_0_1_RC00
• Phiên bản tối thiểu của ứng dụng Google Home (GHA): hoạt động với mọi phiên bản
• androidx.core phiên bản tối thiểu của thư viện: 1.10.0
• Phiên bản Matter: 1.3.0.0
  • Lưu ý: Các loại và cụm thiết bị Matter tạm thời không được hỗ trợ.

Vấn đề đã biết

• Việc chuyển đổi Tài khoản Google đã đăng nhập có thể không thành công và dẫn đến lỗi.
  • Giải pháp: Chạy lại quy trình cấp quyền hoặc khởi động lại ứng dụng.
• Các thiết bị Google TV có thể không hoạt động đối với những quy trình tự động hoá sử dụng đặc điểm MediaPlayback.
• Trong một cấu trúc chỉ chứa một trung tâm Google:
  • Các thiết bị Matter có thể xuất hiện ở trạng thái ngoại tuyến trong ứng dụng Google Home (GHA).
  • Trợ lý Google không thể điều khiển các thiết bị Matter.
  • Màn hình thông minh không thể điều khiển các thiết bị Matter hoặc hiển thị trạng thái của bất kỳ thiết bị Matter nào.
• Đối với một số thiết bị, ứng dụng có thể không phải lúc nào cũng phản ánh trạng thái chính xác và ứng dụng của bạn có thể báo cáo một trạng thái khác với trạng thái do một ứng dụng của Google báo cáo, chẳng hạn như ứng dụng Google Home (GHA). Điều này thường là do các thiết bị không báo cáo trạng thái cho Google.
  • Giải pháp: Kiểm tra trạng thái bằng một ứng dụng của Google sẽ giải quyết vấn đề không khớp.

Khắc phục các vấn đề đã biết

• Quá trình thiết lập có thể không thành công nếu ứng dụng bị thu nhỏ trong quá trình này.
  • Giải pháp: Sử dụng suppressHalfSheetNotification() API để chặn thông báo nửa màn hình khi bạn dùng Commissioning API trong ứng dụng.
• Vấn đề về phía máy chủ có thể khiến các câu lệnh bắt đầu Ok Google không hoạt động trong các quy trình tự động hoá.
• Khi sử dụng một trung tâm chạy Fuchsia mà không có thiết bị Matter nào trong cấu trúc, nếu trung tâm ở trạng thái không hoạt động trong hơn 3 giờ, việc thiết lập thiết bị Matter đầu tiên sẽ khiến thiết bị Matter ở trạng thái ngoại tuyến.
• Sau khi bạn đặt lại dữ liệu về trạng thái ban đầu cho một trung tâm, các lệnh đối với những thiết bị mới được thiết lập có thể không hoạt động mặc dù thiết bị được báo cáo là đang trực tuyến.