Utilisez des cibles de partage direct pour permettre aux utilisateurs d'autres applications de partager plus facilement et plus rapidement des URL, des images ou d'autres types de données avec votre application. Le partage direct présente les contacts des applications de messagerie et de réseaux sociaux directement dans la Sharesheet Android, sans que les utilisateurs aient à sélectionner l'application, puis à rechercher le contact.
ShortcutManagerCompat est une API AndroidX qui fournit des raccourcis de partage et qui est rétrocompatible avec l'API ChooserTargetService obsolète. C'est la méthode recommandée pour publier à la fois les raccourcis de partage et ChooserTargets. Pour obtenir des instructions, consultez la section Utiliser AndroidX pour fournir à la fois des raccourcis de partage et des ChooserTargets sur cette page.
Publier les cibles de partage direct
La ligne de partage direct de Sharesheet n'affiche que les raccourcis dynamiques fournis par l'API Sharing Shortcuts. Pour publier des cibles de partage direct, procédez comme suit :
Dans le fichier de ressources XML de votre application, déclarez les éléments
share-target.<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>Lorsque votre application s'initialise, utilisez
setDynamicShortcutspour trier les raccourcis dynamiques par importance.Un indice inférieur indique une importance plus élevée. Si vous créez une application de communication, il peut s'agir de conversations principales classées par récence selon leur récence selon leur affichage dans votre application. Ne publiez pas de raccourcis obsolètes. Une conversation sans activité utilisateur au cours des 30 derniers jours est considérée comme obsolète.
Kotlin
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
Si vous développez une application de communication, signalez immédiatement l'utilisation des raccourcis via
pushDynamicShortcutchaque fois que l'utilisateur reçoit ou envoie un message à un contact. Pour en savoir plus, consultez Signaler l'utilisation des raccourcis pour les applications de communication sur cette page. Par exemple, signalez l'utilisation des messages envoyés par l'utilisateur en spécifiant la fonctionnalitéactions.intent.SEND_MESSAGEdans le raccourci viaShortcutInfoCompat.Builder#addCapabilityBinding.Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Si l'utilisateur supprime un contact, utilisez
removeLongLivedShortcut. Il s'agit de la méthode recommandée pour supprimer le raccourci, qu'il soit mis en cache par les services système ou non. L'extrait de code suivant montre comment procéder.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Améliorer le classement de vos cibles de partage direct
La Sharesheet Android affiche un nombre fixe de cibles de partage direct. Ces suggestions sont triées par classement. Vous pouvez améliorer le classement de vos raccourcis en procédant comme suit:
- Assurez-vous que tous les
shortcutIdssont uniques et qu'ils ne sont jamais réutilisés pour différentes cibles. - Assurez-vous que le raccourci est durable en appelant
setLongLived(true). - Pour les raccourcis liés aux conversations, signalez l'utilisation des raccourcis pour les messages sortants et entrants en republicant les raccourcis correspondants via
ShortcutManagerCompat.pushDynamicShortcut. Pour en savoir plus, consultez la section Enregistrer l'utilisation des raccourcis pour les applications de communication sur cette page. - Évitez de fournir des cibles de partage direct non pertinentes ou obsolètes (par exemple, des contacts avec lesquels l'utilisateur n'a pas échangé de messages au cours des 30 derniers jours).
- Pour les applications de SMS, évitez de fournir des raccourcis pour les numéros courts ou les conversations identifiées comme du spam potentiel. Il est très peu probable que les utilisateurs partagent des contenus dans ces conversations.
- Appelez
setCategories()pour associer le raccourci aux attributsmimeTypeappropriés. Par exemple, pour une application de SMS, si le contact n'est pas compatible avec le RCS ou les MMS, vous n'associerez pas le raccourci correspondant à des types MIME non textuels tels queimage/*etvideo/*. - Pour une conversation donnée, une fois qu'un raccourci dynamique est transmis et que l'utilisation est signalée, ne modifiez pas l'ID du raccourci. Cela permet de conserver les données d'utilisation pour le classement.
Si l'utilisateur appuie sur une cible de partage direct, votre application doit le rediriger vers une UI où il peut effectuer une action directement sur l'objet de la cible. Ne présentez pas à l'utilisateur une UI de sélection d'application et ne le placez pas dans une UI sans rapport avec la cible sur laquelle l'utilisateur appuie. Par exemple, dans une application de chat, appuyer sur une cible de partage direct permet à l'utilisateur d'accéder à une conversation avec la personne qu'il a sélectionnée. Le clavier est visible et le message est prérempli avec les données partagées.
API de raccourcis de partage
À partir d'Android 10 (niveau d'API 29), ShortcutInfo.Builder a ajouté des méthodes et des améliorations qui fournissent des informations supplémentaires sur la cible de partage:
setCategories()- À partir d'Android 10, les catégories sont également utilisées pour filtrer les raccourcis pouvant gérer des intents ou des actions de partage. Pour en savoir plus, consultez Déclarer une cible de partage. Ce champ est obligatoire pour les raccourcis destinés à être utilisés comme cibles de partage.
setLongLived()Spécifie si un raccourci est valide ou non lorsqu'il a été annulé ou rendu invisible par l'application (en tant que raccourci dynamique ou épinglé). Si un raccourci est de longue durée, il peut être mis en cache par divers services système, même après avoir été désapprouvé en tant que raccourci dynamique.
Rendre un raccourci durable peut améliorer son classement. Pour en savoir plus, consultez la section Obtenir le meilleur classement.
setShortLabel(),setLongLabel()Lorsque vous publiez un raccourci vers une personne, veuillez inclure son nom complet dans
setLongLabel()et tout nom court, tel qu'un surnom ou un prénom, danssetShortLabel().
Consultez un exemple de publication de raccourcis de partage sur GitHub.
Fournir des images de raccourci
Pour créer un raccourci de partage, vous devez ajouter une image via setIcon().
Les raccourcis de partage peuvent apparaître sur différentes surfaces du système et être remodelés.
De plus, certains appareils équipés d'Android 7, 8 ou 9 (niveaux d'API 25, 26, 27 et 28) peuvent afficher des icônes bitmap uniquement sans arrière-plan, ce qui réduit considérablement le contraste. Pour vous assurer que votre raccourci s'affiche comme prévu, fournissez un bitmap adaptatif à l'aide de IconCompat.createWithAdaptiveBitmap().
Assurez-vous que les bitmaps adaptatifs respectent les mêmes consignes et dimensions que les icônes adaptatives. La méthode la plus courante consiste à mettre à l'échelle le bitmap carré prévu à 72 x 72 dp et à le centrer dans un canevas transparent de 108 x 108 dp. Si votre icône inclut des zones transparentes, vous devez inclure une couleur d'arrière-plan. Sinon, les régions transparentes apparaissent en noir.
Ne fournissez pas d'images masquées sur une forme spécifique. Par exemple, avant Android 10 (niveau d'API 29), il était courant de fournir des avatars utilisateur pour les ChooserTarget de partage direct masqués en cercle. Android Sharesheet et d'autres surfaces système d'Android 10 façonnent et thématisent désormais les images de raccourci.
La méthode privilégiée pour fournir des raccourcis de partage, via ShortcutManagerCompat, consiste à transformer automatiquement les objets ChooserTarget de partage direct rétrocompatibles en cercles.
Définir une cible de partage
Les cibles de partage doivent être déclarées dans le fichier de ressources de l'application, comme pour les définitions de raccourcis statiques. Ajoutez des définitions de cibles de partage dans l'élément racine <shortcuts> du fichier de ressources, ainsi que d'autres définitions de raccourcis statiques. Chaque élément <share-targets> contient des informations sur le type de données partagé, les catégories correspondantes et la classe cible qui gérera l'intent de partage. Le code XML se présente comme suit:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
L'élément de données d'une cible de partage est semblable à la spécification de données d'un filtre d'intent. Chaque cible de partage peut avoir plusieurs catégories, qui ne sont utilisées que pour faire correspondre les raccourcis publiés d'une application à ses définitions de cible de partage. Les catégories peuvent avoir des valeurs arbitraires définies par l'application.
Si l'utilisateur sélectionne le raccourci de partage dans la Sharesheet Android correspondant à l'exemple de partage cible ci-dessus, l'application recevra l'intent de partage suivant:
Action: Intent.ACTION_SEND ComponentName: {com.example.android.sharingshortcuts / com.example.android.sharingshortcuts.SendMessageActivity} Data: Uri to the shared content EXTRA_SHORTCUT_ID: <ID of the selected shortcut>
Si l'utilisateur ouvre la cible de partage à partir des raccourcis du lanceur d'applications, l'application reçoit l'intent créé lors de l'ajout du raccourci de partage à ShortcutManagerCompat.
Étant donné qu'il s'agit d'un autre intent, Intent.EXTRA_SHORTCUT_ID ne sera pas disponible, et vous devrez transmettre l'ID manuellement si vous en avez besoin.
Enregistrer l'utilisation des raccourcis pour les applications de communication
Si vous développez une application de communication, vous pouvez améliorer votre classement dans la Sharesheet Android en enregistrant l'utilisation des messages sortants et entrants.
Pour ce faire, publiez à nouveau le raccourci de conversation qui représente le contact via ShortcutManagerCompat.pushDynamicShortcut.
L'utilisation des raccourcis et les liaisons de fonctionnalités sont rétrocompatibles avec Android 5.0 (API 21).
Signaler l'utilisation des raccourcis pour les messages sortants
La création d'un rapport sur l'utilisation des messages envoyés par l'utilisateur est fonctionnellement semblable au clic sur le bouton "Envoyer" après avoir créé un message.
Pour déclencher des rapports d'utilisation, spécifiez des liaisons de fonctionnalités dans le raccourci via ShortcutInfoCompat.Builder#addCapabilityBinding avec la fonctionnalité actions.intent.SEND_MESSAGE.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Si le message sortant est destiné à une discussion de groupe, vous devez également ajouter la valeur du paramètre Audience, car le type recipient est associé à la fonctionnalité.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Enregistrer l'utilisation des raccourcis pour les messages entrants
Pour déclencher la création de rapports sur l'utilisation lorsque l'utilisateur reçoit un message tel qu'un SMS, un message Chat, un e-mail ou des notifications, vous devez également spécifier des liaisons de capacités dans le raccourci via ShortcutInfoCompat.Builder#addCapabilityBinding avec la capacité actions.intent.RECEIVE_MESSAGE.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Si le message entrant provient d'une discussion de groupe, vous devez également ajouter la valeur du paramètre Audience, car le type sender est associé à la fonctionnalité.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Utiliser AndroidX pour fournir à la fois des raccourcis de partage et des ChooserTargets
Pour pouvoir utiliser la bibliothèque de compatibilité AndroidX, le fichier manifeste de l'application doit contenir le sélecteur de métadonnées et l'ensemble de filtres d'intent. Consultez l'API Partage direct ChooserTargetService actuelle.
Ce service est déjà déclaré dans la bibliothèque de compatibilité. L'utilisateur n'a donc pas besoin de le déclarer dans le fichier manifeste de l'application. Toutefois, le lien de l'activité de partage au service doit être pris en compte en tant que fournisseur de cible de sélecteur.
Dans l'exemple suivant, l'implémentation de ChooserTargetService est androidx.core.content.pm.ChooserTargetServiceCompat, qui est déjà définie dans AndroidX:
<activity android:name=".SendMessageActivity" android:label="@string/app_name" android:theme="@style/SharingShortcutsDialogTheme"> <!-- This activity can respond to Intents of type SEND --> <intent-filter> <action android:name="android.intent.action.SEND" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="text/plain" /> </intent-filter> <!-- Only needed if you import the sharetarget AndroidX library that provides backwards compatibility with the old DirectShare API. The activity that receives the Sharing Shortcut intent needs to be taken into account with this chooser target provider. --> <meta-data android:name="android.service.chooser.chooser_target_service" android:value="androidx.sharetarget.ChooserTargetServiceCompat" /> </activity>
Questions fréquentes sur les raccourcis de partage
Comment sont stockées les données d'utilisation des raccourcis et quittent-elles l'appareil ?
Les raccourcis sont entièrement stockés sur l'appareil dans le répertoire de données système, dans une partition de disque chiffrée. Les informations des raccourcis, telles que l'icône, l'intent, ainsi que les noms des personnes et des ressources ne sont accessibles qu'aux services système et à la même application qui publie les raccourcis.
Quel est l'historique de la fonctionnalité Partage direct ?
Nous avons lancé le partage direct dans Android 6.0 (niveau d'API 23) pour permettre aux applications de fournir des objets ChooserTarget via un ChooserTargetService. Les résultats ont été récupérés de manière réactive à la demande, ce qui ralentit le temps de chargement des cibles.
Sous Android 10 (niveau d'API 29), nous avons remplacé les API de partage direct ChooserTargetService par la nouvelle API Sharing Shortcuts. Au lieu de récupérer les résultats de manière réactive à la demande, l'API Sharing Shortcuts permet aux applications de publier des cibles de partage direct à l'avance. Cela a considérablement accéléré le processus de récupération des cibles de partage direct lors de la préparation de la ShareSheet. Le mécanisme de partage direct ChooserTargetService continuera à fonctionner, mais le système classe les cibles fournies de cette manière en dessous de toute cible utilisant l'API de raccourcis de partage.
Android 11 (niveau d'API 30) a abandonné le service ChooserTargetService. L'API Sharing Shortcuts est le seul moyen de fournir des cibles de partage direct.
En quoi les raccourcis publiés pour les cibles de partage sont-ils différents des raccourcis du lanceur (utilisation typique des raccourcis lorsque vous appuyez de manière prolongée sur les icônes d'application dans le lanceur) ?
Tous les raccourcis publiés à des fins de "partage de cible" sont également des raccourcis de lanceur et s'affichent dans le menu lorsque vous appuyez de manière prolongée sur l'icône de votre application. La limite maximale du nombre de raccourcis par activité s'applique également au nombre total de raccourcis qu'une application publie (cibles de partage et anciens raccourcis du lanceur combinés).
Quels sont les conseils concernant le nombre de raccourcis de partage à publier ?
Le nombre de raccourcis de partage est limité à la même limite de raccourcis dynamiques disponibles via getMaxShortcutCountPerActivity(android.content.Context). Vous pouvez publier n'importe quel numéro jusqu'à cette limite, mais n'oubliez pas que les raccourcis de partage peuvent être visibles en appuyant de manière prolongée sur le lanceur d'applications et dans la feuille de partage. La plupart des lanceurs d'applications affichent un maximum de quatre ou cinq raccourcis en mode Portrait et huit en mode Paysage. Pour en savoir plus et obtenir des conseils sur le partage de raccourcis, consultez les questions fréquentes.