Spécifier des cibles de partage direct

Figure 1  : Ligne "Partage direct" dans la feuille de partage, comme indiqué par 1

Utilisez les 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 fonctionne en présentant les contacts des applications de messagerie et sociales directement sur la feuille de partage 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. Il s'agit de la méthode à privilégier pour publier des raccourcis de partage et ChooserTargets. Pour obtenir des instructions, consultez Utiliser AndroidX pour fournir des raccourcis de partage et des ChooserTargets sur cette page.

Publier des cibles de partage direct

La ligne "Partage direct" de la feuille de partage n'affiche que les raccourcis dynamiques fournis par l'API Sharing Shortcuts. Suivez les étapes ci-dessous pour publier des cibles Direct Share.

  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 ordre d'importance.

    Un index plus faible indique une plus grande importance. Si vous créez une application de communication, il peut s'agir des conversations les plus récentes, telles qu'elles apparaissent 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);

  3. Si vous développez une application de communication, signalez l'utilisation des raccourcis via pushDynamicShortcut immédiatement chaque fois que l'utilisateur reçoit ou envoie un message à un contact. Pour en savoir plus, consultez Rapporter 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 les liaisons de capacité dans le raccourci via ShortcutInfoCompat.Builder#addCapabilityBinding avec la capacité 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 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 feuille de partage Android 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 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 republiant les raccourcis correspondants via ShortcutManagerCompat.pushDynamicShortcut. Pour en savoir plus, consultez Signaler l'utilisation de 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 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 les codes abrégés ou les conversations identifiées comme spam potentiel. Il est très peu probable que les utilisateurs partagent des contenus dans ces conversations.
  • Appelez setCategories() pour associer le raccourci aux attributs mimeType appropriés. Par exemple, pour une application de SMS, si le contact n'est pas compatible avec RCS ni MMS, vous n'associez pas le raccourci correspondant aux types MIME non textuels tels que image/* et video/*.
  • Pour une conversation donnée, une fois qu'un raccourci dynamique est envoyé et que son utilisation est signalée, ne modifiez pas son ID. 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 l'orienter vers une UI où il peut effectuer une action directement sur le sujet de la cible. Ne présentez pas d'interface utilisateur de désambiguïsation à l'utilisateur et ne le placez pas dans une interface utilisateur sans rapport avec la cible sélectionnée. Par exemple, dans une application de messagerie, appuyer sur une cible de partage direct redirige l'utilisateur vers une vue de 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 Sharing Shortcuts

À 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 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 a été non publié 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 différents services système, même après avoir été dépublié en tant que raccourci dynamique.

Rendre un raccourci durable 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 surnom ou un prénom, dans setShortLabel().

Consultez un exemple de publication de raccourcis de partage sur GitHub.

Fournir des images de raccourcis

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 redimensionné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 consignes et les dimensions définies pour les icônes adaptatives. La méthode la plus courante consiste à mettre à l'échelle le bitmap carré souhaité à 72x72 dp et à le centrer dans un canevas transparent de 108x108 dp. Si votre icône comporte des régions transparentes, vous devez inclure une couleur d'arrière-plan. Sinon, les régions transparentes s'affichent en noir.

Ne fournissez pas d'images masquées selon une forme spécifique. Par exemple, avant Android 10 (niveau d'API 29), il était courant de fournir des avatars utilisateur pour les ChooserTargets de partage direct masqués en forme de cercle. La feuille de partage Android et d'autres surfaces système d'Android 10 mettent désormais en forme et thématisent les images de raccourcis. La méthode recommandée pour fournir des raccourcis de partage, via ShortcutManagerCompat, met automatiquement en forme les objets ChooserTarget de partage direct rétrocompatibles en cercles pour vous.

Déclarer une cible de partage

Les cibles de partage doivent être déclarées dans le fichier de ressources de l'application, comme les définitions de raccourcis statiques. Ajoutez des définitions de cibles de partage à l'intérieur de l'élément racine <shortcuts> dans le 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ées, les catégories correspondantes et la classe cible qui gérera l'intention de partage. Le code XML ressemble à ceci :

<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 comporter plusieurs catégories, qui ne sont utilisées que pour faire correspondre les raccourcis publiés d'une application avec ses définitions de cibles 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 feuille de partage Android qui correspond à l'exemple de partage cible ci-dessus, l'application recevra l'intention de partage suivante :

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, l'application obtient l'intent créé lors de l'ajout du raccourci de partage à ShortcutManagerCompat. Comme il s'agit d'une intention différente, Intent.EXTRA_SHORTCUT_ID ne sera pas disponible et vous devrez transmettre l'ID manuellement si vous en avez besoin.

Signaler l'utilisation de raccourcis pour les applications de communication

Si vous développez une application de communication, vous pouvez améliorer votre classement dans la feuille de partage Android en signalant 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 capacités sont rétrocompatibles avec Android 5.0 (API 21).

Signaler l'utilisation de raccourcis pour les messages sortants

Le signalement de l'utilisation des messages envoyés par l'utilisateur est fonctionnellement similaire à l'action de cliquer sur le bouton "Envoyer" après avoir créé un message.

Pour déclencher le signalement de l'utilisation, spécifiez les liaisons de capacités dans le raccourci via ShortcutInfoCompat.Builder#addCapabilityBinding avec la capacité 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é à un chat 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);

Signaler l'utilisation de raccourcis pour les messages entrants

Pour déclencher le signalement de l'utilisation lorsque l'utilisateur reçoit un message tel qu'un SMS, un message instantané, un e-mail ou des notifications, vous devez également spécifier les liaisons de capacité 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 des raccourcis de partage et des ChooserTargets

Pour pouvoir utiliser la bibliothèque de compatibilité AndroidX, le fichier manifeste de l'application doit contenir les ensembles de métadonnées chooser-target-service et d'intent-filters. Consultez l'API Direct Share 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 entre l'activité de partage et le service doit être pris en compte en tant que fournisseur de cibles du 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 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 des données système, dans une partition de disque chiffrée. Les informations contenues dans les raccourcis, telles que l'icône, l'intention, ainsi que les noms des personnes et des ressources, ne sont accessibles qu'aux 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 entraînait un temps de chargement lent pour les cibles.

Dans Android 10 (niveau d'API 29), nous avons remplacé les API Direct Share 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 permis d'accélérer considérablement le processus de récupération des cibles de partage direct lors de la préparation de la feuille de partage. Le mécanisme de partage direct ChooserTargetService continuera de fonctionner, mais le système classera les cibles fournies de cette manière plus bas que toute cible utilisant l'API Sharing Shortcuts.

Android 11 (niveau d'API 30) a abandonné le service ChooserTargetService. L'API Sharing Shortcuts est désormais 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 (l'utilisation typique des raccourcis lorsque vous appuyez de manière prolongée sur les icônes d'application dans le lanceur d'applications) ?

Tout raccourci publié à des fins de "cible de partage" est également un raccourci du lanceur d'applications et s'affiche 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 d'applications combinés).

Quelles sont les consignes concernant le nombre de raccourcis de partage à publier ?

Le nombre de raccourcis de partage est limité au même nombre de raccourcis dynamiques disponibles via getMaxShortcutCountPerActivity(android.content.Context). Vous pouvez publier n'importe quel nombre dans cette limite, mais vous devez garder à l'esprit que les raccourcis partagés peuvent être visibles dans l'appui prolongé 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 ces questions fréquentes.