Commissioning API（Android）

Commissioning API を使用すると、アプリは次のいずれかにコミッショニングできます。

  • お客様のファブリックと Google のファブリック。
  • Google ファブリックのみ。

Matter デバイスをコミッショニングする方法

コミッショニング プロセスは、次の方法で開始できます。

アプリで直接コミッショニングをリクエストする

アプリで直接コミッショニングをリクエストするには、アプリのボタンをトリガーにします。これには次の 2 つの方法があります。

単一ファブリックの場合

コミッショニングをリクエストするには:

  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 での Commissioning API のマルチ管理者をご覧ください。

ファスト ペアリングまたは QR コード スキャンの Matter コミッショニング エントリ ポイント（Android のみ）

Android でファスト ペアリングまたは QR コードを使用してコミッショニングをリクエストするには、次の 2 つの方法があります。

単一ファブリックの場合

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 API のアプリ選択ツールで、推奨される 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 のハーフシート通知の例

デフォルトでは、Android の Google Play services は、モバイル デバイスの画面の下半分を覆う「ハーフシート」通知を使用して、コミッショニング可能な Matter デバイスが近くにあることをユーザーに事前に通知します。

アプリがフォアグラウンドで動作しているときに中断されないようにするには、suppressHalfSheetNotification() メソッドを呼び出して、これらの通知を抑制します。詳しくは、API ドキュメントをご覧ください。

この API で有効にした抑制は、アプリが 15 分以上フォアグラウンドにあるとタイムアウトします。タイムアウト後に抑制を再度有効にするには、suppressHalfSheetNotification() を再度呼び出します。そうしないと、ハーフシート通知が表示されるようになります。

ファブリック上の Matter デバイスを Google と共有するにはどうすればよいですか？

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 エコシステムとデバイスを一般的に共有できます。