Commissioning API（如果是 Android）

Commissioning API 允许应用执行以下任一操作：

• 您的结构和 Google 结构。
• 仅限 Google 织物。

Matter 设备的调试方式

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

• 直接在应用中
• 通过 Android 上的“快速配对”功能。

直接在应用中请求调试

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

• 对于单层织物
• 适用于多种面料

对于单个 Fabric

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

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 结构：

   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())
     }
   }
   

对于多个 Fabric（多管理方流程）

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

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

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

• 对于单层织物
• 适用于多种面料

对于单个 Fabric

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

如需指明支持 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 用于将您的应用添加到 Commissioning API 应用选择器中的建议 Matter 应用列表中。如果您的应用不是建议的应用之一，则会显示在选择其他应用选项中。

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

对于多个 Fabric（多管理方流程）

您还可以在多管理员场景中使用快速配对流程。 如需了解详情，请参阅 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

如果载荷值不为 null，则表示用户已扫描设备二维码或输入了配对密钥。null 载荷值并不意味着应中止调试。

禁止显示可佣金发现通知

默认情况下，Android 上的 Google Play services 会使用覆盖移动设备屏幕下半部分的“半页”通知，主动向用户指示附近有可调试的 Matter 设备。

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

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

如何与 Google 共享 Fabric 上的 Matter 设备？

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