Gérer les raccourcis

Après avoir créé des raccourcis, vous devrez peut-être les gérer tout au long de la durée de vie de votre application. Par exemple, vous pouvez optimiser votre application en déterminant la fréquence à laquelle vos utilisateurs effectuent des actions spécifiques avec vos raccourcis. Dans un autre cas, vous pouvez décider de désactiver un raccourci épinglé pour empêcher votre application d'effectuer des actions obsolètes ou manquantes. Pour les raccourcis référencés dans les conversations, vous pouvez suivre leur utilisation afin de fournir des signaux qui améliorent leur classement.

Cette page décrit ces méthodes et plusieurs autres méthodes courantes pour gérer vos raccourcis.

Comportement des raccourcis

Les sections suivantes contiennent des informations générales sur le comportement des raccourcis, y compris leur visibilité, leur ordre d'affichage et leur classement.

Visibilité des raccourcis

Important Toutes les informations sur les raccourcis sont stockées dans un espace de stockage chiffré par identifiants. Votre application ne peut donc pas accéder aux raccourcis d'un utilisateur tant qu'il n'a pas déverrouillé l'appareil.

Les raccourcis statiques et dynamiques s'affichent dans un lanceur d'applications ou un assistant compatible lorsque l'utilisateur effectue un geste ou une commande vocale spécifique. Sur les lanceurs d'applications compatibles, le geste consiste à appuyer de manière prolongée sur l'icône de lanceur de l'application, mais il peut être différent sur d'autres lanceurs d'applications. Avec l'Assistant Google, les raccourcis peuvent être affichés dans l'Assistant ou lancés à partir d'une commande vocale de l'utilisateur.

La classe LauncherApps fournit des API permettant aux applications de lanceur d'accéder aux raccourcis.

Comme les raccourcis épinglés apparaissent dans le lanceur d'applications, ils sont toujours visibles. Un raccourci épinglé n'est supprimé du lanceur que dans les cas suivants :

• L'utilisateur la supprime.
• L'application associée au raccourci est désinstallée.
• L'utilisateur efface les données d'une application en accédant à Paramètres > Applications et notifications, en sélectionnant l'application, puis en appuyant sur Stockage > Effacer le stockage.

Les cibles de partage sont un sous-ensemble de raccourcis dynamiques qui s'affichent dans la ligne de partage direct de la feuille de partage Android.

Figure 1. Android Sharesheet. Les cibles de partage direct apparaissent sur la première ligne, suivies des applications classées, puis des listes d'applications.

Ordre d'affichage des raccourcis

Lorsque le lanceur d'applications affiche les raccourcis d'une application, ils doivent apparaître dans l'ordre suivant :

1. Raccourcis statiques : raccourcis dont la méthode isDeclaredInManifest() renvoie true.
2. Raccourcis dynamiques : raccourcis dont la méthode ShortcutInfo.isDynamic() renvoie true.

Dans chaque type de raccourci (statique et dynamique), les raccourcis sont triés par rang croissant selon ShortcutInfo.getRank. L'Assistant Google tient également compte du classement des raccourcis pour déterminer les raccourcis contextuels à afficher aux utilisateurs.

Les rangs sont des nombres entiers séquentiels non négatifs. Les raccourcis statiques sont classés du premier au dernier dans l'ordre dans lequel ils apparaissent dans votre fichier shortcuts.xml. Pour les raccourcis dynamiques, vous pouvez mettre à jour le classement des raccourcis existants lorsque vous appelez updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) ou setDynamicShortcuts(Context, List).

L'ordre des cibles de partage est basé sur divers facteurs, y compris l'historique des utilisateurs, la récence, la fréquence, l'indice de classement, l'utilisation des applications et la priorité définie sur la conversation associée à un raccourci de partage. Les cibles de partage créées à l'aide de l'API Sharing Shortcuts sont prioritaires par rapport aux cibles de partage produites par ChooserTargetService, qui a été abandonné dans Android 11. Dans Android 12 et versions ultérieures, les cibles de partage générées par ChooserTargetService, qui est obsolète, n'apparaîtront plus dans la feuille de partage.

La plupart des lanceurs d'applications affichent au maximum quatre raccourcis. Pour toute combinaison de raccourcis statiques et dynamiques définis, le lanceur d'applications affiche un maximum de deux raccourcis statiques et deux raccourcis dynamiques. Par exemple, si vous définissez quatre raccourcis statiques et que vous créez trois raccourcis dynamiques par programmation, le lanceur d'applications affiche les deux premiers raccourcis statiques et les deux raccourcis dynamiques les mieux classés.

Remarque : Les rangs sont ajustés automatiquement pour être uniques à chaque type de raccourci (statique ou dynamique). Par exemple, s'il existe trois raccourcis dynamiques avec les rangs 0, 1 et 2, l'ajout d'un autre raccourci dynamique avec un rang de 1 représente une demande de placement de ce raccourci en deuxième position. En réponse, les positions des raccourcis précédemment classés en 1re et 2e positions passent respectivement à la 2e et à la 3e position.

Gérer plusieurs intents et activités

Si vous souhaitez que votre application effectue plusieurs opérations lorsque l'utilisateur active un raccourci, vous pouvez la configurer pour qu'elle déclenche des activités successives. Pour ce faire, vous pouvez attribuer plusieurs intents, démarrer une activité à partir d'une autre ou définir des indicateurs d'intent, selon le type de raccourci.

Démarrer une activité à partir d'une autre

Les raccourcis statiques ne peuvent pas comporter de flags d'intent personnalisés. La première intention d'un raccourci statique est toujours définie sur Intent.FLAG_ACTIVITY_NEW_TASK et Intent.FLAG_ACTIVITY_CLEAR_TASK. Cela signifie que lorsque votre application est en cours d'exécution, toutes les activités existantes dans l'application sont détruites lorsqu'un raccourci statique est lancé. Si vous ne souhaitez pas ce comportement, vous pouvez utiliser une activité trampoline (une activité invisible qui en démarre une autre) en appelant finish à l'intérieur d'un bloc de lancement ou onCreate avant la définition du contenu Compose :

1. Dans AndroidManifest.xml file, incluez l'attribution d'attribut android:taskAffinity="" dans l'activité de trampoline.

2. Dans le fichier de ressources de raccourcis, référencez l'activité de trampoline dans l'intent du raccourci statique.

Pour en savoir plus sur les activités trampoline, consultez Démarrer une activité à partir d'une autre.

Définir des indicateurs d'intent

Vous pouvez publier des raccourcis dynamiques avec n'importe quel ensemble d'options Intent. De préférence, spécifiez la combinaison de Intent.FLAG_ACTIVITY_SINGLE_TOP et Intent.FLAG_ACTIVITY_CLEAR_TOP dans l'intent du raccourci. Cela garantit que si votre ComponentActivity est déjà actif, il est mis au premier plan et réutilisé sans être détruit, ce qui permet à votre architecture à activité unique de gérer correctement l'événement de raccourci via onNewIntent().

Pour en savoir plus sur les tâches et les indicateurs d'intent, consultez Tâches et pile "Retour".

Modifier les raccourcis

L'icône du lanceur d'applications de chaque application peut contenir, au maximum, un nombre de raccourcis statiques et dynamiques combinés égal à la valeur renvoyée par getMaxShortcutCountPerActivity. Le nombre de raccourcis épinglés qu'une application peut créer n'est pas limité.

Lorsqu'un raccourci dynamique est épinglé, il reste visible et peut être lancé, même si l'éditeur le supprime en tant que raccourci dynamique. Cela permet à une application d'avoir plus de getMaxShortcutCountPerActivity raccourcis.

Prenons l'exemple suivant, qui suppose que la valeur renvoyée par getMaxShortcutCountPerActivity est 4 :

1. Une application de chat publie quatre raccourcis dynamiques représentant les quatre conversations les plus récentes : c1, c2, c3 et c4.
2. L'utilisateur épingle les quatre raccourcis.
3. Plus tard, l'utilisateur démarre trois conversations supplémentaires : c5, c6 et c7. L'application éditeur republie ses raccourcis dynamiques. La nouvelle liste de raccourcis dynamiques est la suivante : c4, c5, c6 et c7.

L'application doit supprimer c1, c2 et c3, car elle ne peut pas afficher plus de quatre raccourcis dynamiques. Toutefois, c1, c2 et c3 restent des raccourcis épinglés auxquels l'utilisateur peut accéder et qu'il peut lancer.

L'utilisateur peut alors accéder à un total de sept raccourcis vers des activités dans l'application de l'éditeur. En effet, le total inclut le nombre maximal de raccourcis et les trois raccourcis épinglés.

1. L'application peut utiliser updateShortcuts(Context, List) pour mettre à jour l'un des sept raccourcis existants. Par exemple, vous pouvez mettre à jour cet ensemble de raccourcis lorsque les icônes des pairs de chat changent.
2. Vous pouvez utiliser les méthodes addDynamicShortcuts(Context, List) et setDynamicShortcuts(Context, List) pour mettre à jour les raccourcis existants avec les mêmes ID. Toutefois, vous ne pouvez pas les utiliser pour mettre à jour les raccourcis épinglés non dynamiques, car ces deux méthodes tentent de convertir les listes de raccourcis données en raccourcis dynamiques.

Le nombre de raccourcis pouvant être affichés dans les applications d'assistance telles que l'Assistant Google est illimité. Utilisez la méthode pushDynamicShortcut de la bibliothèque Jetpack ShortcutManagerCompat pour créer et mettre à jour des raccourcis à utiliser dans les applications d'assistance. Ajoutez également la bibliothèque d'intégration de raccourcis Google à votre application pour que les liens dynamiques puissent apparaître dans l'Assistant Google.

Pour en savoir plus sur les consignes concernant les raccourcis d'application, y compris sur la mise à jour des raccourcis, consultez Bonnes pratiques pour les raccourcis.

Gérer les modifications des paramètres régionaux du système

Les applications doivent mettre à jour les raccourcis dynamiques et épinglés lorsqu'elles reçoivent la diffusion Intent.ACTION_LOCALE_CHANGED indiquant une modification des paramètres régionaux du système.

Suivre l'utilisation des raccourcis

Pour déterminer les situations dans lesquelles les raccourcis statiques et dynamiques s'affichent, le lanceur examine l'historique d'activation des raccourcis. Pour les raccourcis statiques, vous pouvez suivre le moment où les utilisateurs effectuent des actions spécifiques dans votre application en appelant la méthode reportShortcutUsed et en lui transmettant l'ID d'un raccourci lorsque l'un des événements suivants se produit :

• L'utilisateur sélectionne le raccourci avec l'ID donné.
• Dans l'application, l'utilisateur effectue manuellement l'action correspondant au même raccourci.

Votre application suit l'utilisation des raccourcis dynamiques en appelant la méthode pushDynamicShortcut et en lui transmettant l'ID du raccourci lorsqu'un événement pertinent se produit. L'envoi de l'utilisation de raccourcis dynamiques avec cette méthode permet aux applications d'assistance telles que l'Assistant Google de suggérer des raccourcis pertinents aux utilisateurs. Étant donné que la méthode pushDynamicShortcut signale l'utilisation lorsqu'elle est appelée, n'appelez pas la méthode reportShortcutUsed pour les mêmes raccourcis.

Pour les raccourcis liés aux conversations, il est important de suivre l'utilisation des messages sortants et entrants. Pour en savoir plus, consultez les bonnes pratiques concernant les personnes et les conversations.

Remarque : La bibliothèque d'intégration des raccourcis Google est requise pour que les liens dynamiques envoyés par votre application puissent s'afficher sur les surfaces Google telles que l'Assistant Google. En ajoutant cette bibliothèque à votre application, vous permettez à l'Assistant d'ingérer vos liens dynamiques et de les suggérer aux utilisateurs depuis l'application Assistant.

Désactiver les raccourcis

Étant donné que votre application et ses utilisateurs peuvent épingler des raccourcis au lanceur d'applications de l'appareil, il est possible que ces raccourcis épinglés redirigent les utilisateurs vers des actions obsolètes ou qui n'existent plus dans votre application. Pour gérer cette situation, vous pouvez désactiver les raccourcis que vous ne souhaitez pas que les utilisateurs sélectionnent en appelant disableShortcuts. Cela supprime les raccourcis spécifiés de la liste des raccourcis statiques et dynamiques, et désactive les copies épinglées de ces raccourcis. Vous pouvez également utiliser une version surchargée de cette méthode qui accepte CharSequence comme message d'erreur personnalisé. Ce message d'erreur s'affiche ensuite lorsque les utilisateurs tentent de lancer un raccourci désactivé.

Remarque : Si vous supprimez certains raccourcis statiques de votre application lorsque vous la mettez à jour, le système les désactive automatiquement.

Limitation du débit

Lorsque vous utilisez les méthodes setDynamicShortcuts, addDynamicShortcuts ou updateShortcuts, vous ne pouvez peut-être les appeler qu'un certain nombre de fois dans une application en arrière-plan (une application sans activité ni service au premier plan). La limite du nombre de fois que vous pouvez appeler ces méthodes est appelée limitation du débit. Cette fonctionnalité empêche ShortcutManagerCompat de consommer trop de ressources de l'appareil.

Lorsque la limitation du débit est active, isRateLimitingActive renvoie la valeur "true". Toutefois, la limitation du débit est réinitialisée lors de certains événements. Ainsi, même les applications en arrière-plan peuvent appeler les méthodes ShortcutManager jusqu'à ce que la limite de débit soit à nouveau atteinte. Voici quelques exemples d'événements :

• Une application passe au premier plan.
• Les paramètres régionaux du système changent.
• L'utilisateur effectue l'action Réponse intégrée sur une notification.

Si vous rencontrez une limitation du débit lors du développement ou des tests, vous pouvez sélectionner Options pour les développeurs > Réinitialiser la limitation du débit ShortcutManager dans les paramètres de l'appareil ou saisir la commande suivante dans adb :

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

Sauvegarde et restauration

Vous pouvez autoriser les utilisateurs à effectuer des opérations de sauvegarde et de restauration sur votre application lorsqu'ils changent d'appareil en incluant l'attribution de l'attribut android:allowBackup="true" dans le fichier manifeste de votre application. Si vous proposez la sauvegarde et la restauration, gardez à l'esprit les points suivants concernant les raccourcis d'application :

• Les raccourcis statiques sont republiés automatiquement, mais uniquement après que l'utilisateur a réinstallé votre application sur un nouvel appareil.
• Les raccourcis dynamiques ne sont pas sauvegardés. Vous devez donc inclure une logique dans votre application pour les republier lorsqu'un utilisateur ouvre votre application sur un nouvel appareil.
• Les raccourcis épinglés sont automatiquement restaurés dans le lanceur d'applications de l'appareil, mais le système ne sauvegarde pas les icônes associées aux raccourcis épinglés. Par conséquent, enregistrez les images de vos raccourcis épinglés dans votre application afin de pouvoir les restaurer rapidement sur un nouvel appareil.

L'extrait de code suivant montre comment restaurer au mieux les raccourcis dynamiques de votre application et comment vérifier si les raccourcis épinglés de votre application ont été conservés :

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}