API de comissionamento no Android

A API Commissioning permite que um app comissione para:

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

Maneiras de comissionar dispositivos Matter

O processo de comissionamento pode ser iniciado:

Solicitar o comissionamento diretamente no app

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

Para tecidos únicos

Para solicitar o comissionamento:

  1. Inicialize um ActivityResultLauncher na sua atividade. Se o usuário comissionou o dispositivo no tecido do Google, o resultado poderá incluir o nome atribuído ao dispositivo durante o 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 de comissionar o dispositivo para o tecido 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 tecido, defina o serviço de comissionamento com setCommissioningService em CommissioningRequest.

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

    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ários tecidos (vários administradores)

Se você precisar configurar vários tecidos Matter em um dispositivo, consulte Vários administradores para a API Commissioning no Android.

Ponto de entrada de comissionamento do Matter para Pareamento rápido ou leitura de QR code (somente Android)

A solicitação de comissionamento 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 de comissionamento completa para um app sem precisar do GHA. Ao comissionar para o tecido 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 comissionamento usando ACTION_START_COMMISSIONING

Para indicar suporte ao comissionamento de tecido do Google, adicione o seguinte intent-filter à declaração de atividade escolhida no 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 Commissioning. Se o app não for um dos sugeridos, ele vai aparecer na opção Escolher outro app.

Depois que o usuário selecionar seu app, ele será iniciado e direcionado para a atividade escolhida com uma intent.ACTION_START_COMMISSIONING

Para vários tecidos (vários administradores)

Você também pode usar o fluxo do Pareamento rápido em cenários de vários administradores. Para mais informações, consulte Vários administradores para a API Commissioning no Android.

Processar a intent recebida

Depois que a atividade for iniciada, ela precisará verificar a intent ACTION_START_COMMISSIONING e recuperar o payload:

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)
}

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 comissionamento precisa ser interrompido.

Suprimir notificações de descoberta comissionável

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, Google Play services no Android usa notificações de meia tela que cobrem a metade inferior da tela de um dispositivo móvel para indicar aos usuários que há dispositivos Matter comissionáveis por perto.

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

A supressão ativada por essa API expira se o app estiver 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 tela vão começar a aparecer.

Como compartilhar dispositivos Matter no seu tecido com o Google?

O Google recomenda que você use a API Commissioning como o principal meio de compartilhar um dispositivo que já foi configurado no seu próprio tecido com o tecido do Google. A API Share tem limitações e precisa ser reservada para outros casos de uso.

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

A API Commissioning permite acionar o compartilhamento de um dispositivo diretamente com o tecido 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 GHA instalado e saber como selecionar GHA durante o processo para garantir o sucesso.

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

Quando usar a API Share?

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