Créer des blocs "Réglages rapides" personnalisés pour votre application

Les Réglages rapides sont des cartes affichées dans le panneau "Réglages rapides". Ils représentent des actions sur lesquelles les utilisateurs peuvent appuyer pour effectuer rapidement des tâches récurrentes. Votre application peut fournir un bloc personnalisé aux utilisateurs via la classe TileService et utiliser un objet Tile pour suivre l'état du bloc. Par exemple, vous pouvez créer un bloc permettant aux utilisateurs d'activer ou de désactiver un VPN fourni par votre application.

Panneau "Réglages rapides" avec le bloc VPN activé et désactivé
Figure 1. Panneau "Réglages rapides" avec le bloc VPN activé et désactivé.

Décider quand créer une vignette

Nous vous recommandons de créer des cartes pour des fonctionnalités spécifiques auxquelles les utilisateurs sont susceptibles d'accéder souvent ou d'avoir besoin d'accéder rapidement (ou les deux). Les cartes les plus efficaces sont celles qui combinent ces deux qualités, en offrant un accès rapide aux actions fréquemment effectuées.

Par exemple, vous pouvez créer une carte pour une application de fitness qui permettrait aux utilisateurs de démarrer rapidement une séance d'entraînement. Cependant, nous vous déconseillons de créer une carte pour la même application qui permettrait aux utilisateurs de consulter l'intégralité de l'historique de leurs entraînements.

Cas d'utilisation des cartes d'applications de fitness
Figure 2. Exemples de cartes recommandées et non recommandées pour une application de fitness.

Pour améliorer la visibilité et la facilité d'utilisation de votre carte, nous vous recommandons d'éviter certaines pratiques :

  • Évitez d'utiliser des cartes pour lancer une application. Utilisez plutôt un raccourci d'application ou un lanceur d'application standard.

  • Évitez d'utiliser des cartes pour des actions ponctuelles de l'utilisateur. Utilisez plutôt un raccourci d'application ou une notification.

  • Évitez de créer trop de tuiles. Nous vous recommandons d'en utiliser deux au maximum par application. Utilisez plutôt un raccourci d'application.

  • Évitez d'utiliser des cartes qui affichent des informations, mais qui ne sont pas interactives pour les utilisateurs. Utilisez plutôt une notification ou un widget.

Créer votre carte

Pour créer une carte, vous devez d'abord créer une icône de carte appropriée, puis créer et déclarer votre TileService dans le fichier manifeste de votre application.

L'exemple de réglages rapides montre comment créer et gérer un bloc.

Créer votre icône personnalisée

Vous devez fournir une icône personnalisée, qui s'affiche sur la tuile dans le panneau "Réglages rapides". (Vous ajouterez cette icône lors de la déclaration de TileService, décrite dans la section suivante.) L'icône doit être d'un blanc uni avec un arrière-plan transparent, mesurer 24 x 24 dp et se présenter sous la forme d'un VectorDrawable.

Exemple de drawable vectoriel
Figure 3. Exemple de drawable vectoriel.

Créez une icône qui indique visuellement l'objectif de votre carte. Cela aide les utilisateurs à déterminer si votre carte correspond à leurs besoins. Par exemple, vous pouvez créer une icône de chronomètre pour une carte d'une application de fitness qui permet aux utilisateurs de démarrer une séance d'entraînement.

Créer et déclarer votre TileService

Créez un service pour votre carte qui étend 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()
    }
}

Déclarez votre TileService dans le fichier manifeste de votre application. Ajoutez le nom et l'étiquette de votre TileService (jusqu'à 18 caractères pour android:label), l'icône personnalisée que vous avez créée dans la section précédente et l'autorisation appropriée.

 <!-- 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>

Gérer votre TileService

Une fois que vous avez créé et déclaré votre TileService dans le fichier manifeste de votre application, vous devez gérer son état.

TileService est un service lié. Votre TileService est lié lorsque votre application le demande ou si le système doit communiquer avec lui. Un cycle de vie de service lié standard contient les quatre méthodes de rappel suivantes : onCreate(), onBind(), onUnbind() et onDestroy(). Ces méthodes sont appelées par le système chaque fois que le service entre dans une nouvelle phase de cycle de vie.

Présentation du cycle de vie de TileService

En plus des rappels qui contrôlent le cycle de vie du service lié, vous devez implémenter d'autres méthodes spécifiques au cycle de vie de TileService. Ces méthodes peuvent être appelées en dehors de onCreate() et onDestroy(), car les méthodes de cycle de vie Service et TileService sont appelées dans deux threads asynchrones distincts.

Le cycle de vie de TileService contient les méthodes suivantes, qui sont appelées par le système chaque fois que votre TileService entre dans une nouvelle phase du cycle de vie :

  • onTileAdded() : cette méthode n'est appelée que lorsque l'utilisateur ajoute votre carte pour la première fois, et s'il la supprime et l'ajoute à nouveau. C'est le meilleur moment pour effectuer une initialisation unique. Toutefois, cela peut ne pas satisfaire toutes les initialisations nécessaires.

  • onStartListening() et onStopListening() : ces méthodes sont appelées chaque fois que votre application met à jour la carte, et elles sont appelées souvent. TileService reste lié entre onStartListening() et onStopListening(), ce qui permet à votre application de modifier la carte et de transmettre les mises à jour.

  • onTileRemoved() : cette méthode n'est appelée que si l'utilisateur supprime votre carte.

Sélectionnez un mode d'écoute

Votre TileService écoute en mode actif ou inactif. Nous vous recommandons d'utiliser le mode actif, que vous devrez déclarer dans le fichier manifeste de l'application. Sinon, TileService est le mode standard et n'a pas besoin d'être déclaré.

Ne partez pas du principe que votre TileService existera en dehors de la paire de méthodes onStartListening() et onStopListening().

Utilisez le mode actif pour un TileService qui écoute et surveille son état dans son propre processus. Un TileService en mode actif est lié à onTileAdded(), onTileRemoved(), aux événements d'appui et aux demandes du processus de l'application.

Nous vous recommandons d'utiliser le mode actif si votre TileService est averti lorsque l'état de votre carte doit être mis à jour par son propre processus. Les tuiles actives limitent la charge sur le système, car elles n'ont pas besoin d'être liées chaque fois que le panneau "Réglages rapides" devient visible pour l'utilisateur.

La méthode statique TileService.requestListeningState() peut être appelée pour demander le démarrage de l'état d'écoute et recevoir un rappel vers onStartListening().

Vous pouvez déclarer le mode actif en ajoutant META_DATA_ACTIVE_TILE au fichier manifeste de votre application.

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

Mode non actif

Le mode non actif est le mode standard. Un TileService est en mode non actif s'il est lié chaque fois que votre carte est visible par l'utilisateur. Cela signifie que votre TileService peut être créé et lié à nouveau à des moments indépendants de sa volonté. Il peut également être dissocié et détruit lorsque l'utilisateur ne consulte pas la carte.

Votre application reçoit un rappel vers onStartListening() une fois que l'utilisateur a ouvert le panneau "Réglages rapides". Vous pouvez mettre à jour votre objet Tile autant de fois que vous le souhaitez entre onStartListening() et onStopListening().

Vous n'avez pas besoin de déclarer le mode non actif : n'ajoutez pas META_DATA_ACTIVE_TILE au fichier manifeste de votre application.

Présentation des états des cartes

Lorsqu'un utilisateur ajoute votre carte, celle-ci se trouve toujours dans l'un des états suivants.

  • STATE_ACTIVE : indique un état activé. L'utilisateur peut interagir avec votre carte lorsqu'elle est dans cet état.

    Par exemple, pour une carte d'application de fitness qui permet aux utilisateurs de lancer une séance d'entraînement chronométrée, STATE_ACTIVE signifie que l'utilisateur a lancé une séance d'entraînement et que le minuteur est en cours d'exécution.

  • STATE_INACTIVE : indique un état désactivé ou en pause. L'utilisateur peut interagir avec votre carte lorsqu'elle est dans cet état.

    Pour reprendre l'exemple de la carte d'application de fitness, une carte dans l'état STATE_INACTIVE signifie que l'utilisateur n'a pas démarré de séance d'entraînement, mais qu'il peut le faire s'il le souhaite.

  • STATE_UNAVAILABLE : indique un état temporairement indisponible. L'utilisateur ne peut pas interagir avec votre carte lorsqu'elle est dans cet état.

    Par exemple, une tuile dans STATE_UNAVAILABLE signifie qu'elle n'est pas disponible pour l'utilisateur pour une raison quelconque.

Le système ne définit que l'état initial de votre objet Tile. Vous définissez l'état de l'objet Tile tout au long du reste de son cycle de vie.

Le système peut teinter l'icône et l'arrière-plan de la vignette pour refléter l'état de votre objet Tile. Les objets Tile définis sur STATE_ACTIVE sont les plus sombres, tandis que STATE_INACTIVE et STATE_UNAVAILABLE sont de plus en plus clairs. La teinte exacte est spécifique au fabricant et à la version.

Tuile VPN teintée pour refléter l'état des objets
Figure 4. Exemples de tuiles teintées pour refléter leur état (respectivement actif, inactif et indisponible).

Mettre à jour votre carte

Vous pourrez mettre à jour votre carte une fois que vous aurez reçu un rappel à l'adresse onStartListening(). Selon le mode de la tuile, celle-ci peut être mise à jour au moins une fois jusqu'à ce qu'elle reçoive un rappel vers onStopListening().

En mode actif, vous pouvez mettre à jour votre carte une seule fois avant de recevoir un rappel vers onStopListening(). En mode non actif, vous pouvez mettre à jour votre carte autant de fois que vous le souhaitez entre onStartListening() et onStopListening().

Vous pouvez récupérer votre objet Tile en appelant getQsTile(). Pour mettre à jour des champs spécifiques de votre objet Tile, appelez les méthodes suivantes :

Vous devez appeler updateTile() pour mettre à jour votre carte une fois que vous avez défini les champs de l'objet Tile sur les valeurs appropriées. Le système analysera alors les données de tuile mises à jour et actualisera l'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()
}

Gérer les appuis

Les utilisateurs peuvent appuyer sur votre carte pour déclencher une action si elle se trouve dans STATE_ACTIVE ou STATE_INACTIVE. Le système appelle ensuite le rappel onClick() de votre application.

Une fois que votre application reçoit un rappel vers onClick(), elle peut lancer une boîte de dialogue ou une activité, déclencher une tâche en arrière-plan ou modifier l'état de votre carte.

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()
}

Lancer une boîte de dialogue

showDialog() réduit le panneau des réglages rapides et affiche une boîte de dialogue. Utilisez une boîte de dialogue pour ajouter du contexte à votre action si elle nécessite une saisie supplémentaire ou le consentement de l'utilisateur.

Lancer une activité

startActivityAndCollapse() démarre une activité tout en réduisant le panneau. Les activités sont utiles s'il y a plus d'informations détaillées à afficher que dans une boîte de dialogue, ou si votre action est hautement interactive.

Si votre application nécessite une interaction importante de l'utilisateur, elle ne doit lancer une activité qu'en dernier recours. Envisagez plutôt d'utiliser une boîte de dialogue ou un bouton d'activation/de désactivation.

Un appui prolongé sur une vignette affiche l'écran Infos sur l'appli. Pour remplacer ce comportement et lancer une activité de définition des préférences, ajoutez un <intent-filter> à l'une de vos activités avec ACTION_QS_TILE_PREFERENCES.

À partir de l'API Android 28, l'élément PendingIntent doit comporter l'attribut Intent.FLAG_ACTIVITY_NEW_TASK :

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

Vous pouvez également ajouter l'option dans le AndroidManifest.xml de la section Activity spécifique.

Marquer votre tuile comme activable/désactivable

Nous vous recommandons de marquer votre tuile comme activable/désactivable si elle fonctionne principalement comme un commutateur à deux états (ce qui est le comportement le plus courant des tuiles). Cela permet de fournir des informations sur le comportement de la carte au système d'exploitation et d'améliorer l'accessibilité globale.

Définissez les métadonnées TOGGLEABLE_TILE sur true pour marquer votre carte comme activable/désactivable.

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

N'effectuer que des actions sécurisées sur les appareils verrouillés de manière sécurisée

Votre tuile peut s'afficher au-dessus de l'écran de verrouillage sur les appareils verrouillés. Si la tuile contient des informations sensibles, vérifiez la valeur de isSecure() pour déterminer si l'appareil est dans un état sécurisé. Votre TileService doit modifier son comportement en conséquence.

Si l'action de la tuile peut être effectuée en toute sécurité lorsque l'appareil est verrouillé, utilisez startActivity() pour lancer une activité au-dessus de l'écran de verrouillage.

Si l'action de la tuile n'est pas sécurisée, utilisez unlockAndRun() pour inviter l'utilisateur à déverrouiller son appareil. Si l'opération réussit, le système exécute l'objet Runnable que vous transmettez à cette méthode.

Catégoriser votre tuile

Pour améliorer l'expérience utilisateur dans les Réglages rapides, vous pouvez classer votre vignette par catégorie. Le système organise les cartes en catégories telles que "Connectivité", "Affichage" et "Confidentialité". Le système utilise ces catégories pour trier et regrouper les blocs en mode d'édition des Réglages rapides, ce qui permet aux utilisateurs de les trouver et de les gérer plus facilement.

Implémentation

Pour spécifier une catégorie pour votre TileService, ajoutez un champ de métadonnées à la déclaration du service dans le fichier AndroidManifest.xml :

  • Dans votre AndroidManifest.xml, ajoutez un élément <meta-data> dans l'élément <service> de votre TileService.
  • android:name : définissez cette valeur sur android.service.quicksettings.TILE_CATEGORY.
  • android:value : attribuez l'une des constantes de catégorie prédéfinies, telles que android.service.quicksettings.CATEGORY_CONNECTIVITY ou android.service.quicksettings.CATEGORY_DISPLAY.

Comme illustré dans l'exemple suivant :

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

L'API fournit un ensemble de catégories prédéfinies parmi lesquelles choisir. Ces catégories sont définies en tant que constantes de chaîne dans la classe TileService.

Si aucune catégorie n'est spécifiée, le système attribue automatiquement une catégorie par défaut :

  • Depuis les applis système : pour les cartes qui font partie d'une application système.
  • Depuis les applis que vous avez installées : pour les cartes des applications installées par l'utilisateur.

Bien que les appareils Google Pixel utilisent des catégories dans les Réglages rapides, les OEM peuvent utiliser ou ignorer ces informations de catégorie dans leurs UI système respectives.

Inviter l'utilisateur à ajouter votre carte

Pour ajouter manuellement votre vignette, les utilisateurs doivent suivre plusieurs étapes :

  1. Balayez l'écran vers le bas pour ouvrir le panneau Réglages rapides.
  2. Appuyez sur le bouton "Modifier".
  3. Faire défiler toutes les vignettes sur son appareil jusqu'à trouver la vôtre.
  4. Appuyez de manière prolongée sur la vignette, puis faites-la glisser vers la liste des vignettes actives.

L'utilisateur peut également déplacer ou supprimer votre carte à tout moment.

À partir d'Android 13, vous pouvez utiliser la méthode requestAddTileService() pour permettre aux utilisateurs d'ajouter plus facilement votre carte à un appareil. Cette méthode invite les utilisateurs à ajouter rapidement votre bloc directement à leur panneau "Réglages rapides". L'invite inclut le nom de l'application, le libellé fourni et l'icône.

Invite de l'API de placement des Réglages rapides
Figure 5. Invite de l'API de placement des réglages rapides.
public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Le rappel contient des informations indiquant si la tuile a été ajoutée ou non, si elle était déjà présente ou si une erreur s'est produite.

Faites preuve de discernement lorsque vous décidez quand et à quelle fréquence envoyer des prompts aux utilisateurs. Nous vous recommandons d'appeler requestAddTileService() uniquement en contexte, par exemple lorsque l'utilisateur interagit pour la première fois avec une fonctionnalité facilitée par votre carte.

Le système peut choisir d'arrêter de traiter les demandes pour une ComponentName donnée si l'utilisateur l'a déjà refusée un certain nombre de fois. L'utilisateur est déterminé à partir de l'Context utilisé pour récupérer ce service : il doit correspondre à l'utilisateur actuel.