Android의 Commissioning API

커미셔닝 API를 사용하면 앱이 다음 중 하나로 커미셔닝할 수 있습니다.

• 내 패브릭과 Google 패브릭
• Google 패브릭만

Matter 기기를 커미셔닝하는 방법

커미셔닝 프로세스는 다음 방법으로 시작할 수 있습니다.

• 앱에서 직접
• Android의 빠른 페어링을 통해

앱에서 직접 커미셔닝 요청

앱에서 직접 커미셔닝을 요청하는 것은 앱의 버튼으로 트리거할 수 있으며 다음 두 가지 방법으로 실행할 수 있습니다.

• 단일 패브릭의 경우
• 여러 직물

단일 직물의 경우

커미셔닝을 요청하려면 다음 단계를 따르세요.

1. 활동에서 ActivityResultLauncher을 초기화합니다. 사용자가 Google 패브릭에서 기기를 커미셔닝한 경우 결과에는 사용자가 커미셔닝할 때 기기에 할당한 이름이 포함될 수 있습니다.

   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")
         }
       }
   

2. 수신된 페이로드 데이터를 포함하여 CommissioningRequest을 생성하고 setStoreToGoogleFabric을 사용하여 기기를 Google 패브릭에 커미셔닝하는 옵션을 설정합니다.

   val commissioningRequest = CommissioningRequest.builder()
           .setOnboardingPayload(payload)
           .setStoreToGoogleFabric(true)
     // set all other options that you care about
           .build()
   

   Google 패브릭과 자체 패브릭에 모두 기기를 커미셔닝하려면 CommissioningRequest에서 setCommissioningService로 커미셔닝 서비스를 설정하세요.

3. 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
   

4. CommissioningClient가 인텐트 발신자를 반환하면 발신자를 실행합니다.

   commissioningIntentSender.observe(this) { sender ->
     if (sender != null) {
       commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
     }
   }
   

여러 패브릭 (다중 관리자)

기기에서 여러 Matter 패브릭을 설정해야 하는 경우 Android의 커미셔닝 API 다중 관리자를 참고하세요.

빠른 페어링 또는 QR 코드 스캔을 위한 Matter 커미셔닝 진입점 (Android만 해당)

Android에서 빠른 페어링 또는 QR 코드를 통해 커미셔닝을 요청하는 방법은 두 가지입니다.

• 단일 패브릭의 경우
• 여러 직물

단일 직물의 경우

GHA가 필요하지 않고 앱의 전체 커미셔닝 기능을 제공하려면 ACTION_START_COMMISSIONING 인텐트 필터를 사용하세요. Google 패브릭에 커미셔닝할 때 사용자가 기기에 이름을 할당하도록 허용하는 것이 포함됩니다.

Google 패브릭 커미셔닝 지원을 나타내려면 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 인텐트로 선택한 활동으로 이동합니다.

여러 패브릭 (다중 관리자)

다중 관리자 시나리오에서 FastPair 흐름을 사용할 수도 있습니다. 자세한 내용은 Android의 커미셔닝 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 기기가 근처에 있음을 사전 예방적으로 표시합니다.

앱이 포그라운드에 있는 동안 중단을 방지하려면 suppressHalfSheetNotification() 메서드를 호출하여 이러한 알림을 억제하면 됩니다. 자세한 내용은 API 문서를 참고하세요.

이 API로 사용 설정된 억제는 앱이 15분 이상 포그라운드에 있으면 타임아웃됩니다. 타임아웃 후 억제를 다시 사용 설정하려면 suppressHalfSheetNotification()를 다시 호출하세요. 그렇지 않으면 절반 시트 알림이 표시되기 시작합니다.

패브릭에서 Google과 Matter 기기를 공유하려면 어떻게 해야 하나요?

커미셔닝 API를 사용하여 자체 패브릭에 이미 설정한 기기를 Google 패브릭과 공유하는 것이 좋습니다. Share API에는 제한사항이 있으므로 다른 사용 사례에 사용해야 합니다.

Share API 대신 Commissioning API를 사용해야 하는 이유는 무엇인가요?

커미셔닝 API를 사용하면 기기를 Google 패브릭과 직접 공유할 수 있으며, 이는 가능한 경우 권장되는 방법입니다. Share API를 사용하면 최종 사용자에게 더 많은 단계가 필요합니다. 예를 들어 최종 사용자는 GHA를 설치해야 하며, 성공을 위해 프로세스 중에 GHA를 선택해야 합니다.

커미셔닝 API를 사용하려면 보조 Matter 커미셔너로 커미셔닝 API를 사용하는 방법에 설명된 대로 커미셔닝 창을 열고 커미셔닝 API를 호출해야 합니다.

Share API는 언제 사용해야 하나요?

Share API를 사용하여 최종 사용자가 다른 Matter 생태계와 기기를 일반적인 방식으로 공유할 수 있는 적합한 애플리케이션을 선택하도록 할 수 있습니다.