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 の アプリ選択ツールで、おすすめの 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エコシステムと汎用的に共有するのに適したアプリケーションを選択できます。