Gérer les raccourcis

Après avoir créé des raccourcis, vous devrez peut-être les gérer pendant toute la durée de vie votre application. Par exemple, vous pouvez optimiser votre application en déterminant vos utilisateurs effectuent souvent 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 de des actions obsolètes ou manquantes. Pour les raccourcis référencés dans conversations, vous pouvez suivre l'utilisation pour fournir des signaux qui améliorent le classement des raccourcis.

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

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

Important :Toutes les informations sur les raccourcis sont stockées dans des identifiants chiffrés d'espace de stockage, de sorte que votre application ne peut accéder aux raccourcis d'un utilisateur qu'une fois celui-ci déverrouillé l'appareil.

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

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

Étant donné que les raccourcis épinglés s'affichent dans le lanceur d'applications, ils sont toujours visibles. Un raccourci épinglé n'est supprimé du Lanceur d'applications 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 > Vider l'espace de stockage

Cibles de partage sont un sous-ensemble de raccourcis dynamiques qui s'affichent sur la ligne de partage direct Feuille de partage Android

Image 1. Android Sharesheet Les cibles de partage direct apparaissent dans 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, ceux-ci doivent apparaître comme suit : commande:

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

Dans chaque type de raccourci (statique ou dynamique), les raccourcis sont triés par ordre de Augmentation du classement d'après ShortcutInfo.getRank Assistant Google tient également compte du classement des raccourcis lors de la sélection des raccourcis contextuels à afficher utilisateurs.

Les classements 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 créations 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, dont les anciens historique, récence, fréquence, indice de classement, l'utilisation des applications et la priorité de la conversation associée à le raccourci de partage. Partager les cibles créées à l'aide de API Share Shortcuts sont prioritaires par rapport aux cibles de partage produites par ChooserTargetService qui était obsolète dans Android 11. Dans Android 12 et versions ultérieures, les cibles de partage généré par le ChooserTargetService obsolète n'apparaîtra plus dans le partager la feuille.

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

Remarque :Les classements sont ajustés automatiquement afin d'être uniques pour chaque type de statique ou dynamique. Par exemple, s'il existe trois raccourcis dynamiques avec les rangs 0, 1 et 2, et en ajoutant un autre raccourci dynamique avec le rang 1 représente une requête visant à placer ce raccourci en deuxième position. En réponse, les classements des raccourcis précédemment classés 1 et 2 deviennent 2 et 3, respectivement.

Gérer plusieurs intents et activités

Si vous souhaitez que votre application effectue plusieurs opérations lorsque l'utilisateur active un vous pouvez le configurer pour déclencher des activités successives. Vous pouvez en attribuant plusieurs intents, en démarrant une activité ou en définissant 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 peut 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, sur la pile "Retour". Si le 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 d’applications de l’appareil.

Remarque :Lorsque l'utilisateur sélectionne un raccourci, puis appuie sur le bouton "Retour", votre l'application lance l'activité correspondant à l'avant-dernier intent indiqué dans le fichier de ressources des raccourcis. Ce modèle de comportement continue à mesure que l'utilisateur continue d'appuyer sur le bouton Retour jusqu'à ce que l'utilisateur efface la pile "Retour" qu'un crée un raccourci. Ensuite, si l'utilisateur appuie de nouveau sur le bouton Retour, le système il revient au lanceur d'applications.

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

Les raccourcis statiques ne peuvent pas comporter d'indicateurs d'intent personnalisés. Le premier intent d'une requête le raccourci contient toujours Intent.FLAG_ACTIVITY_NEW_TASK et Intent.FLAG_ACTIVITY_CLEAR_TASK défini. Cela signifie que lorsque votre application est toutes les activités de l'application sont détruites raccourci est lancé. Si ce comportement n'est pas souhaitable, vous pouvez utiliser un trampoline activité : une activité invisible qui lance une autre activité, Activity.onCreate(Bundle) qui appelle Activity.finish():

1. Dans le fichier AndroidManifest.xml, incluez l'attribution des attributs. android:taskAffinity=" dans l'activité des trampolines.
2. Dans le fichier de ressources de raccourcis, faites référence à l'activité du trampoline dans dans le raccourci statique.

Pour plus d'informations sur les activités de trampoline, consultez la section Démarrer une activité d'une autre source.

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 Intent.FLAG_ACTIVITY_CLEAR_TASK avec vos autres options. Si vous essayez de démarrer une autre tâche alors que votre application il est possible que l'activité cible ne s'affiche pas.

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 certain nombre d'éléments statiques et dynamiques de raccourcis combinés, soit égale à la valeur renvoyée par getMaxShortcutCountPerActivity Il n'y a pas de limite au nombre les raccourcis épinglés qu'une application peut créer.

Lorsqu'un raccourci dynamique est épinglé, même si l'éditeur le supprime en tant que raccourci dynamique, le raccourci épinglé reste visible et peut être lancé. Cela permet une application comporte 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, qui représentent les quatre conversations 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. La l'application de l'éditeur republie ses raccourcis dynamiques. Nouveau raccourci dynamique liste est: c4, c5, c6 et c7.

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

L'utilisateur peut alors accéder à sept raccourcis au total, qui lui permettent d'accéder aux activités de l'application de l'éditeur. En effet, le total inclut le nombre maximal raccourcis et les trois raccourcis épinglés.

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

Le nombre de raccourcis pouvant être affichés n'est pas limité comme l'Assistant Google. Utilisez le pushDynamicShortcut() de la bibliothèque Jetpack ShortcutManagerCompat pour créer et mettre à jour raccourcis à utiliser dans les applications avec l'Assistant. Ajoutez également l'intégration des raccourcis Google bibliothèque à votre application pour permettre l'affichage de liens dynamiques sur Google Assistant.

Pour en savoir plus sur les consignes concernant les raccourcis d'application, y compris la modification des raccourcis, 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 le Diffusion Intent.ACTION_LOCALE_CHANGED indiquant une modification du système paramètres régionaux.

Suivre l'utilisation des raccourcis

Pour déterminer les situations dans lesquelles des raccourcis statiques et dynamiques apparaissent, le lanceur d’applications examine l’historique d’activation des raccourcis. Pour les raccourcis statiques, vous pouvez savoir à quel moment les utilisateurs effectuent des actions spécifiques dans votre application en appeler la méthode reportShortcutUsed() et lui transmettre 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 à 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'une qu'un événement pertinent se produise. L'utilisation d'un raccourci dynamique avec cette méthode permet les applications de l'Assistant Google, comme l'Assistant Google, suggèrent 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 communications et les messages entrants. Pour en savoir plus, consultez les bonnes pratiques pour les personnes et conversations.

Remarque :La bibliothèque d'intégration des raccourcis Google est nécessaire pour activer Liens dynamiques envoyés par votre application pour apparaître sur les surfaces Google comme l'Assistant Google. En ajoutant cette bibliothèque à votre appli, vous autorisez l'Assistant reçoivent vos liens dynamiques et les proposent aux utilisateurs depuis l'application Assistant.

Désactiver les raccourcis

Comme 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 dirigent les utilisateurs vers des actions dans votre application qui sont obsolètes ou qui n'existent plus. Pour gérer cette situation, vous pouvez désactiver les raccourcis que les utilisateurs ne doivent pas sélectionner en appelant disableShortcuts, qui supprime les raccourcis spécifiés du et les raccourcis dynamiques, et désactive les copies épinglées de ces raccourcis. Toi peut également utiliser une version surchargée de cette méthode qui accepte un CharSequence en tant que message d'erreur personnalisé. Ce message d'erreur apparaît alors lorsque les utilisateurs tentent de lancer un raccourci désactivé.

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

Limitation du débit

Lorsque vous utilisez setDynamicShortcuts(), addDynamicShortcuts(), ou updateShortcuts(), vous ne pourrez peut-être les appeler que un nombre spécifique de fois dans une application en arrière-plan, c'est-à-dire une application sans activité ni au premier plan. Le nombre maximal de fois où vous pouvez est appelée limitation du débit. Cette fonctionnalité empêche ShortcutManagerCompat de surconsommer des 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 peut appeler des méthodes ShortcutManager jusqu'à ce que la fréquence limite soit de nouveau atteinte. Ces sont 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 fréquence ShortcutManager à partir de l'appareil paramètres, ou saisissez 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 lorsque changer d'appareil en incluant le android:allowBackup="true" attribut dans le fichier manifeste de votre application. Si vous proposez la sauvegarde et la restauration, conservez tenez compte des points suivants concernant les raccourcis d'application:

• Les raccourcis statiques sont republiés automatiquement, mais seulement une fois que l'utilisateur réinstalle votre application sur un nouvel appareil.
• Les raccourcis dynamiques ne sont pas sauvegardés : incluez une logique dans votre application pour la republier quand un utilisateur ouvre votre application sur un nouvel appareil.
• Les raccourcis épinglés sont restaurés automatiquement dans le lanceur d'applications de l'appareil, mais les le système ne sauvegarde pas les icônes associées aux raccourcis épinglés. Par conséquent, enregistrez vos raccourcis épinglés dans votre application afin de pouvoir les restaurer facilement un nouvel appareil.

L'extrait de code suivant montre comment restaurer au mieux les paramètres dynamiques de votre application et comment 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.
            }
        }
    }
    // ...
}