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 l'utilisation afin de fournir des signaux qui améliorent le classement des raccourcis.

Cette page décrit ces méthodes et d'autres méthodes courantes de gestion des raccourcis.

Comportement des raccourcis

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

Visibilité des raccourcis

Les raccourcis statiques et dynamiques apparaissent 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 est une pression prolongée sur l'icône de lanceur de l'application, mais il peut être différent sur d'autres applications de lanceur. Avec l'Assistant Google, les raccourcis peuvent être affichés dans celui-ci ou lancés à l'aide 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 restent toujours visibles. Un raccourci épinglé n'est supprimé du lanceur d'applications que dans les cas suivants:

  • L'utilisateur le supprime.
  • L'appli associée au raccourci est désinstallée.
  • Pour effacer les données d'une application, l'utilisateur doit accéder à Settings > Apps & notifications (Paramètres > Applications et notifications), sélectionner l'application, puis appuyer sur Stockage > Vider l'espace de stockage.

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

Capture d'écran d'Android Sharesheet
Image 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 affiche les raccourcis d'une application, ceux-ci 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 ou dynamique), les raccourcis sont triés par ordre de classement croissant, en fonction de ShortcutInfo.getRank. L'Assistant Google prend également en compte le classement des raccourcis pour déterminer les raccourcis contextuels à présenter aux utilisateurs.

Les classements sont des 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 dépend de plusieurs facteurs, y compris l'historique des utilisateurs, la récence, la fréquence, l'indice de classement, l'utilisation de l'application et la priorité définie pour la conversation associée à un raccourci de partage. Les cibles de partage créées à l'aide de l'API de raccourcis de partage sont prioritaires sur les cibles de partage générées par ChooserTargetService, qui était obsolète dans Android 11. Dans Android 12 et les versions ultérieures, les cibles de partage générées par le ChooserTargetService obsolète n'apparaîtront plus dans la feuille de partage.

La plupart des lanceurs d'applications affichent quatre raccourcis au maximum. Pour toute combinaison de raccourcis statiques et de raccourcis dynamiques définies, le lanceur 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 de manière programmatique, le lanceur affiche les deux premiers raccourcis statiques et les deux raccourcis dynamiques les mieux classés.

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 le configurer pour déclencher 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.

Attribuer plusieurs intents

Lorsque vous créez un raccourci avec ShortcutInfoCompat.Builder, vous pouvez utiliser setIntents() au lieu de setIntent(). En appelant setIntents(), vous pouvez lancer plusieurs activités dans votre application lorsque l'utilisateur sélectionne un raccourci, en plaçant toutes les activités, à l'exception de la dernière, dans la pile "Retour". Si l'utilisateur appuie ensuite sur le bouton "Retour" de l'appareil, il voit une autre activité dans votre application au lieu de revenir au lanceur de l'appareil.

Commencer une activité à partir d'une autre

Les raccourcis statiques ne peuvent pas comporter d'indicateurs d'intent personnalisés. Le premier intent d'un raccourci statique est toujours défini sur Intent.FLAG_ACTIVITY_NEW_TASK et Intent.FLAG_ACTIVITY_CLEAR_TASK défini. Cela signifie que lorsque votre application est en cours d'exécution, toutes les activités existantes sont détruites lorsqu'un raccourci statique est lancé. Si vous ne souhaitez pas que ce comportement s'applique, vous pouvez utiliser une activité "trampoline" (activité invisible qui lance une autre activité) dans Activity.onCreate(Bundle) qui appelle Activity.finish():

  1. Dans le fichier AndroidManifest.xml, incluez l'attribution d'attributs android:taskAffinity="" dans l'activité de trampoline.
  2. Dans le fichier de ressources des raccourcis, référencez l'activité de trampoline dans l'intent au sein du raccourci statique.

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

Définir des options d'intent

Vous pouvez publier des raccourcis dynamiques avec n'importe quel ensemble d'indicateurs Intent. De préférence, spécifiez Intent.FLAG_ACTIVITY_CLEAR_TASK avec vos autres options. Sinon, si vous tentez de démarrer une autre tâche pendant l'exécution de votre application, l'activité cible risque de ne pas s'afficher.

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

Mettre à jour les raccourcis

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

Lorsqu'un raccourci dynamique est épinglé, même lorsque l'éditeur le supprime en tant que raccourci dynamique, il reste visible et peut être lancé. Une application peut ainsi avoir plus de getMaxShortcutCountPerActivity() raccourcis.

Prenons l'exemple suivant, qui part du principe 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 entame trois conversations supplémentaires: c5, c6 et c7. L'application d'é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 sont toujours des raccourcis épinglés auxquels l'utilisateur peut accéder et le lancer.

L'utilisateur peut ensuite accéder à un total de sept raccourcis qui renvoient à des activités dans l'application d'é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 des raccourcis existants avec les mêmes ID. Toutefois, vous ne pouvez pas les utiliser pour mettre à jour des 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 de l'Assistant telles que l'Assistant Google n'est pas limité. Utilisez la méthode pushDynamicShortcut() de la bibliothèque Jetpack ShortcutManagerCompat pour créer et mettre à jour des raccourcis à utiliser dans les applications de l'assistant. Ajoutez également la bibliothèque d'intégration de raccourcis Google à votre application pour que les liens dynamiques puissent s'afficher dans l'Assistant Google.

Pour en savoir plus sur les consignes concernant les raccourcis d'application, y compris sur leur modification, consultez la section Bonnes pratiques concernant 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 l'annonce 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 des raccourcis statiques et dynamiques apparaissent, le lanceur examine l'historique d'activation des raccourcis. Pour les raccourcis statiques, vous pouvez savoir quand 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'identifiant 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. Cette méthode permet aux applications assistantes, comme 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.

Désactiver les raccourcis

Étant donné que votre application et ses utilisateurs peuvent épingler des raccourcis dans le 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, qui 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 un CharSequence comme message d'erreur personnalisé. Ce message d'erreur s'affiche lorsque les utilisateurs tentent de lancer un raccourci désactivé.

Limitation du débit

Lorsque vous utilisez les méthodes setDynamicShortcuts(), addDynamicShortcuts() ou updateShortcuts(), il est possible que vous ne puissiez appeler ces méthodes qu'un certain nombre de fois dans une application en arrière-plan, c'est-à-dire sans activités ni services au premier plan. La limite du nombre spécifique d'appels vers ces méthodes s'appelle la limitation du débit. Cette fonctionnalité empêche ShortcutManagerCompat de surcharger les ressources de l'appareil.

Lorsque la limitation du débit est active, isRateLimitingActive() renvoie la valeur "true". Cependant, 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 des méthodes ShortcutManager jusqu'à ce que la limite de débit soit à nouveau atteinte. Ces événements incluent les suivants:

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

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

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Sauvegarder et restaurer

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 une fonctionnalité de sauvegarde et de restauration, tenez compte des points suivants concernant les raccourcis d'application:

  • Les raccourcis statiques sont republiés automatiquement, mais seulement lorsque 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 restaurés automatiquement dans le lanceur 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 facilement sur un nouvel appareil.

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

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}