API de Commissioning en Android

La API de Commissioning permite que una app ponga en servicio lo siguiente:

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

Formas de poner en servicio dispositivos Matter

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

Solicita la puesta en servicio directamente en tu app

La solicitud de puesta en servicio directamente 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 la puesta en servicio, haz lo siguiente:

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

    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 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 servicio el dispositivo en la estructura de Google y en tu propia estructura, configura tu servicio de puesta en servicio con setCommissioningService en la CommissioningRequest.

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

    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 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 servicio 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 filtro de intents ACTION_START_COMMISSIONING para proporcionar la capacidad de puesta en servicio completa para una app sin necesidad de la 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 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, aparece 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
    }
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 null no significa que se deba anular la puesta en servicio.

Cómo suprimir las notificaciones de descubrimiento de dispositivos que se pueden poner en servicio

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 que se pueden poner en servicio 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 puesta en servicio 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 Matter ecosistemas.