Spécifier des cibles de partage direct

Utilisez les cibles de partage direct pour permettre aux utilisateurs d'autres applications de partager des URL, des images ou d'autres types de données avec votre application. Le partage direct présente les contacts d'applications de messagerie et de réseaux sociaux directement sur la Sharesheet Android, sans que les utilisateurs n'aient à sélectionner l'application pour rechercher le contact.

ShortcutManagerCompat est une API AndroidX qui fournit des raccourcis de partage. Elle est rétrocompatible avec l'API obsolète ChooserTargetService. Il s'agit du moyen privilégié pour publier à la fois des raccourcis de partage et ChooserTargets. Pour obtenir des instructions, consultez Utiliser AndroidX pour fournir à la fois des raccourcis de partage et des cibles de sélection sur cette page.

Publier les cibles de partage direct

La ligne "Partage direct" de Sharesheet ne présente que les raccourcis dynamiques fournis par l'API de raccourcis de partage. Pour publier des cibles de partage direct, procédez comme suit :

1. 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>
   

2. Lorsque votre application s'initialise, utilisez setDynamicShortcuts pour classer les raccourcis dynamiques par importance.

   Un indice faible indique une plus grande importance. Si vous créez une application de communication, il peut s'agir des principales conversations classées par récence, telles qu'elles apparaissent dans votre application. Ne publiez pas de raccourcis obsolètes. Une conversation sans activité de l'utilisateur au cours des 30 derniers jours est considérée comme non actualisée.

   Kotlin

   ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
   

   Java

   List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
   shortcuts.add(shortcut1);
   shortcuts.add(shortcut2);
   ...
   ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
   
   

3. Si vous développez une application de communication, signalez immédiatement l'utilisation des raccourcis via pushDynamicShortcut chaque 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 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);
   

4. Si l'utilisateur supprime un contact, utilisez removeLongLivedShortcut. Il s'agit de la méthode privilégié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

Android Sharesheet affiche un nombre fixe de cibles de partage direct. Ces suggestions sont triées par classement. Vous pouvez potentiellement améliorer le classement de vos raccourcis en procédant comme suit:

• Assurez-vous que tous les shortcutIds sont uniques et ne sont jamais réutilisés pour différentes cibles.
• Assurez-vous que le raccourci a une longue durée de vie en appelant setLongLived(true).
• Pour les raccourcis liés aux conversations, signalez l'utilisation des raccourcis pour les messages sortants et entrants en republiant les raccourcis correspondants via ShortcutManagerCompat.pushDynamicShortcut. Pour en savoir plus, consultez Signaler 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, telles que des contacts auxquels l'utilisateur n'a pas envoyé de message au cours des 30 derniers jours.
• Pour les applications de SMS, évitez de fournir des raccourcis pour des codes courts ou des conversations identifiées comme spam potentiel. Il est très peu probable que les utilisateurs partagent ces conversations.
• Appelez setCategories() pour associer le raccourci aux attributs mimeType appropriés. Par exemple, pour une application SMS, si le contact n'est pas compatible RCS ou MMS, vous n'associez pas le raccourci correspondant à des types MIME non textuels tels que image/* et video/*.
• Pour une conversation donnée, une fois qu'un raccourci dynamique a été transmis et que son utilisation est signalée, ne modifiez pas l'ID du raccourci. Cela garantit la conservation des données d'utilisation pour le classement.

Si l'utilisateur appuie sur une cible de partage direct, votre application doit le rediriger vers une interface utilisateur qui lui permet d'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 utilisée. Par exemple, dans une application de chat, le fait d'appuyer sur une cible de partage direct redirige l'utilisateur vers un mode 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 partage des raccourcis

À 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 du partage:

setCategories()

À partir d'Android 10, les catégories sont également utilisées pour filtrer les raccourcis pouvant gérer les intents ou les 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()

Indique si un raccourci est valide lorsqu'il n'a pas été publié ou qu'il est rendu invisible par l'application (sous la forme d'un raccourci dynamique ou épinglé). Si un raccourci a une longue durée de vie, il peut être mis en cache par divers services système, même après annulation de sa publication en tant que raccourci dynamique.

Utiliser un raccourci de longue durée peut améliorer son classement. Pour en savoir plus, consultez 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 pseudo ou un prénom, dans setShortLabel().

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 les surfaces système et être modifiés. En outre, certains appareils équipés d'Android 7, 8 ou 9 (niveaux d'API 25, 26, 27 et 28) peuvent afficher des icônes uniquement bitmap 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 consignes et dimensions définies pour 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 régions 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 pour respecter une forme spécifique. Par exemple, avant Android 10 (niveau d'API 29), il était courant de fournir des avatars d'utilisateurs pour les ChooserTarget de partage direct masqués dans un cercle. Android Sharesheet et d'autres surfaces système d'Android 10 sont désormais des images de raccourcis de forme et de thème. La méthode privilégiée pour fournir des raccourcis de partage via ShortcutManagerCompat consiste à transformer automatiquement les objets ChooserTarget de backcompat Direct Share en cercles.

Déclarer 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, avec d'autres définitions de raccourci statique. Chaque élément <share-targets> contient des informations sur le type de données partagées, 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 cibles de partage. Les catégories peuvent avoir n'importe quelle valeur définie par l'application de manière arbitraire.

Si l'utilisateur sélectionne le raccourci de partage dans la Sharesheet Android qui correspond à l'exemple de partage cible ci-dessus, l'application obtiendra 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 obtiendra l'intent créé lors de l'ajout du raccourci de partage au ShortcutManagerCompat. Comme il s'agit d'un intent différent, Intent.EXTRA_SHORTCUT_ID n'est pas disponible. Vous devrez transmettre l'ID manuellement si vous en avez besoin.

Signaler l'utilisation des raccourcis pour les applis de communication

Si vous développez une application de communication, vous pouvez améliorer votre classement dans Android Sharesheet en enregistrant l'utilisation des messages sortants et entrants. Pour ce faire, republiez 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

D'un point de vue fonctionnel, l'utilisation des rapports pour les messages envoyés par l'utilisateur est semblable à celle consistant à cliquer 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.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

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 concerne un chat de groupe, vous devez également ajouter la valeur du paramètre Audience, car le type recipient est associé à la capacité.

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)

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);

Signaler l'utilisation des raccourcis pour les messages entrants

Pour déclencher des rapports d'utilisation lorsque l'utilisateur reçoit un message tel qu'un SMS, un message de chat, un e-mail ou une notification, vous devez également spécifier des liaisons de fonctionnalités dans le raccourci via ShortcutInfoCompat.Builder#addCapabilityBinding avec la fonctionnalité actions.intent.RECEIVE_MESSAGE.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

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'un chat de groupe, vous devez également ajouter la valeur du paramètre Audience, car le type sender est associé à la capacité.

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)

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 "ChooserCibles"

Pour pouvoir utiliser la bibliothèque de compatibilité AndroidX, le fichier manifeste de l'application doit contenir le sélecteur de métadonnées-target-service et les filtres d'intent définis. Consultez l'API Direct Share actuelle de ChooserTargetService.

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 entre l'activité de partage et le service doit être pris en compte en tant que fournisseur cible du sélecteur.

Dans l'exemple suivant, l'implémentation de ChooserTargetService est androidx.core.content.pm.ChooserTargetServiceCompat, qui est déjà défini 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 les données d'utilisation des raccourcis sont-elles stockées et quittent-elles l'appareil ?

Les raccourcis sont stockés entièrement sur l'appareil dans le répertoire de données système, au sein d'une partition de disque chiffrée. Les informations des raccourcis, telles que l'icône, l'intent et les noms des personnes et des ressources, ne sont accessibles que par les services système et l'application qui publie les raccourcis.

Quel est l'historique du partage direct ?

Nous avons introduit 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 étaient récupérés de manière réactive à la demande, ce qui ralentissait le temps de chargement des cibles.

Dans Android 10 (niveau d'API 29), nous avons remplacé les API Direct Share ChooserTargetService par la nouvelle API de raccourcis de partage. 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 rapidement 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 de fonctionner, mais le système classe les cibles fournies de cette manière moins souvent que toute cible utilisant l'API de raccourcis de partage.

Android 11 (niveau d'API 30) a abandonné le service ChooserTargetService, et l'API de raccourcis de partage est le seul moyen de fournir des cibles de partage direct.

En quoi les raccourcis publiés pour les cibles de partage diffèrent-ils des raccourcis du lanceur d'applications (utilisation typique des raccourcis lorsque l'utilisateur appuie de manière prolongée sur les icônes d'application dans le lanceur d'applications) ?

Tous les raccourcis publiés à des fins de "cible de partage" sont également un raccourci de lanceur. Ils s'affichent dans le menu lorsque vous appuyez de manière prolongée sur l'icône de votre application. La limite maximale de raccourcis par activité s'applique également au nombre total de raccourcis publiés par une application (cibles de partage et anciens raccourcis de lanceur d'applications combinés).

Quelles sont les recommandations concernant le nombre de raccourcis de partage qu'un utilisateur doit publier ?

Le nombre de raccourcis de partage est limité à la même limite que les 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 dans le lanceur d'applications en appuyant de manière prolongée sur l'écran, ainsi que dans la feuille de partage. La plupart des lanceurs d'applications en appuyant de manière prolongée 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 ces questions fréquentes.