Commissioning API를 사용하면 앱에서 다음 중 하나에 커미셔닝할 수 있습니다.
- 개발자 제공 패브릭과 Google 패브릭
- Google Fabric만
Matter 커미셔닝 지원 알리기
Google Home Mobile SDK를 사용하여 커미셔닝하는 경우 Google Home Developer Console에 앱 패키지 이름을 추가하고 Matter API를 구현하고 ACTION_COMMISSION_DEVICE
인텐트를 처리하여 앱이 Matter 커미셔닝을 지원한다고 표시해야 합니다.
AndroidManifest.xml
파일 내의 application
선언에 다음 intent-filter
를 추가합니다.
<intent-filter>
<action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>
참고용 샘플 앱의 매니페스트를 확인하세요.
Matter 기기 커미셔닝 방법
다음과 같은 방법으로 커미셔닝 프로세스를 시작할 수 있습니다.
앱에서 직접 커미셔닝 요청
앱에서 직접 커미셔닝을 요청하는 것은 앱의 버튼으로 트리거할 수 있으며 다음 두 가지 방법으로 할 수 있습니다.
단일 직물의 경우
커미셔닝을 요청하려면 다음 단계를 따르세요.
활동에서
ActivityResultLauncher
을(를) 초기화합니다. 사용자가 Google Fabric에서 기기를 커미셔닝한 경우 결과에 사용자가 커미셔닝할 때 기기에 할당한 이름이 포함될 수 있습니다.private val commissioningLauncher = registerForActivityResult(StartIntentSenderForResult()) { result -> val resultCode = result.resultCode if (resultCode == RESULT_OK) { Log.i("CommissioningActivity", "Commissioning success") val deviceName = CommissioningResult.fromIntentSenderResult(result.resultCode, result.data).deviceName } else { Log.i("CommissioningActivity", "Commissioning failed") } }
수신된 페이로드 데이터를 포함하여
CommissioningRequest
를 생성하고setStoreToGoogleFabric
를 사용하여 기기를 Google Fabric에 커미셔닝하는 옵션을 설정합니다.val commissioningRequest = CommissioningRequest.builder() .setOnboardingPayload(payload) .setStoreToGoogleFabric(true) // set all other options that you care about .build()
기기를 자체 패브릭뿐만 아니라 Google 패브릭에도 커미셔닝하려면
CommissioningRequest
에서setCommissioningService
를 사용하여 커미셔닝 서비스를 설정하세요.CommissioningClient
인스턴스를 사용하여 커미셔닝을 시작합니다.commissioningClient .commissionDevice(commissioningRequest) .addOnSuccessListener { result -> Log.i("CommissioningActivity", "Commissioning success") _commissioningIntentSender.postValue(result) } .addOnFailureListener { error -> Log.i("CommissioningActivity", "Commissioning failed") }
여기서
_commissioningIntentSender
는 다음과 같이 정의됩니다.private val _commissioningIntentSender = MutableLiveData<IntentSender?>() val commissioningIntentSender: LiveData<IntentSender?> get() = _commissioningIntentSender
CommissioningClient
가 인텐트 전송자를 반환하면 전송자를 실행합니다.commissioningIntentSender.observe(this) { sender -> if (sender != null) { commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build()) } }
여러 Fabric (복수 관리자)
기기에 여러 개의 Matter 패브릭을 설정해야 하는 경우 멀티 관리자 모드에서 커미셔닝 API를 사용하는 방법을 참고하세요.
빠른 페어링 또는 QR 코드 스캔을 위한 Matter 커미셔닝 진입점 (Android만 해당)
Android에서 빠른 페어링 또는 QR 코드를 사용하여 커미셔닝을 요청하는 방법은 다음 두 가지가 있습니다.
단일 직물의 경우
ACTION_START_COMMISSIONING
인텐트 필터를 사용하여 GHA 없이 앱에 전체 커미셔닝 기능을 제공합니다. Google Fabric에 커미셔닝할 때는 사용자가 기기에 이름을 할당할 수 있도록 허용하는 것이 포함됩니다.
Google Fabric 커미셔닝 지원을 나타내려면 AndroidManifest.xml
파일 내에서 선택한 활동 선언에 다음 intent-filter
를 추가합니다.
<intent-filter>
<action android:name="com.google.android.gms.home.matter.ACTION_START_COMMISSIONING" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
intent-filter
는 커미셔닝 API 앱 선택 도구의 추천 Matter 앱 목록에 앱을 포함하는 데 사용됩니다.
추천 앱에 포함되지 않은 앱은 다른 앱 선택 옵션에 표시됩니다.
사용자가 앱을 선택하면 앱이 실행되고 ACTION_START_COMMISSIONING
인텐트를 사용하여 선택한 활동으로 이동합니다.
여러 Fabric (다중 관리자)
멀티 관리자 시나리오에서 FastPair 흐름을 사용할 수도 있습니다. 자세한 내용은 멀티 관리자 모드에서 커미셔닝 API를 사용하는 방법을 참고하세요.
수신 인텐트 처리
활동이 실행되면 기존 ACTION_START_COMMISSIONING
인텐트를 확인하고 페이로드를 가져와야 합니다.
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val payload = if (Matter.ACTION_START_COMMISSIONING.equals(intent.getAction())) {
intent.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
} else {
null
}
CommissioningRequest.builder()
.setOnboardingPayload(payload)
.setStoreToGoogleFabric(true)
// set all other options that you care about
startCommissioning(commissioningRequest)
}
null
가 아닌 페이로드 값은 사용자가 이미 기기 QR 코드를 스캔했거나 페어링 키를 입력했음을 나타냅니다. null
페이로드 값이 반환되었다고 해서 커미셔닝을 중단해야 한다는 의미는 아닙니다.
수수료 지급 가능 탐색 알림 숨기기
기본적으로 Android의 Google Play services는 휴대기기 화면의 하단 절반을 덮는 '하프시트' 알림을 사용하여 사용자에게 수수료 지급 대상 Matter 기기가 근처에 있음을 사전에 알립니다.
앱이 포그라운드에 있는 동안 중단을 방지하려면 Mobile SDK에서 suppressHalfSheetNotification()
메서드를 호출하여 이러한 알림을 억제할 수 있습니다. 자세한 내용은 API 문서를 참고하세요.
이 API로 사용 설정된 억제는 앱이 15분 넘게 포그라운드에 있으면 타임아웃됩니다. 제한 시간 후 억제를 다시 사용 설정하려면 suppressHalfSheetNotification()
를 다시 호출합니다. 그러지 않으면 하프시트 알림이 표시되기 시작합니다.
이 API의 구현은 Google Home Sample App for Matter에서 확인할 수 있습니다. 자세한 내용은 HalfSheetSuppressionObserver.kt
을 참조하세요.
Fabric의 Matter 기기를 Google과 공유하려면 어떻게 해야 하나요?
자체 Fabric에 이미 설정된 기기를 Google Fabric과 공유하는 기본 수단으로 Commissioning API를 사용하는 것이 좋습니다. Share API에는 제한사항이 있으며 다른 사용 사례에만 사용해야 합니다.
Share API 대신 Commissioning API를 사용해야 하는 이유는 무엇인가요?
Commissioning API를 사용하면 Google Fabric과 직접 기기 공유를 트리거할 수 있습니다. 이는 가능한 경우 권장되는 방법입니다. Share API를 사용하면 최종 사용자가 더 많은 단계를 거쳐야 합니다. 예를 들어 최종 사용자는 GHA가 설치되어 있어야 하며, 성공을 보장하려면 프로세스 중에 GHA를 선택해야 한다는 것을 알아야 합니다.
Commissioning API를 사용하려면 Commissioning API를 보조 Matter 커미셔너로 사용하는 방법에 설명된 대로 커미셔닝 창을 열고 Commissioning API를 호출해야 합니다.
Share API는 언제 사용해야 하나요?
Share API를 사용하여 최종 사용자가 기기를 다른 Matter 생태계와 일반적으로 공유할 수 있는 적합한 애플리케이션을 선택하도록 할 수 있습니다.