Creare riquadri delle Impostazioni rapide personalizzati per la tua app

Le Impostazioni rapide sono riquadri visualizzati nel riquadro Impostazioni rapide, che rappresentano azioni che gli utenti possono toccare per completare rapidamente attività ricorrenti. La tua app può fornire un riquadro personalizzato agli utenti tramite la classe TileService e utilizzare un oggetto Tile per monitorare lo stato del riquadro. Ad esempio, potresti creare un riquadro che consenta agli utenti di attivare o disattivare una VPN fornita dal tuo provider VPN.

Riquadro Impostazioni rapide con il riquadro della VPN attivato e disattivato
Figura 1. Pannello Impostazioni rapide con il riquadro della VPN attivato e disattivato.

Decidi quando creare un riquadro

Ti consigliamo di creare riquadri per funzionalità specifiche a cui prevedi che gli utenti accedano spesso o di cui hanno bisogno rapidamente (o entrambe le cose). I riquadri più efficaci sono quelli che soddisfano entrambe queste qualità, fornendo un accesso rapido alle azioni eseguite di frequente.

Ad esempio, potresti creare una scheda per un'app di fitness che consenta agli utenti di avviare rapidamente una sessione di allenamento. Tuttavia, non consigliamo di creare un riquadro per la stessa app che consenta agli utenti di esaminare l'intera cronologia degli allenamenti.

Casi d'uso dei riquadri delle app di fitness
Figura 2. Esempi di riquadri consigliati e non consigliati per un'app di fitness.

Per migliorare la rilevabilità e la facilità d'uso della tua scheda, ti consigliamo di evitare alcune pratiche:

  • Evita di utilizzare i riquadri per avviare un'app. Utilizza invece una scorciatoia per l'app o un Avvio app standard.

  • Evita di utilizzare i riquadri per azioni utente una tantum. Utilizza invece una scorciatoia per l'app o una notifica.

  • Evita di creare troppi riquadri. Consigliamo un massimo di due per app. Utilizza invece una scorciatoia per l'app.

  • Evita di utilizzare riquadri che mostrano informazioni, ma non sono interattivi per gli utenti. Utilizza invece una notifica o un widget.

Crea il tuo riquadro

Per creare una scheda, devi prima creare un'icona della scheda appropriata, quindi creare e dichiarare il tuo TileService nel file manifest dell'app.

L'esempio di Impostazioni rapide fornisce un esempio di come creare e gestire un riquadro.

Crea la tua icona personalizzata

Dovrai fornire un'icona personalizzata, che viene visualizzata nel riquadro Impostazioni rapide. (Aggiungerai questa icona quando dichiari TileService, descritto nella sezione successiva.) L'icona deve essere di colore bianco pieno con uno sfondo trasparente, misurare 24 x 24 dp ed essere sotto forma di VectorDrawable.

Esempio di un drawable vettoriale
Figura 3. Esempio di un drawable vettoriale.

Crea un'icona che suggerisca visivamente lo scopo del tuo riquadro. In questo modo, gli utenti possono identificare se il tuo riquadro è adatto alle loro esigenze. Ad esempio, potresti creare l'icona di un cronometro per un riquadro di un'app di fitness che consente agli utenti di avviare una sessione di allenamento.

Crea e dichiara il tuo TileService

Crea un servizio per la tua scheda che estenda la classe TileService.

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}

Dichiara il tuo TileService nel file manifest dell'app. Aggiungi il nome e l'etichetta del tuo TileService (fino a 18 caratteri per android:label), l'icona personalizzata che hai creato nella sezione precedente e l'autorizzazione appropriata.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

Gestisci TileService

Dopo aver creato e dichiarato TileService nel file manifest dell'app, devi gestirne lo stato.

TileService è un servizio associato. Il tuo TileService viene associato quando richiesto dalla tua app o se il sistema deve comunicare con l'app. Un tipico ciclo di vita di un servizio associato contiene i seguenti quattro metodi di callback: onCreate(), onBind(), onUnbind() e onDestroy(). Questi metodi vengono richiamati dal sistema ogni volta che il servizio entra in una nuova fase del ciclo di vita.

Panoramica del ciclo di vita di TileService

Oltre ai callback che controllano il ciclo di vita del servizio associato, devi implementare altri metodi specifici per il ciclo di vita di TileService. Questi metodi possono essere chiamati al di fuori di onCreate() e onDestroy() perché i metodi del ciclo di vita di Service e i metodi del ciclo di vita di TileService vengono chiamati in due thread asincroni separati.

Il ciclo di vita di TileService contiene i seguenti metodi, che vengono richiamati dal sistema ogni volta che TileService entra in una nuova fase del ciclo di vita:

  • onTileAdded(): questo metodo viene chiamato solo quando l'utente aggiunge il tuo tile per la prima volta e se l'utente lo rimuove e lo aggiunge di nuovo. Questo è il momento migliore per eseguire l'inizializzazione una tantum. Tuttavia, questo potrebbe non soddisfare tutte le inizializzazioni necessarie.

  • onStartListening() e onStopListening(): questi metodi vengono chiamati ogni volta che l'app aggiorna il riquadro e vengono chiamati spesso. TileService rimane associato tra onStartListening() e onStopListening(), consentendo alla tua app di modificare il riquadro e di eseguire il push degli aggiornamenti.

  • onTileRemoved(): questo metodo viene chiamato solo se l'utente rimuove il tuo riquadro.

Seleziona una modalità di ascolto

TileService ascolta in modalità attiva o non attiva. Ti consigliamo di utilizzare la modalità attiva, che dovrai dichiarare nel manifest dell'app. In caso contrario, TileService è la modalità standard e non deve essere dichiarata.

Non dare per scontato che TileService esisterà al di fuori della coppia di metodi onStartListening() e onStopListening().

Utilizza la modalità attiva per un TileService che ascolta e monitora il proprio stato nel proprio processo. Un TileService in modalità attiva è associato a onTileAdded(), onTileRemoved(), eventi di tocco e quando richiesto dal processo dell'app.

Ti consigliamo di utilizzare la modalità attiva se il tuo TileService riceve una notifica quando lo stato del riquadro deve essere aggiornato dal suo processo. I riquadri attivi limitano il carico sul sistema perché non devono essere associati ogni volta che il riquadro Impostazioni rapide diventa visibile all'utente.

È possibile chiamare il metodo statico TileService.requestListeningState() per richiedere l'avvio dello stato di ascolto e ricevere un callback a onStartListening().

Puoi dichiarare la modalità attiva aggiungendo META_DATA_ACTIVE_TILE al file manifest dell'app.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

Modalità non attiva

La modalità non attiva è la modalità standard. Un TileService è in modalità non attiva se è associato ogni volta che il tuo riquadro è visibile all'utente. Ciò significa che il tuo TileService potrebbe essere creato e associato di nuovo in momenti che non dipendono dal suo controllo. Inoltre, potrebbe essere scollegato ed eliminato quando l'utente non visualizza il riquadro.

La tua app riceve un callback a onStartListening() dopo che l'utente apre il riquadro Impostazioni rapide. Puoi aggiornare l'oggetto Tile tutte le volte che vuoi tra onStartListening() e onStopListening().

Non è necessario dichiarare la modalità non attiva: non aggiungere META_DATA_ACTIVE_TILE al file manifest dell'app.

Panoramica degli stati dei riquadri

Dopo che un utente aggiunge il tuo riquadro, questo si trova sempre in uno dei seguenti stati.

  • STATE_ACTIVE: indica uno stato attivo o abilitato. In questo stato, l'utente può interagire con il tuo riquadro.

    Ad esempio, per un riquadro di un'app di fitness che consente agli utenti di avviare una sessione di allenamento a tempo, STATE_ACTIVE indica che l'utente ha avviato una sessione di allenamento e il timer è in esecuzione.

  • STATE_INACTIVE: indica uno stato di disattivazione o pausa. In questo stato, l'utente può interagire con il tuo riquadro.

    Per utilizzare di nuovo l'esempio della scheda dell'app di fitness, una scheda in STATE_INACTIVE indica che l'utente non ha avviato una sessione di allenamento, ma potrebbe farlo se lo desidera.

  • STATE_UNAVAILABLE: indica uno stato di non disponibilità temporanea. L'utente non può interagire con il tuo riquadro mentre si trova in questo stato.

    Ad esempio, un riquadro in STATE_UNAVAILABLE indica che al momento non è disponibile per l'utente per qualche motivo.

Il sistema imposta solo lo stato iniziale dell'oggetto Tile. Puoi impostare lo stato dell'oggetto Tile per il resto del suo ciclo di vita.

Il sistema potrebbe colorare l'icona e lo sfondo della scheda per riflettere lo stato dell'oggetto Tile. Gli oggetti Tile impostati su STATE_ACTIVE sono i più scuri, mentre STATE_INACTIVE e STATE_UNAVAILABLE sono sempre più chiari. La tonalità esatta è specifica del produttore e della versione.

Riquadro VPN colorato per riflettere gli stati degli oggetti
Figura 4. Esempi di un riquadro colorato per riflettere lo stato del riquadro (rispettivamente attivo, non attivo e non disponibile).

Aggiorna il riquadro

Puoi aggiornare il riquadro una volta ricevuta una chiamata di richiamata al numero onStartListening(). A seconda della modalità del riquadro, quest'ultimo può essere aggiornato almeno una volta fino alla ricezione di un callback a onStopListening().

In modalità attiva, puoi aggiornare il riquadro esattamente una volta prima di ricevere un callback a onStopListening(). In modalità non attiva, puoi aggiornare il riquadro tutte le volte che vuoi tra le ore onStartListening() e le ore onStopListening().

Puoi recuperare l'oggetto Tile chiamando getQsTile(). Per aggiornare campi specifici dell'oggetto Tile, chiama i seguenti metodi:

Devi chiamare updateTile() per aggiornare il riquadro dopo aver impostato i campi dell'oggetto Tile sui valori corretti. In questo modo, il sistema analizzerà i dati aggiornati del riquadro e aggiornerà la UI.

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}

Gestisci i tocchi

Gli utenti possono toccare la tua scheda per attivare un'azione se la scheda è in STATE_ACTIVE o STATE_INACTIVE. Il sistema richiama quindi il callback onClick() della tua app.

Una volta che l'app riceve un callback a onClick(), può avviare una finestra di dialogo o un'attività, attivare un lavoro in background o modificare lo stato del riquadro.

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}

Avvia una finestra di dialogo

showDialog() comprime il riquadro Impostazioni rapide e mostra una finestra di dialogo. Utilizza una finestra di dialogo per aggiungere contesto alla tua azione se richiede un input aggiuntivo o il consenso dell'utente.

Avvia un'attività

startActivityAndCollapse() avvia un'attività comprimendo il riquadro. Le attività sono utili se ci sono informazioni più dettagliate da mostrare rispetto a una finestra di dialogo o se l'azione è altamente interattiva.

Se la tua app richiede un'interazione significativa con l'utente, deve avviare un'attività solo come ultima risorsa. In alternativa, valuta la possibilità di utilizzare una finestra di dialogo o un pulsante di attivazione/disattivazione.

Se l'utente tocca e tiene premuto un riquadro, viene visualizzata la schermata Informazioni app. Per eseguire l'override di questo comportamento e avviare un'attività per l'impostazione delle preferenze, aggiungi un <intent-filter> a una delle tue attività con ACTION_QS_TILE_PREFERENCES.

A partire dall'API Android 28, l'elemento PendingIntent deve avere l'elemento Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}

In alternativa, puoi aggiungere il flag in AndroidManifest.xml nella sezione Activity specifica.

Contrassegna il riquadro come attivabile/disattivabile

Ti consigliamo di contrassegnare la scheda come attivabile/disattivabile se funziona principalmente come un interruttore a due stati (che è il comportamento più comune delle schede). In questo modo, il sistema operativo riceve informazioni sul comportamento del riquadro e l'accessibilità complessiva migliora.

Imposta i metadati TOGGLEABLE_TILE su true per contrassegnare il riquadro come attivabile/disattivabile.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Eseguire solo azioni sicure su dispositivi bloccati in modo sicuro

La tua scheda potrebbe essere visualizzata sopra la schermata di blocco sui dispositivi bloccati. Se il riquadro contiene informazioni sensibili, controlla il valore di isSecure() per determinare se il dispositivo è in uno stato sicuro e il tuo TileService deve modificare il suo comportamento di conseguenza.

Se l'azione della scheda è sicura da eseguire mentre il dispositivo è bloccato, utilizza startActivity() per avviare un'attività sopra la schermata di blocco.

Se l'azione del riquadro non è sicura, utilizza unlockAndRun() per chiedere all'utente di sbloccare il dispositivo. In caso di esito positivo, il sistema esegue l'oggetto Runnable che passi a questo metodo.

Categorizza il tuo riquadro

Per migliorare l'esperienza utente nelle Impostazioni rapide, puoi classificare il tuo riquadro. Il sistema organizza i riquadri in categorie come Connettività, Display e Privacy. Il sistema utilizza queste categorie per ordinare e raggruppare i riquadri nella modalità di modifica delle Impostazioni rapide, in modo che gli utenti possano trovarli e gestirli più facilmente.

Implementazione

Per specificare una categoria per TileService, aggiungi un campo di metadati alla dichiarazione del servizio nel file AndroidManifest.xml:

  • Nel file AndroidManifest.xml, all'interno dell'elemento <service> per il tuo TileService, aggiungi un elemento <meta-data>.
  • android:name: imposta questo valore su android.service.quicksettings.TILE_CATEGORY.
  • android:value: assegna una delle costanti di categoria predefinite, ad esempio android.service.quicksettings.CATEGORY_CONNECTIVITY o android.service.quicksettings.CATEGORY_DISPLAY.

Come mostrato nell'esempio seguente:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

L'API fornisce un insieme di categorie predefinite tra cui scegliere. Queste categorie sono definite come costanti di stringa all'interno della classe TileService.

Se non viene specificata una categoria, il sistema assegna automaticamente una categoria predefinita:

  • Dalle app di sistema: per i riquadri che fanno parte di un'applicazione di sistema.
  • Dalle app che hai installato: per i riquadri delle applicazioni installate dall'utente.

Sebbene i dispositivi Google Pixel utilizzino le categorie nelle Impostazioni rapide, gli OEM possono utilizzare o ignorare queste informazioni sulle categorie nelle rispettive UI di sistema.

Chiedi all'utente di aggiungere la tua scheda

Per aggiungere manualmente la tua scheda, gli utenti devono seguire diversi passaggi:

  1. Scorri verso il basso per aprire il riquadro Impostazioni rapide.
  2. Tocca il pulsante Modifica.
  3. Scorrere tutti i riquadri sul dispositivo fino a trovare il tuo.
  4. Tieni premuto il riquadro e trascinalo nell'elenco dei riquadri attivi.

L'utente può anche spostare o rimuovere la tua scheda in qualsiasi momento.

A partire da Android 13, puoi utilizzare il metodo requestAddTileService() per consentire agli utenti di aggiungere più facilmente la tua scheda a un dispositivo. Questo metodo mostra agli utenti una richiesta per aggiungere rapidamente la tua scheda direttamente al riquadro Impostazioni rapide. Il prompt include il nome dell'applicazione, l'etichetta fornita e l'icona.

Prompt dell'API Quick Settings Placement
Figura 5. Prompt dell'API Quick Settings Placement.
public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Il callback contiene informazioni sull'aggiunta o meno della scheda, se era già presente o se si è verificato un errore.

Usa la tua discrezione per decidere quando e con quale frequenza mostrare i prompt agli utenti. Ti consigliamo di chiamare requestAddTileService() solo nel contesto, ad esempio quando l'utente interagisce per la prima volta con una funzionalità facilitata dalla tua scheda.

Il sistema può scegliere di interrompere l'elaborazione delle richieste per un determinato ComponentName se l'utente le ha rifiutate un numero sufficiente di volte in precedenza. L'utente viene determinato dal Context utilizzato per recuperare questo servizio: deve corrispondere all'utente corrente.