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 APIs のアプリ選択ツールで、おすすめの 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 と共有するにはどうすればよいですか？

Commissioning API を、独自のファブリックでセットアップ済みのデバイスを Google ファブリックと共有する主な手段として使用することを強くおすすめします。Share API には制限があるため、他のユースケースのために予約しておく必要があります。

Share API ではなく Commissioning API を使用すべき理由

Commissioning API を使用すると、デバイスを Google ファブリックと直接共有するようトリガーできます。これは、可能な場合に推奨される方法です。Share API では、エンドユーザーがより多くの手順を行う必要があります。たとえば、エンドユーザーは GHA をインストールし、プロセス中に GHA を選択して成功させる必要があります。

Commissioning API を使用するには、Commissioning API をセカンダリ Matter コミッショナーとして使用する方法で説明されているように、コミッショニング ウィンドウを開いて Commissioning API を呼び出す必要があります。

Share API を使用するタイミング

Share API を使用すると、エンドユーザーは、デバイスを他の Matter エコシステムと汎用的に共有するための対象アプリを選択できます。