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 Fabric の構成をサポートしていることを示すには、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 インテントとともに移動します。

複数のファブリックの場合（マルチ管理者）

マルチ管理シナリオで FastPair フローを使用することもできます。詳細については、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 のハーフシート通知の例

デフォルトでは、Android の Google Play services は、モバイル デバイスの画面の下半分を覆う「ハーフシート」通知を使用して、コミッション対象の 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 エコシステムと汎用的に共有する対象となるアプリを選択できます。