API Commissioning su Android

L'API Commissioning consente a un'app di eseguire il provisioning su:

• Il tuo tessuto e il tessuto Google.
• Solo il tessuto Google.

Modi per effettuare la messa in servizio dei dispositivi Matter

La procedura di messa in servizio può essere avviata:

• Direttamente nella tua app
• Tramite l'accoppiamento rapido su Android.

Richiedere la commissione direttamente nell'app

La richiesta di messa in servizio direttamente nell'app può essere attivata da un pulsante nell'app e può essere eseguita in due modi:

• Per singoli tessuti
• Per più tessuti

Per tessuti singoli

Per richiedere la commissione:

1. Inizializza un ActivityResultLauncher nella tua attività. Se l'utente ha commissionato il dispositivo sul tessuto Google, il risultato potrebbe includere il nome che l'utente ha assegnato al dispositivo al momento della commissione.

   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. Crea un CommissioningRequest, inclusi i dati utili ricevuti, e imposta l'opzione per commissionare il dispositivo a Google Fabric, utilizzando setStoreToGoogleFabric:

   val commissioningRequest = CommissioningRequest.builder()
           .setOnboardingPayload(payload)
           .setStoreToGoogleFabric(true)
     // set all other options that you care about
           .build()
   

   Se vuoi commissionare il dispositivo al tessuto Google e al tuo tessuto, imposta il servizio di commissione con setCommissioningService in CommissioningRequest.

3. Utilizza l'istanza CommissioningClient per iniziare il commissioning:

   commissioningClient
     .commissionDevice(commissioningRequest)
     .addOnSuccessListener { result ->
       Log.i("CommissioningActivity", "Commissioning success")
   _commissioningIntentSender.postValue(result)
         }
         .addOnFailureListener { error ->
           Log.i("CommissioningActivity", "Commissioning failed")
     }
   

   Dove _commissioningIntentSender è definito come:

   private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
       val commissioningIntentSender: LiveData<IntentSender?>
       get() = _commissioningIntentSender
   

4. Una volta che CommissioningClient restituisce il mittente dell'intent, avvialo:

   commissioningIntentSender.observe(this) { sender ->
     if (sender != null) {
       commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
     }
   }
   

Per più tessuti (più amministratori)

Se devi configurare più tessuti Matter su un dispositivo, consulta Multi-admin per l'API Commissioning su Android.

Punto di ingresso del commissioning di Matter per l'accoppiamento rapido o la scansione del codice QR (solo Android)

La richiesta di commissioning tramite Accoppiamento rapido o codice QR su Android può essere effettuata in due modi:

• Per singoli tessuti
• Per più tessuti

Per tessuti singoli

Utilizza il filtro per intent ACTION_START_COMMISSIONING per fornire funzionalità di configurazione complete per un'app senza bisogno di GHA. Quando viene eseguito il provisioning su Google, ciò include la possibilità per l'utente di assegnare un nome al dispositivo.

Per indicare il supporto del provisioning di Google Fabric, aggiungi il seguente intent-filter alla dichiarazione di attività scelta all'interno del tuo file 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>

intent-filter viene utilizzato per includere la tua app nell'elenco delle app Matter suggerite nel selettore di app delle API Commissioning. Se la tua app non è una delle app suggerite, viene visualizzata nell'opzione Scegli un'altra app.

Una volta selezionata la tua app, questa viene avviata e indirizzata all'attività scelta con un intent ACTION_START_COMMISSIONING.

Per più tessuti (più amministratori)

Puoi anche utilizzare il flusso Fast Pair in scenari con più amministratori. Per ulteriori informazioni, consulta la pagina Multi-admin per l'API Commissioning su Android.

Gestire l'intent in entrata

Una volta avviata l'attività, deve verificare l'intent ACTION_START_COMMISSIONING esistente e recuperare il 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)
}

Un valore del payload diverso da null indica che l'utente ha già scansionato il codice QR del dispositivo o inserito la chiave di accoppiamento. Un valore del payload null non significa che il provisioning deve essere interrotto.

Disattivare le notifiche di scoperta commissionabili

Per impostazione predefinita, Google Play services su Android utilizza notifiche "a metà foglio" che coprono la metà inferiore dello schermo di un dispositivo mobile per fornire agli utenti un'indicazione proattiva che i dispositivi Matter commissionabili si trovano nelle vicinanze.

Per evitare interruzioni mentre l'app è in primo piano, puoi eliminare queste notifiche chiamando il metodo suppressHalfSheetNotification(). Per ulteriori informazioni, consulta la documentazione dell'API.

La soppressione abilitata da questa API scade se la tua app è in primo piano per più di 15 minuti. Per riattivare la soppressione dopo un timeout, chiama di nuovo suppressHalfSheetNotification(), altrimenti inizieranno a essere visualizzate le notifiche a metà foglio.

Come condividere i dispositivi Matter sul tuo tessuto con Google?

Google consiglia vivamente di utilizzare l'API Commissioning come mezzo principale per condividere un dispositivo che hai già configurato nel tuo tessuto con il tessuto Google. L'API Share ha i suoi limiti e deve essere riservata ad altri casi d'uso.

Perché dovresti utilizzare l'API Commissioning anziché l'API Share?

L'API Commissioning consente di attivare la condivisione di un dispositivo direttamente con il tessuto Google, che è il metodo preferito quando è possibile. Con l'API Share, l'utente finale deve eseguire più passaggi. Ad esempio, l'utente finale deve avere installato GHA e deve sapere di selezionare GHA durante la procedura per garantire la riuscita.

Per utilizzare l'API Commissioning, devi aprire la finestra di commissioning e chiamare l'API Commissioning, come descritto in Come utilizzare l'API Commissioning come commissario Matter secondario.

Quando devi utilizzare l'API Share?

Puoi utilizzare l'API Share per consentire all'utente finale di scegliere un'applicazione idonea per condividere un dispositivo in modo generico con altri ecosistemi Matter.