Android 版 Commissioning API

透過 Commissioning API，應用程式可委派給下列任一項目：

  • 你的網狀架構和 Google 網狀架構。
  • 僅限 Google 織物。

調試 Matter 裝置的方式

你可以透過下列方式啟動委任程序：

直接在應用程式中要求啟用

您可以透過應用程式中的按鈕，直接在應用程式中要求委派作業，方法有兩種：

單一布料

如要申請委託，請按照下列步驟操作：

  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 多重管理員」。

Fast Pair 或掃描 QR code 的 Matter 委派進入點 (僅限 Android)

在 Android 上透過快速配對或 QR code 請求委派作業時，可以採取兩種方式：

單一布料

使用 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 code 或輸入配對金鑰。null 酬載值不表示應中止委派作業。

停用可賺取佣金的探索通知

Android 半頁通知範例
圖 1：Android 半頁通知範例

根據預設，Android 上的 Google Play services 會使用「半頁」通知，涵蓋行動裝置螢幕的下半部，主動向使用者指出附近有可賺取佣金的Matter裝置。

如要避免應用程式在前台執行時受到干擾，您可以呼叫 suppressHalfSheetNotification() 方法，禁止顯示這些通知。詳情請參閱 API 說明文件。

如果應用程式在前台執行超過 15 分鐘，這項 API 啟用的抑制功能就會逾時。如要在逾時後重新啟用抑制功能，請再次呼叫 suppressHalfSheetNotification()，否則系統會開始顯示半頁通知。

如何透過 Google 分享網狀架構中的 Matter 裝置？

Google 強烈建議您使用 Commissioning API，將已在自有網路上設定的裝置分享到 Google 網路。Share API 有其限制，應保留用於其他用途。

為什麼應該使用 Commissioning API，而不是 Share API？

透過 Commissioning API，您可以直接觸發與 Google 網狀架構共用裝置，這是可行的首選方法。使用 Share API 時，使用者必須執行更多步驟。舉例來說，使用者必須安裝 GHA，且必須知道在過程中選取 GHA，才能確保成功。

如要使用 Commissioning API，請開啟委派視窗並呼叫 Commissioning API，詳情請參閱「如何使用 Commissioning API 做為次要 Matter 委派裝置」。

何時應使用 Share API？

您可以使用 Share API，讓使用者選擇要與其他 Matter 生態系統分享裝置的應用程式。