Commissioning API（如果是 Android）

借助 Commissioning API，应用可以委托以下任一平台：

  • 您的 fabric 和 Google fabric。
  • 仅限 Google 面料。

调试 Matter 设备的方式

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

直接在应用中请求调试

您可以通过应用中的按钮直接在应用中请求调试，具体有以下两种方式：

对于单个面料

如需申请委托，请执行以下操作：

  1. 在 activity 中初始化 ActivityResultLauncher。如果用户在 Google Fabric 上委托了设备，则结果可能包含用户在委托设备时为其分配的名称。

    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 Fabric 和您自己的 Fabric，请在 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())
  }
}

对于多个 Fabric（多管理方）

如果您需要在设备上设置多个 Matter 工厂，请参阅 Android 上适用于配置 API 的多管理员。

用于快速配对或二维码扫描的 Matter 配置入口点（仅限 Android）

在 Android 设备上，您可以通过以下两种方式请求通过快速配对或二维码进行调试：

对于单个面料

使用 ACTION_START_COMMISSIONING intent 过滤器可为应用提供完整的配置功能，而无需 GHA。在将设备委托给 Google Fabric 时，这包括允许用户为设备分配名称。

使用 ACTION_START_COMMISSIONING 进行调试流程
图 1：使用 ACTION_START_COMMISSIONING 进行配置流程

如需指明支持 Google Fabric 委托，请将以下 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。

对于多个 Fabric（多管理方）

您还可以在多管理员场景中使用 FastPair 流程。如需了解详情，请参阅 Android 上适用于配置 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 半屏通知示例

默认情况下，Android 上的 Google Play services 会使用覆盖移动设备屏幕下半部分的“半页面”通知，以主动向用户指明可促成佣金的 Matter 设备就在附近。

如需在应用在前台运行时防止中断，您可以通过调用 suppressHalfSheetNotification() 方法来抑制这些通知。如需了解详情，请参阅 API 文档。

如果您的应用在前台运行超过 15 分钟，此 API 启用的抑制功能将超时。如需在超时后重新启用抑制功能，请再次调用 suppressHalfSheetNotification()，否则系统将开始显示半屏通知。

您应如何与 Google 分享 Fabric 上的 Matter 设备？

Google 强烈建议您将 Commissioning API 用作与 Google Fabric 共享您已在自己的 Fabric 上设置的设备的主要方式。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 生态系统通用地共享设备。