API de comissionamento no Android

A API Commissioning permite que um app seja comissionado para:

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

Indicar suporte para a ativação do Matter

Se você estiver usando a Google Home Mobile SDK para comissionamento, é necessário adicionar o nome do pacote do app no Google Home Developer Console, implementar nossas APIs Matter e indicar que o app oferece suporte à comissionamento Matter processando a intent ACTION_COMMISSION_DEVICE.

Adicione o intent-filter abaixo à declaração application no arquivo AndroidManifest.xml:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

Consulte o manifesto do app de exemplo para referência.

Formas de comissionar dispositivos Matter

O processo de comissionamento pode ser iniciado:

• Diretamente no seu app
• Com o pareamento rápido no Android.

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

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
• Para vários tecidos

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.

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 Multi-admin for Commissioning 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

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() no Mobile SDK. 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.

Uma implementação dessa API pode ser encontrada no Google Home Sample App for Matter. Consulte HalfSheetSuppressionObserver.kt para mais informações.

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.