API de comissionamento no Android

A API Commissioning permite que um app faça o provisionamento para:

  • Seu tecido e o tecido do Google.
  • Apenas o tecido do Google.

Como comissionar dispositivos Matter

O processo de comissionamento pode ser iniciado:

Solicitar o provisionamento diretamente no seu app

A solicitação de comissionamento diretamente no app pode ser acionada por um botão no app e pode ser feita de duas maneiras:

Para tecidos únicos

Para solicitar uma comissão:

  1. Inicialize um ActivityResultLauncher na sua atividade. Se o usuário tiver comissionado o dispositivo no tecido do Google, o resultado poderá incluir o nome atribuído ao dispositivo no momento do comissionamento.

    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. Construa um CommissioningRequest, incluindo os dados de payload recebidos, e defina a opção para comissionar o dispositivo para a estrutura do Google, usando setStoreToGoogleFabric:

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

    Se você quiser comissionar o dispositivo para o tecido do Google e para o seu, defina o serviço de comissionamento com setCommissioningService no CommissioningRequest.

  3. Use a instância CommissioningClient para iniciar o provisionamento:

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

    Em que _commissioningIntentSender é definido como:

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

  4. Depois que o CommissioningClient retornar o remetente da intent, inicie o remetente:

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

Para várias estruturas (multiadministrador)

Se você precisar configurar várias estruturas Matter em um dispositivo, consulte Multiadministrador para API Commissioning no Android.

Ponto de entrada de provisionamento do Matter para Pareamento rápido ou leitura de QR code (apenas no Android)

A solicitação de provisionamento por pareamento rápido ou QR code no Android pode ser feita de duas maneiras:

Para tecidos únicos

Use o filtro de intent ACTION_START_COMMISSIONING para oferecer capacidade total de comissionamento a um app sem precisar do GHA. Ao comissionar para a estrutura do Google, isso inclui permitir que o usuário atribua um nome ao dispositivo.

Fluxo de provisionamento usando ACTION_START_COMMISSIONING
Figura 1: fluxo de provisionamento usando ACTION_START_COMMISSIONING

Para indicar suporte ao provisionamento de tecido do Google, adicione o seguinte intent-filter à declaração de atividade escolhida no seu arquivo 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>

O intent-filter é usado para incluir seu app na lista de apps Matter sugeridos no seletor de apps das APIs de comissionamento. Se o app não for um dos sugeridos, ele vai aparecer na opção Escolher outro app.

Depois que o usuário seleciona seu app, ele é iniciado e direcionado para a atividade escolhida com um intent ACTION_START_COMMISSIONING.

Para várias estruturas (multiadministrador)

Também é possível usar o fluxo do FastPair em cenários com vários administradores. Para mais informações, consulte Multiadministrador para a API Commissioning no Android.

Processar a intent recebida

Depois que a atividade for iniciada, ela vai verificar o intent ACTION_START_COMMISSIONING e recuperar a 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)
}

Um valor de payload que não seja null indica que o usuário já leu o QR code do dispositivo ou inseriu a chave de pareamento. Um valor de payload null não significa que o provisionamento deve ser cancelado.

Suprimir notificações de descoberta comissionáveis

Exemplo de uma notificação de meia página do Android
Figura 1: exemplo de uma notificação de meia tela do Android

Por padrão, o Google Play services no Android usa notificações de "meia página" que cobrem a metade inferior da tela de um dispositivo móvel para indicar aos usuários que há dispositivos Matter por perto que geram comissão.

Para evitar interrupções enquanto o app está em primeiro plano, você pode suprimir essas notificações chamando o método suppressHalfSheetNotification(). Consulte a documentação da API para mais informações.

A supressão ativada por essa API expira se o app ficar em primeiro plano por mais de 15 minutos. Para reativar a supressão após um tempo limite, chame suppressHalfSheetNotification() novamente. Caso contrário, as notificações de meia página vão começar a aparecer.

Como compartilhar dispositivos Matter no tecido com o Google?

O Google recomenda usar a API Commissioning como principal meio de compartilhar um dispositivo já configurado na sua própria estrutura com a estrutura do Google. A API Share tem limitações e deve ser reservada para outros casos de uso.

Por que usar a API Commissioning em vez da API Share?

Com a API Commissioning, é possível acionar o compartilhamento de um dispositivo diretamente com a estrutura do Google, que é o método preferido quando viável. Com a API Share, mais etapas são necessárias para o usuário final. Por exemplo, o usuário final precisa ter o GHA instalado e saber selecionar GHA durante o processo para garantir o sucesso.

Para usar a API Commissioning, abra a janela de provisionamento e chame a API Commissioning, conforme descrito em Como usar a API Commissioning como o comissário secundário do Matter.

Quando usar a API Share?

Use a API Share para permitir que o usuário final escolha um aplicativo qualificado para compartilhar um dispositivo de forma genérica com outros ecossistemas Matter.