API de Commissioning en Android

La API de Commissioning permite que una app realice la comisión en cualquiera de los siguientes casos:

  • Tu tejido y el de Google.
  • Solo la tela de Google.

Formas de asignar dispositivos Matter

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

Solicita la puesta en marcha directamente en tu app

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

Para telas individuales

Para solicitar la puesta en marcha, sigue estos pasos:

  1. Inicializa un ActivityResultLauncher en tu actividad. Si el usuario puso en funcionamiento el dispositivo en la estructura de Google, el resultado puede incluir el nombre que el usuario le asignó al dispositivo cuando lo puso en funcionamiento.

    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 objeto CommissioningRequest, incluidos los datos de carga útil recibidos, y configura la opción para encargar el dispositivo al tejido de Google con setStoreToGoogleFabric:

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

    Si quieres encargar el dispositivo al tejido de Google y a tu propio tejido, configura tu servicio de encargo 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, inicia el remitente:

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

Para varios fabrics (varios administradores)

Si necesitas configurar varias estructuras de Matter en un dispositivo, consulta Multi-admin para la API de Commissioning en Android.

Punto de entrada de la puesta en marcha de Matter para la Vinculación rápida o el escaneo de códigos QR (solo para Android)

La solicitud de puesta en marcha a través de la vinculación rápida o el código QR en Android se puede realizar de dos maneras:

Para telas individuales

Usa el filtro de intents ACTION_START_COMMISSIONING para proporcionar la capacidad de comisión completa para una app sin necesidad de GHA. Cuando se realiza la comisión en el tejido de Google, 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 dentro de 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>

El intent-filter se usa para incluir tu app en la lista de apps de 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 fabrics (varios administradores)

También puedes usar el flujo de Vinculación rápida en situaciones de varios administradores. Para obtener más información, consulta Multi-admin for Commissioning API on Android.

Cómo controlar el intent entrante

Una vez que se inicie tu actividad, debería verificar 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

Un valor de carga útil que no sea null indica que el usuario ya escaneó el código QR del dispositivo o ingresó la clave de vinculación. Un valor de carga útil de null no significa que se deba anular la puesta en marcha.

Cómo suprimir las notificaciones de descubrimiento que generan comisiones

Ejemplo de una notificación de hoja inferior de Android
Figura 1: Ejemplo de una notificación de hoja de media pantalla de Android

De forma predeterminada, Google Play services en Android usa notificaciones de "media 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 tu app está en primer plano, puedes suprimir estas notificaciones llamando al método suppressHalfSheetNotification(). Consulta la documentación de la API para obtener más información.

El tiempo de espera de 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 las notificaciones de media hoja.

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

Google recomienda que uses la API de Commissioning como el medio principal para compartir un dispositivo que ya configuraste en tu propio tejido con el tejido 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 el tejido de Google, 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 que debe 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 comisionado secundario de Matter.

¿Cuándo deberías 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.