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を作成し、 を使用して、デバイスを 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 コードを使用してコミッショニングをリクエストするには、次の 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 の app picker で、推奨される Matter アプリのリストにアプリを含めるために使用されます。 アプリが推奨アプリの 1 つでない場合は、[他のアプリを選択] オプションに表示されます。

ユーザーがアプリを選択すると、アプリが起動し、選択した アクティビティに 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
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エコシステムと汎用的に共有するのに適したアプリケーションを選択できます。