Home API Android SDK 출시 노트

2025-09-08

Android용 샘플 앱 버전 1.4.1이 출시되었습니다.

새로운 기능

• 회의실 만들기, 이름 바꾸기, 업데이트, 삭제
• 서드 파티 Matter 패브릭에 커미셔닝

알려진 문제 수정

• 이제 권한 취소 페이지 링크가 작동합니다.

2025-08-29

  Home API 공개 베타 출시 1.4.1  

이번 출시에는 버그가 수정되고 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스: 25.33.32
• Google 허브 펌웨어 최소 버전:
  • 전송: 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

새로운 기능

• 기기 API
  • 멀티 소스 기기를 사용 중단하려고 시도하기 위해 새로운 DecommissionIneligibleReason이 정의됩니다. 다중 소스 기기를 참고하세요.

알려진 문제

• 현재 활성 상태인 허브가 강제 삭제되면 일부 기기를 제어할 수 없는 5분간의 기간이 있습니다. 5분이 지나면 기기를 제어할 수 있습니다.

알려진 문제 해결

• 사용자가 지원되지 않는 모드로 온도 조절기를 설정하려고 하면 Android 샘플 앱이 비정상 종료됩니다.

2025-07-31

  Home API 공개 베타 출시 1.4.0  

이번 출시에는 버그가 수정되고 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스: 25.28.34
• Google 허브 펌웨어 최소 버전:
  • 전송: 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
  • 자동화는 제한된 횟수만큼 실행되도록 제한할 수 있습니다. 실행 횟수 제한을 참고하세요.

• 기기 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

이제 Nest WiFi Pro가 Cast 펌웨어 버전 3.76.479819를 통해 Home API 허브로 작동할 수 있습니다.

2025-06-26

  Home APIs 공개 베타 출시 1.3.2  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• 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 샘플 앱

• 사용자는 앱에서 연결을 해제하고 권한을 취소할 수 있습니다.
• play-services-home-17.0.0 및 play-services-home-types-17.0.0을 포함하도록 SDK 아티팩트를 업데이트했습니다.

알려진 문제

• 도킹된 진공청소기 기기는 도킹 상태로 등록되지 않습니다.

2025-06-05

  Home API 공개 베타 출시 1.3.1  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스: 25.19.32
• Google 허브 펌웨어 최소 버전:
  • 전송: 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

새로운 기능

특성

• Matter 스위치 기기에서 생성된 이벤트 처리를 간소화하고 스위치가 자동화 시작을 트리거할 수 있도록 하는 SyntheticSwitch 특성을 도입합니다.
• 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가 있는 기기가 이전에 사용자에게 오프라인으로 표시되었습니다. 이 상태는 이제 online으로 표시됩니다.

2025-05-12

  홈 API 공개 베타 출시 1.3  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스: 25.16.33
• Google 허브 펌웨어 최소 버전:
  • 전송: 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 표현식을 사용하여 시계 시간, 태양 시간, 캘린더 기반 조건에 따라 주기적으로 실행되는 자동화를 개발자가 만들 수 있는 반복 예약 일정 시작 조건 지원이 추가되었습니다.
• 기기 API
  • 기기 이름을 바꿀 수 있는 기능이 추가되었습니다. 기기 이름 변경하기를 참고하세요.
• Structure API
  • 채팅방 이름을 변경하는 기능이 추가되었습니다. 회의실 이름 변경하기를 참고하세요.

알려진 문제

Google Home 앱에서 홈 위치를 설정하지 않으면 자동화를 생성할 때 Google Home 앱이 FailedPreconditionException로 비정상 종료됩니다(방법은 Google 홈 주소 변경 참고).

• 해결 방법: 자동화를 만들려고 시도하기 전에 Discovery API를 사용하여 집 주소가 있는지 확인합니다.

알려진 문제 수정

• Wi-Fi에서 모바일 네트워크로 전환할 때 기기 제어 지연 시간이 증가할 수 있습니다.
• 허브를 초기화하면 기기가 오프라인으로 표시될 수 있습니다.

2025-04-09

  Home API 공개 베타 출시 1.2.1  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스: 25.09.33
• Google 허브 펌웨어 최소 버전:
  • 전송: 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
  • 자동화에서 지정된 기준에 따라 자동화가 기기를 동적으로 선택할 수 있는 엔티티 필터 지원이 추가되었습니다.
• 기기 API
  • 이제 BasicInformationTrait에서 클라우드 간 기기 정보를 확인할 수 있습니다.

알려진 문제

• Wi-Fi에서 모바일 네트워크로 전환할 때 기기 제어 지연 시간이 증가할 수 있습니다.
• 허브를 초기화하면 기기가 오프라인으로 표시될 수 있습니다.

알려진 문제 해결

• 초기화 전에 또는 초기화가 완료되기 전에 Discovery API를 호출하면 code 14: UNKNOWN와 '경로를 찾을 수 없습니다'라는 메시지가 포함된 HomeException이 발생합니다.
• 구조와 사용자가 여러 개인 환경에서는 구조와 사용자 간에 전환하면 기기가 반환되지 않을 수 있습니다.

2025-03-14

  Home API 공개 베타 버전 1.2.0  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스 최소 버전: 25.06.32
• Google 허브 펌웨어 최소 버전:
  • 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를 호출하면 code 14: UNKNOWN와 '경로를 찾을 수 없습니다'라는 메시지가 포함된 HomeException이 발생합니다.
  • 해결 방법: 실제로 자동화 후보가 필요한 경우에만 Discovery API를 호출하세요. 후보 항목을 미리 가져오고 캐시하지 않습니다. 엔티티에서 Discovery API 메서드를 호출하기 전에 엔티티가 온라인 상태인지 확인합니다.
• 구조와 사용자가 여러 개인 환경에서는 구조와 사용자 간에 전환하면 기기가 반환되지 않을 수 있습니다.

알려진 문제 해결

• Home API 앱이 실행된 후 처음으로 HomeManager.structures()를 호출하면 하나 이상의 구조가 있어도 구조를 0개 수신합니다. 이로 인해 Google 계정과 연결된 구조가 없다는 잘못된 인상을 줄 수 있습니다.
• 자동화 로드, 생성, 수정 시 사용자가 오래 기다려야 할 수 있습니다.
• 카메라 앱에서 설정 흐름을 시작하는 사용자는 Matter 커미셔닝을 완료하기 위해 QR 코드를 두 번 스캔해야 합니다.
• 기기가 200개를 초과하는 구조에서는 검색 API가 후보를 반환하지 않을 수도 있습니다.

2025-01-29

  Home API 공개 베타 출시 1.1.0  

이번 출시에는 버그 수정이 포함되어 있으며 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스 최소 버전: 25.02.32
• Google 허브 펌웨어 최소 버전:
  • 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 (실험용):
  • 개발자가 동시에 실행되는 일괄 명령어를 여러 개 보낼 수 있습니다.
  • 한 번에 여러 명령어 보내기를 참고하세요.

알려진 문제

• 자동화 로드, 생성, 수정 시 사용자가 오래 기다려야 할 수 있습니다.
• 카메라 앱에서 설정 흐름을 시작하는 사용자는 Matter 커미셔닝을 완료하기 위해 QR 코드를 두 번 스캔해야 합니다.
• 기기가 200개를 초과하는 구조에서는 검색 API가 후보를 반환하지 않을 수도 있습니다.

알려진 문제 해결

• 로그인된 Google 계정을 전환하면 실패하고 오류가 발생할 수 있습니다.
• Google TV 기기는 MediaPlayback 특성을 사용하는 자동화에서 작동하지 않을 수 있습니다.
• Google 허브만 포함하는 구조의 경우:
  • Matter 기기가 Google Home 앱에서 오프라인으로 표시될 수 있습니다.
  • Google 어시스턴트가 Matter 기기를 제어할 수 없습니다.
  • 스마트 디스플레이는 Matter 기기를 제어하거나 Matter 기기의 상태를 표시할 수 없습니다.
• 일부 기기의 경우 앱에 정확한 상태가 항상 반영되지 않을 수 있으며, 앱에서 Google Home 앱과 같은 Google 앱에서 보고하는 상태와 다른 상태를 보고할 수 있습니다. 이는 일반적으로 기기에서 Google에 상태를 보고하지 않기 때문입니다.
  • 해결 방법: Google 앱으로 상태를 확인하면 불일치가 해결됩니다.

2025-01-14

Home API 초기화 안내가 업데이트되었습니다.

홈 인스턴스를 컨텍스트 싱글톤으로 초기화해야 한다는 점을 더 명확하게 했습니다. 이렇게 하면 앱에서 더 원활한 사용자 환경을 제공하고 유효하지 않은 세션으로 인한 오류를 방지할 수 있습니다.

2025-01-07

  Home API 공개 베타 출시  

공개 개발자 베타 기간 동안 모든 개발자는 앱을 빌드하고 테스트할 수 있습니다.

이번 출시에는 버그 수정이 포함되어 있으며 Google Nest Audio 및 Google TV 기기 지원 개선을 비롯해 Home API Android SDK의 베타 품질이 향상되었습니다.

최소 버전

• Google Play 서비스 최소 버전: 24.45.34
• Google 허브 펌웨어 최소 버전:
  • 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 Home 앱 (GHA)과 같은 Google 앱에서 보고한 상태와 다른 상태를 보고할 수 있습니다. 이는 일반적으로 기기에서 Google에 상태를 보고하지 않기 때문에 발생합니다.
  • 해결 방법: Google 앱으로 상태를 확인하면 불일치가 해결됩니다.

알려진 문제 해결

• 프로세스 중에 앱이 최소화되면 커미셔닝이 실패할 수 있습니다.
  • 해결 방법: 앱에서 커미셔닝 API를 사용하는 경우 suppressHalfSheetNotification() API를 사용하여 절반 시트 알림을 억제합니다.
• 서버 측 문제로 인해 자동화에서 OkGoogle 스타터가 작동하지 않을 수 있습니다.
• 구조에 Matter 기기가 없는 Fuchsia를 실행하는 허브를 사용하는 경우 허브가 3시간 이상 유휴 상태로 유지되면 첫 번째 Matter 기기를 커미셔닝하면 Matter 기기가 오프라인 상태가 됩니다.
• 허브를 초기화한 후 새로 커미셔닝된 기기에 대한 명령어가 기기가 온라인으로 보고되더라도 실패할 수 있습니다.