API de comissionamento no Android

Observação: se a API Commissioning não for usada no Android, os usuários ainda poderão comissionar dispositivos Matter usando o Google Home app (GHA).

A API Commissioning permite que um app seja comissionado para:

  • Seu fabric e o do Google.
  • Somente o fabric do Google.

Formas de comissionar dispositivos Matter

O processo de comissionamento pode ser iniciado:

Solicitar a ativação 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 a ativação:

  1. Inicialize um ActivityResultLauncher na sua atividade. Se o usuário comissionou o dispositivo no Google Fabric, o resultado poderá 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 uma CommissioningRequest, incluindo os dados de payload recebidos, e defina a opção para comissionar o dispositivo ao Google Fabric 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 fabric do Google e para o seu próprio fabric, defina o serviço de comissionamento com setCommissioningService no CommissioningRequest.

  3. Use a instância CommissioningClient para iniciar a 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. Quando 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 fabrics (multiadmin)

Se você precisar configurar vários tecidos Matter em um dispositivo, consulte Multi-admin for Commissioning API no Android.

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

É possível solicitar a ativação por meio do Pareamento rápido ou do QR code no Android de duas maneiras:

Para tecidos únicos

Use o filtro de intent ACTION_START_COMMISSIONING para fornecer o recurso de comissionamento completo 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 à ativação do Google Fabric, 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 de comissionamento. Se o app não estiver entre os sugeridos, ele vai aparecer na opção Escolher outro app.

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

Para vários fabrics (multiadmin)

Você também pode usar o fluxo FastPair em cenários com vários administradores. Para mais informações, consulte API de vários administradores para comissionamento no Android.

Processar a intent recebida

Quando a atividade for iniciada, ela vai verificar a intent ACTION_START_COMMISSIONING existente e extrair 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

Um valor de payload que não é null indica que o usuário já leu o código QR do dispositivo ou inseriu a chave de pareamento. Um valor de payload null não significa que a comissionamento precisa ser abortado.

Suprimir notificações de descobertas que podem gerar comissão

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

Por padrão, o Google Play services no Android usa notificações "half-sheet" que cobrem a metade inferior da tela de um dispositivo móvel para indicar aos usuários que dispositivos Matter comissionáveis estão por perto.

Para evitar interrupções enquanto o app está em primeiro plano, suprima 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 vai expirar 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 você deve compartilhar dispositivos Matter no seu fabric com o Google?

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

Por que você deve usar a API Commissioning em vez da API Share?

A API Commissioning permite acionar o compartilhamento de um dispositivo diretamente com o fabric 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 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 comissionamento secundário do Matter.

Quando usar a API Share?

É possível 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 ecossistemas Matter.