API Commissioning su Android

L'API Commissioning consente a un'app di commissionare:

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

Modi per effettuare la messa in servizio dei dispositivi Matter

Il processo di messa in servizio può essere avviato:

Richiedi la messa in servizio 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 richiedere la messa in servizio:

  1. Inizializza un ActivityResultLauncher nella tua attività. Se l'utente ha commissionato il dispositivo sul fabric Google, il risultato potrebbe includere il nome assegnato dall'utente 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 del payload ricevuti, e imposta l'opzione per mettere in funzione il dispositivo nel fabric 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 sia al fabric Google sia al tuo, imposta il servizio di commissionamento con setCommissioningService in 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 l'intent sender, avvia il sender:

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

Per più fabric (multi-amministratore)

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

Punto di accesso per la configurazione di Matter per l'accoppiamento rapido o la scansione di codici QR (solo Android)

La richiesta di commissionamento tramite l'accoppiamento rapido o il codice QR su Android può essere eseguita in due modi:

Per singoli tessuti

Utilizza il filtro per intent ACTION_START_COMMISSIONING per fornire funzionalità di commissione complete per un'app senza bisogno di GHA. Quando viene commissionato al fabric Google, questo include la possibilità per l'utente di assegnare un nome al dispositivo.

Flusso di messa in servizio tramite ACTION_START_COMMISSIONING
Figura 1: flusso di commissione utilizzando ACTION_START_COMMISSIONING

Per indicare il supporto per la messa in servizio del fabric Google, aggiungi quanto segue intent-filter alla dichiarazione dell'attività scelta all'interno del 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 è tra quelle suggerite, viene visualizzata nell'opzione Scegli un'altra app.

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

Per più fabric (multi-amministratore)

Puoi anche utilizzare il flusso di accoppiamento rapido in scenari con più amministratori. Per saperne di più, consulta Multi-amministrazione per l'API Commissioning su Android.

Gestisci l'intent in arrivo

Una volta avviata l'attività, deve verificare l'esistenza dell'intent ACTION_START_COMMISSIONING 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
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 la messa in servizio deve essere interrotta.

Elimina le notifiche di scoperta commissionabili

Esempio di notifica di un halfsheet Android
Figura 1: esempio di notifica di un foglio di mezza pagina Android

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

Per evitare interruzioni mentre l'app è in primo piano, puoi disattivare queste notifiche chiamando il metodo suppressHalfSheetNotification(). Per saperne di più, consulta la documentazione dell'API.

La soppressione attivata da questa API scade se l'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 della scheda.

Come condividere con Google i dispositivi Matter sul tuo fabric?

Google consiglia vivamente di utilizzare l'API Commissioning come mezzo principale per condividere un dispositivo che hai già configurato sul tuo fabric con il fabric di Google. L'API Share presenta 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 il fabric di 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 dover selezionare GHA durante la procedura per garantire il successo.

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

Quando dovresti 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.