API Commissioning

L'API Commissioning consente a un'app di eseguire la messa in servizio per:

• La tua infrastruttura e quella di Google.
• Solo il tessuto Google.

Indicare il supporto per la messa in servizio Matter

Se utilizzi il Google Home Mobile SDK per la messa in servizio, devi aggiungere il nome del pacchetto dell'app in Google Home Developer Console, implementare le nostre API Matter e indicare che la tua app supporta la messa in servizio Matter gestire l'intent ACTION_COMMISSION_DEVICE.

Aggiungi il seguente intent-filter alla dichiarazione application all'interno del AndroidManifest.xml file:

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

Consulta il manifest dell'app di esempio come riferimento.

Modalità di 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.

Richiedi la messa in servizio direttamente nella tua 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 singoli tessuti

Per richiedere la messa in servizio:

1. Inizializza un ActivityResultLauncher nella tua attività. Se l'utente ha eseguito la messa in servizio del dispositivo nel cloud Google, il risultato potrebbe includere il nome assegnato dall'utente al dispositivo durante la messa in servizio.

   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. Costruisci un messaggio CommissioningRequest, includi i dati del payload ricevuti e imposta l'opzione percommissionare il dispositivo al fabric di Google 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 tuo impianto di produzione e a quello di Google, imposta il servizio di messa in servizio con setCommissioningService nel CommissioningRequest.

3. Utilizza l'istanza CommissioningClient per avviare la messa in servizio:

   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ù cloud (multi-admin)

Se devi configurare più fabric Matter su un dispositivo, consulta Come utilizzare le API di messa in servizio in modalità multi-amministratore.

Punto di contatto per la messa in servizio di Matter per l'accoppiamento rapido o la scansione del codice QR (solo Android)

La richiesta di messa in servizio tramite accoppiamento rapido o codice QR su Android può essere eseguita in due modi:

• Per singoli tessuti
• Per più tessuti

Per singoli tessuti

Utilizza il filtro intent ACTION_START_COMMISSIONING per fornire la funzionalità di messa in servizio completa di un'app senza dover utilizzare GHA. Durante la messa in servizio della struttura di Google, questo include la possibilità per l'utente di assegnare un nome al dispositivo.

Per indicare il supporto per la messa in servizio della piattaforma Google, aggiungi il seguente intent-filter alla dichiarazione dell'attività scelta all'interno del AndroidManifest.xml file:

<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 di app Matter suggerite nel selettore di app delle API di 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 intento ACTION_START_COMMISSIONING.

Per più cloud (multi-admin)

Puoi anche utilizzare il flusso di accoppiamento rapido in scenari con più amministratori. Per ulteriori informazioni, consulta Come utilizzare le API di messa in servizio in modalità multi-amministratore.

Gestire l'intent in arrivo

Una volta lanciata, l'attività dovrebbe verificare l'intentACTION_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 indica che la messa in servizio deve essere interrotta.

Eliminare le notifiche relative alle scoperte idonee per la commissione

Per impostazione predefinita, Google Play services su Android utilizza notifiche "half-sheet" che coprono la metà inferiore dello schermo di un dispositivo mobile per fornire agli utenti un'indicazione proattiva della presenza di dispositiviMatter commissionabili nelle vicinanze.

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

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

Un'implementazione di questa API è disponibile in Google Home Sample App for Matter. Per maggiori informazioni, visita la pagina HalfSheetSuppressionObserver.kt.

Come dovresti condividere i dispositivi Matter della tua piattaforma con Google?

Google consiglia vivamente di utilizzare l'API Commissioning come metodo principale per condividere un dispositivo che hai già configurato nel tuo proprio cloud con il cloud di Google. L'API Share ha delle limitazioni e deve essere riservata ad altri casi d'uso.

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

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

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

Quando utilizzare l'API Share?

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