调试 API

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

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

指明支持 Matter 委托

如果您使用 Google Home Mobile SDK 进行委托，则必须在 Google Home Developer Console 中添加应用软件包名称、实现我们的 Matter API，并通过处理 ACTION_COMMISSION_DEVICE intent 指明您的应用支持 Matter 委托。

将以下 intent-filter 添加到 AndroidManifest.xml 文件中的 application 声明：

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

如需参考，请参阅示例应用的清单。

调试 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 工厂，请参阅如何在多管理员模式下使用配置 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 流程。如需了解详情，请参阅如何在多管理员模式下使用配置 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 设备就在附近。

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

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

您可以在 Google Home Sample App for Matter 中找到此 API 的实现。如需了解详情，请参阅 HalfSheetSuppressionObserver.kt。

您应如何与 Google 共享 Matter 设备？

Google 强烈建议您将 Commissioning API 用作与 Google Fabric 共享您已在自己的 Fabric 上设置的设备的主要方式。Share API 有其局限性，应留作其他用例。

为何应使用 Commissioning API 而非 Share API？

借助调试 API，您可以触发直接与 Google Fabric 共享设备，这是可行情况下的首选方法。使用 Share API 时，最终用户需要执行更多步骤。例如，最终用户必须安装 GHA，并且必须知道在该过程中选择 GHA 才能确保成功。

如需使用 Commissioning API，您应打开配置窗口并调用 Commissioning API，如如何将 Commissioning API 用作次要 Matter 委托人中所述。

何时应使用 Share API？

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

上一页
问题排查
下一页
多管理员