A API Commissioning permite que um app faça o provisionamento para:
- Seu tecido e o tecido do Google.
- Apenas o tecido do Google.
Como comissionar dispositivos Matter
O processo de comissionamento pode ser iniciado:
Solicitar o provisionamento diretamente no seu 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 uma comissão:
Inicialize um
ActivityResultLauncher
na sua atividade. Se o usuário tiver comissionado o dispositivo no tecido do Google, o resultado poderá incluir o nome atribuído ao dispositivo no momento do 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") } }
Construa um
CommissioningRequest
, incluindo os dados de payload recebidos, e defina a opção para comissionar o dispositivo para a estrutura do Google, usandosetStoreToGoogleFabric
: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, defina o serviço de comissionamento com
setCommissioningService
noCommissioningRequest
.Use a instância
CommissioningClient
para iniciar o provisionamento: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
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 estruturas (multiadministrador)
Se você precisar configurar várias estruturas Matter em um dispositivo, consulte Multiadministrador para API Commissioning no Android.
Ponto de entrada de provisionamento do Matter para Pareamento rápido ou leitura de QR code (apenas no Android)
A solicitação de provisionamento 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 total de comissionamento a um app sem precisar
do GHA. Ao comissionar para a estrutura do Google, isso
inclui permitir que o usuário atribua um nome ao dispositivo.

ACTION_START_COMMISSIONING
Para indicar suporte ao provisionamento de tecido do Google, adicione o seguinte
intent-filter
à declaração de atividade escolhida no seu
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 for um dos 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 um
intent
ACTION_START_COMMISSIONING
.
Para várias estruturas (multiadministrador)
Também é possível usar o fluxo do FastPair em cenários com vários administradores. Para mais informações, consulte Multiadministrador para a API Commissioning no Android.
Processar a intent recebida
Depois que a atividade for iniciada, ela vai verificar o intent
ACTION_START_COMMISSIONING
e recuperar a carga útil:
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 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 provisionamento deve ser cancelado.
Suprimir notificações de descoberta comissionáveis

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 indicar aos usuários que há dispositivos Matter por perto que geram comissão.
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 ficar 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 no tecido com o Google?
O Google recomenda usar a API Commissioning como principal meio de compartilhar um dispositivo já configurado na sua própria estrutura com a estrutura do Google. A API Share tem limitações e deve ser reservada para outros casos de uso.
Por que usar a API Commissioning em vez da API Share?
Com a API Commissioning, é possível acionar o compartilhamento de um dispositivo diretamente com a estrutura 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 o GHA instalado e saber selecionar GHA durante o processo para garantir o sucesso.
Para usar a API Commissioning, abra a janela de provisionamento e chame a API Commissioning, 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 Matter.