Android의 Commissioning API

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

  • 패브릭 및 Google 패브릭
  • Google 패브릭만

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

커미셔닝 프로세스는 다음을 통해 시작할 수 있습니다.

앱에서 직접 커미셔닝 요청

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

단일 패브릭의 경우

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

  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를 구성하고 를 사용하여 기기를 Google 패브릭에 커미셔닝하는 옵션을 설정합니다.setStoreToGoogleFabric

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

    기기를 Google 패브릭과 자체 패브릭에 커미셔닝하려면 setCommissioningService에서 커미셔닝 서비스를 설정합니다.CommissioningRequest

  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의 Commissioning API용 다중 관리자를 참고하세요.

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

Android에서 빠른 페어링 또는 QR 코드를 통해 커미셔닝을 요청하는 것은 다음 두 가지 방법으로 실행할 수 있습니다.

단일 패브릭의 경우

ACTION_START_COMMISSIONING 인텐트 필터를 사용하여 GHA 없이 앱에 전체 커미셔닝 기능을 제공합니다. Google 패브릭에 커미셔닝할 때 사용자가 기기에 이름을 할당할 수 있도록 허용하는 것이 포함됩니다.

ACTION_START_COMMISSIONING을 사용한 커미셔닝 흐름
그림 1: 다음을 사용한 커미셔닝 흐름 ACTION_START_COMMISSIONING

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는 Commissioning APIs 앱 선택 도구에서 추천 Matter 앱 목록에 앱을 포함하는 데 사용됩니다. 앱이 추천 앱 중 하나가 아닌 경우 다른 앱 선택 옵션에 표시됩니다.

사용자가 앱을 선택하면 앱이 실행되고 선택한 활동으로 ACTION_START_COMMISSIONING 인텐트가 있는 이동합니다.

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

다중 관리자 시나리오에서 빠른 페어링 흐름을 사용할 수도 있습니다. 자세한 내용은 Android의 Commissioning 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

null이 아닌 페이로드 값은 사용자가 이미 기기 QR 코드를 스캔했거나 페어링 키를 입력했음을 나타냅니다. null 페이로드 값은 커미셔닝을 중단해야 함을 의미하지 않습니다.

커미셔닝 가능한 검색 알림 표시 안함

Android 하프시트 알림의 예
그림 1: Android 하프시트 알림의 예

기본적으로 Google Play services의 Android는 모바일 기기 화면의 하단 절반을 덮는 "하프시트" 알림을 사용하여 사용자에게 커미셔닝 가능한 Matter 기기가 근처에 있음을 사전에 알려줍니다.

앱이 포그라운드에 있는 동안 중단을 방지하려면 메서드를 호출하여 이러한 알림을 suppressHalfSheetNotification() 표시하지 않을 수 있습니다. 자세한 내용은 API 참고 리소스를 참고하세요.

이 API로 사용 설정된 표시 안함은 앱이 15분 넘게 포그라운드에 있는 경우 시간이 초과됩니다. 시간 초과 후 표시 안함을 다시 사용 설정하려면 suppressHalfSheetNotification()을 다시 호출합니다. 그렇지 않으면 하프시트 알림이 표시되기 시작합니다.

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

자체 패브릭에서 이미 설정한 기기를 Google 패브릭과 공유하는 기본 수단으로 Commissioning API를 사용하는 것이 좋습니다. Share API에는 제한사항이 있으며 다른 사용 사례를 위해 예약해야 합니다.

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

Commissioning API를 사용하면 기기를 Google 패브릭과 직접 공유하도록 트리거할 수 있습니다. 이는 가능한 경우 선호되는 방법입니다. Share API를 사용하려면 최종 사용자에게 더 많은 단계가 필요합니다. 예를 들어 최종 사용자에게 GHA가 설치되어 있어야 하며 프로세스 중에 GHA를 선택하여 성공을 보장해야 합니다.

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

Share API를 사용해야 하는 경우는 언제인가요?

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