API de comissionamento no Android

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

  • Seu tecido e o tecido do Google.
  • Somente a malha do Google.

Formas 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 no app e pode ser 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 na estrutura do Google, o resultado pode incluir o nome que o usuário atribuiu ao dispositivo quando o comissionou.

    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. Crie um CommissioningRequest, incluindo os dados de payload recebidos, e defina a opção para comissionar o dispositivo no fabric 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 Google Fabric e para seu próprio fabric, defina o serviço de comissionamento com setCommissioningService no 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árias redes (vários administradores)

Se você precisar configurar vários fabrics do Matter em um dispositivo, consulte Multiadministrador 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 meio de 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 fornecer capacidade total de comissionamento para um app sem precisar do GHA. Ao comissionar para o Google Fabric, isso inclui permitir que o usuário atribua um nome ao dispositivo.

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

Para indicar suporte ao comissionamento de fabric 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 estiver entre os 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 uma intent ACTION_START_COMMISSIONING.

Para vários fabrics (multiadministrador)

Também é possível usar o fluxo de Pareamento rápido em cenários de vários administradores. Para mais informações, consulte API Multi-admin for Commissioning no Android.

Processar a intent recebida

Depois que a atividade for iniciada, ela vai precisar verificar a intent ACTION_START_COMMISSIONING atual 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 é 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 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 página 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 fornecer aos usuários uma indicação proativa de que os dispositivos Matter comissionáveis estão por perto.

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 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 página vão começar a aparecer.

Como compartilhar dispositivos Matter na sua rede com o Google?

O Google recomenda que você use a API Commissioning como o principal meio de compartilhar um dispositivo que você já configurou na sua própria estrutura com a estrutura 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 Google Fabric, que é o método preferencial 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 que deve selecionar GHA durante o processo para garantir o sucesso.

Para usar a API Commissioning, abra a janela de comissionamento e chame a API, 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 do Matter.