Commissioning API（如果是 Android）

借助调试 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，包括接收到的载荷数据，并使用 setStoreToGoogleFabric 将设备委托给 Google Fabric：

    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 返回 intent 发送方后，启动发送方：

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

对于多个功能区（多管理方）

如果您需要在设备上设置多个 Matter 结构，请参阅 Android 上用于调试的 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 用于将您的应用纳入调试 API 应用选择器中的建议 Matter 应用列表。 如果您的应用不是建议的应用之一，则会显示在选择其他应用选项中。

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

对于多个功能区（多管理方）

您还可以在多管理员场景中使用 FastPair 流程。如需了解详情，请参阅 Android 上用于调试的 Multi-admin 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 Fabric 触发设备分享，这是可行的首选方法。使用 Share API 时，最终用户需要执行更多步骤。例如，最终用户必须安装 GHA，并且必须知道在流程中选择 GHA 才能确保成功。

如需使用 Commissioning API，您应打开调试窗口并调用 Commissioning API，如如何将 Commissioning API 用作辅助 Matter 调试器中所述。

何时应使用 Share API？

您可以使用 Share API 让最终用户选择一个符合条件的应用，以便与 Matter 生态系统的其他设备共享设备。