API de Commissioning en Android

La API de Commissioning permite que una app comisione a lo siguiente:

  • Tu estructura y la estructura de Google
  • Solo la estructura de Google

Formas de comisionar dispositivos Matter

El proceso de comisionamiento se puede iniciar de las siguientes maneras:

Solicita el comisionamiento directamente en tu app

El comisionamiento directo en la app se puede activar con un botón en la app y se puede realizar de dos maneras:

Para estructuras únicas

Para solicitar el comisionamiento, haz lo siguiente:

  1. Inicializa un ActivityResultLauncher en tu actividad. Si el usuario comisionó el dispositivo en la estructura de Google, el resultado puede incluir el nombre que el usuario le 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, incluidos los datos de carga útil recibidos, y configura la opción para comisionar 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 comisionar el dispositivo en la estructura de Google y en tu propia estructura, configura tu servicio de comisionamiento con setCommissioningService en el CommissioningRequest.

  3. Usa la CommissioningClient instancia para iniciar el comisionamiento:

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

    Donde _commissioningIntentSender se define de la siguiente manera:

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

  4. Una vez que CommissioningClient muestre el remitente del intent, inicia el remitente:

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

Para varias estructuras (varios administradores)

Si necesitas configurar varias estructuras Matter en un dispositivo, consulta Varios administradores para la API de Commissioning en Android.

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

El comisionamiento a través de la Vinculación rápida o el código QR en Android se puede realizar de dos maneras:

Para estructuras únicas

Usa el ACTION_START_COMMISSIONING filtro de intents para proporcionar la capacidad de comisionamiento completa para una app sin necesidad de la GHA. Cuando se comisiona 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 comisionamiento con ACTION_START_COMMISSIONING

Para indicar la compatibilidad con el comisionamiento de la estructura de Google, 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>

El intent-filter se usa para incluir tu app en la lista de apps sugeridas Matter en el selector de apps de las APIs de Commissioning. Si tu app no es una de las apps 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 ACTION_START_COMMISSIONING intent.

Para varias estructuras (varios administradores)

También puedes usar el flujo de FastPair en situaciones de varios administradores. Para obtener más información, consulta Varios administradores para la API de Commissioning en Android.

Cómo controlar el intent entrante

Una vez que se inicia 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 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 null no significa que se deba anular el comisionamiento.

Cómo suprimir las notificaciones de descubrimiento comisionables

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

De forma predeterminada, Google Play services en Android usa notificaciones de "hoja inferior" 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 suppressHalfSheetNotification() método. 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 hoja inferior.

¿Cómo debes compartir 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, se requieren más pasos para el usuario final. Por ejemplo, el usuario final debe tener GHA instalada y debe saber cómo seleccionar GHA durante el proceso para garantizar el éxito.

Para usar la API de Commissioning, debes abrir la ventana de comisionamiento y llamar a la API de Commissioning, como se describe en Cómo usar la API de Commissioning como comisionador 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 Matter ecosistemas.