API de Commissioning en Android

La API de Commissioning permite que una app realice la puesta en servicio en uno de los siguientes destinos:

  • Tu estructura y la estructura 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 comisión 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 una comisión, sigue estos pasos:

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

    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. Construye un objeto CommissioningRequest, que incluye los datos de carga útil recibidos, y configura la opción para poner en servicio el dispositivo en la estructura de Google con setStoreToGoogleFabric:

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

    Si quieres poner en marcha el dispositivo en la estructura de Google y en la tuya, configura tu servicio de puesta en marcha con setCommissioningService en CommissioningRequest.

  3. Usa la instancia CommissioningClient para comenzar la puesta en servicio:

    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 devuelve el remitente del intent, inicia el remitente:

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

Para varias telas (varios administradores)

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

Punto de entrada de la puesta en servicio de Matter para la Vinculación rápida o el escaneo de códigos QR (solo 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 puesta en marcha completa de una app sin necesidad del GHA. Cuando se pone en servicio en la estructura de Google, esto incluye permitir que el usuario asigne un nombre al dispositivo.

Flujo de puesta en servicio con ACTION_START_COMMISSIONING
Figura 1: Flujo de puesta en servicio con ACTION_START_COMMISSIONING

Para indicar la compatibilidad con la puesta en servicio 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 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 varias telas (varios administradores)

También puedes usar el flujo de Fast Pair en situaciones con 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, debe 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

Un valor de carga útil que no es 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 debe anular la comisión.

Cómo suprimir las notificaciones de descubrimiento aptas para comisiones

Ejemplo de una notificación de hoja media de Android
Figura 1: Ejemplo de una notificación de hoja media 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 aptos para recibir comisiones 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.

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 los dispositivos Matter en tu estructura con Google?

Google recomienda que uses la API de Commissioning como el medio principal para compartir un dispositivo que ya configuraste en tu propia estructura con la estructura de Google. La API de Share tiene sus limitaciones y debe reservarse 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 la estructura de Google, que es el método preferido cuando es viable. Con la API de Share, el usuario final debe realizar más pasos. Por ejemplo, el usuario final debe tener GHA instalado y saber que debe seleccionar GHA durante el proceso para garantizar el éxito.

Para usar la API de Commissioning, debes abrir la ventana de puesta en servicio 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.