Commissioning API（如果是 Android）

借助 Commissioning API，应用可以调试以下内容：

  • 您的结构和 Google 结构。
  • 仅 Google 结构。

调试 Matter 设备的方式

调试流程可以通过以下方式启动：

直接在应用中请求调试

直接在应用中请求调试可以通过应用中的按钮触发，并且可以通过以下两种方式完成：

对于单个结构

如需请求调试，请执行以下操作：

  1. 在您的 activity 中初始化 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 返回 intent 发送器后，启动该发送器：

    commissioningIntentSender.observe(this) { sender ->
  if (sender != null) {
    commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
  }
}

对于多个结构（多管理员）

如果您需要在设备上设置多个 Matter 结构， 请参阅 Android 上 Commissioning API 的多管理员。

“快速配对”或二维码扫描的 Matter 调试入口点（仅限 Android）

在 Android 上，可以通过以下两种方式使用“快速配对”或二维码请求调试：

对于单个结构

使用 ACTION_START_COMMISSIONING intent 过滤器 为应用提供完整的调试功能，而无需 GHA。调试到 Google 结构时，这包括允许用户为设备分配名称。

使用 ACTION_START_COMMISSIONING 的调试流程
图 1：使用 ACTION_START_COMMISSIONING

如需指明支持 Google 结构调试，请将以下 intent-filter 添加到 AndroidManifest.xml 文件中选择的 activity 声明中：

<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 应用列表中。 如果您的应用不是建议的应用之一，它会显示在选择其他应用 选项中。

用户选择您的应用后，系统会启动您的应用，并使用 ACTION_START_COMMISSIONING intent 将其定向到所选 activity。

对于多个结构（多管理员）

您还可以在多管理员场景中使用 FastPair 流程。 如需了解详情，请参阅 Android 上 Commissioning API 的多管理员。

处理传入的 intent

您的 activity 启动后，应检查是否存在 ACTION_START_COMMISSIONING intent 并检索载荷：

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，则表示用户已扫描设备二维码或输入配对密钥。null 载荷值不 表示应中止调试。

禁止显示可调试发现通知

Android 半屏通知示例
图 1：Android 半屏通知示例

默认情况下，Google Play services 在 Android 上会使用“半屏”通知（覆盖移动设备屏幕的下半部分）主动向用户表明附近有可调试的 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 生态系统通用地分享设备。