API de comissionamento

A API Commissioning permite que um app seja comissionado para:

  • Seu fabric e o fabric 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 ao 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:

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 ao fazer a encomenda.

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

Se você precisar configurar vários tecidos Matter em um dispositivo, consulte Como usar APIs de comissionamento no modo multiadministrador.

Ponto de entrada de comissionamento do Matter para o Fast Pair 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 fabric do Google, 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 (vários administradores)

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

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á fez a leitura do 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() 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 a 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 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 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.

Anterior
Solução de problemas
Próxima
Vários administradores