API de Commissioning

La API de Commissioning permite que una app realice la comisión a una de las siguientes entidades:

  • Tu tejido y el tejido de Google.
  • Solo el material de Google.

Cómo indicar la compatibilidad con la comisión de Matter

Si usas Google Home Mobile SDK para la comisión, debes agregar el nombre del paquete de la app en Google Home Developer Console, implementar nuestras APIs de Matter e indicar que tu app admite la comisión de Matter controlando el intent ACTION_COMMISSION_DEVICE.

Agrega el siguiente intent-filter a la declaración application dentro de tu archivo AndroidManifest.xml:

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

Consulta el manifiesto de la app de ejemplo como referencia.

Formas de comisionar dispositivos Matter

El proceso de puesta en servicio se puede iniciar de las siguientes maneras:

Solicita la comisión directamente en tu app

La solicitud de comisión directamente en la app se puede activar con un botón en la app y se puede hacer de dos maneras:

Para tejidos individuales

Para solicitar la puesta en marcha, sigue estos pasos:

  1. Inicializa un ActivityResultLauncher en tu actividad. Si el usuario comisionó el dispositivo en Google Fabric, el resultado puede incluir el nombre que el usuario asignó al dispositivo cuando lo comisionó.

    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. Crea un CommissioningRequest, que incluya los datos de carga útil recibidos, y establece la opción para comisionar el dispositivo a Google Fabric con setStoreToGoogleFabric:

    val commissioningRequest = CommissioningRequest.builder()
        .setOnboardingPayload(payload)
        .setStoreToGoogleFabric(true)
  // set all other options that you care about
        .build()

    Si quieres encargar el dispositivo a Google Fabric y a tu propio tejido, configura tu servicio de comisión con setCommissioningService en CommissioningRequest.

  3. Usa la instancia CommissioningClient para iniciar la comisión:

    commissioningClient
  .commissionDevice(commissioningRequest)
  .addOnSuccessListener { result ->
    Log.i("CommissioningActivity", "Commissioning success")
_commissioningIntentSender.postValue(result)
      }
      .addOnFailureListener { error ->
        Log.i("CommissioningActivity", "Commissioning failed")
  }

    En el ejemplo anterior, _commissioningIntentSender se define de la siguiente manera:

    private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
    val commissioningIntentSender: LiveData<IntentSender?>
    get() = _commissioningIntentSender

  4. Una vez que CommissioningClient devuelva el remitente del intent, inícialo:

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

Para varios tejidos (administrador múltiple)

Si necesitas configurar varios tejidos Matter en un dispositivo, consulta Cómo usar las APIs de comisión en el modo de varios administradores.

Punto de entrada de la comisión de Matter para la vinculación rápida o el escaneo de códigos QR (solo para Android)

La solicitud de la comisión mediante la vinculación rápida o el código QR en Android se puede hacer de dos maneras:

Para tejidos individuales

Usa el filtro de intents ACTION_START_COMMISSIONING para proporcionar la capacidad de comisión completa de una app sin necesidad de GHA. Cuando se realiza la comisión en Google Fabric, esto incluye permitir que el usuario asigne un nombre al dispositivo.

Flujo de comisión con ACTION_START_COMMISSIONING
Figura 1: Flujo de comisión con ACTION_START_COMMISSIONING

Para indicar la compatibilidad con la comisión de Google Fabric, agrega el siguiente intent-filter a la declaración de actividad elegida en tu archivo AndroidManifest.xml:

<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 se usa para incluir tu app en la lista de apps Matter sugeridas en el selector de apps de las APIs de Commissioning. Si tu app no es una de las sugeridas, aparecerá en la opción Elegir otra app.

Una vez que el usuario selecciona tu app, esta se inicia y se dirige a la actividad elegida con un intent ACTION_START_COMMISSIONING.

Para varios tejidos (administrador múltiple)

También puedes usar el flujo de FastPair en situaciones de varios administradores. Para obtener más información, consulta Cómo usar las APIs de comisión en el modo de varios administradores.

Cómo controlar el intent entrante

Una vez que se inicie tu actividad, esta debería buscar el intent ACTION_START_COMMISSIONING existente y recuperar la carga útil:

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

Un valor de carga útil que no sea null indica que el usuario ya leyó el código QR del dispositivo o ingresó la clave de vinculación. Un valor de carga útil null no significa que se debe abortar la comisión.

Cómo suprimir las notificaciones de descubrimiento comisionables

Ejemplo de una notificación de mitad de pantalla para Android
Figura 1: Ejemplo de una notificación de mitad de pantalla de Android

De forma predeterminada, Google Play services en Android usa notificaciones de "mitad de hoja" que cubren la mitad inferior de la pantalla de un dispositivo móvil para proporcionar a los usuarios una indicación proactiva de que hay dispositivos Matter comisionables cerca.

Para evitar interrupciones mientras la app está en primer plano, puedes suprimir estas notificaciones llamando al Método suppressHalfSheetNotification() en Mobile SDK. Consulta la documentación de la API para obtener más información.

La supresión habilitada por esta API se agota si tu app está en primer plano durante más de 15 minutos. Para volver a habilitar la supresión después de un tiempo de espera, vuelve a llamar a suppressHalfSheetNotification(). De lo contrario, comenzarán a aparecer notificaciones de la mitad de la hoja.

Puedes encontrar una implementación de esta API en Google Home Sample App for Matter. Consulta HalfSheetSuppressionObserver.kt para obtener más información.

¿Cómo debes compartir los dispositivos Matter de tu tejido con Google?

Google recomienda que uses la API de Commissioning como tu medio principal para compartir un dispositivo que ya configuraste en tu propio fabric con el fabric de Google. La API de Share tiene sus limitaciones y se debe reservar para otros casos de uso.

¿Por qué deberías usar la API de Commissioning en lugar de la API de Share?

La API de Commissioning te permite activar el uso compartido de un dispositivo directamente con Google Fabric, que es el método preferido cuando es viable. Con la API de Share, se requieren más pasos para el usuario final. Por ejemplo, el usuario final debe tener instalado GHA y debe saber seleccionar GHA durante el proceso para garantizar el éxito.

Para usar la API de Commissioning, debes abrir la ventana de comisión y llamar a la API de Commissioning, como se describe en Cómo usar la API de Commissioning como el comisionado secundario de Matter.

¿Cuándo debes usar la API de Share?

Puedes usar la API de Share para permitir que el usuario final elija una aplicación apta para compartir un dispositivo de forma genérica con otros ecosistemas de Matter.

Anterior
Solución de problemas
Siguiente
Varios administradores