Spécifier des cibles de partage direct

Figure 1 : Ligne Partage direct dans Sharesheet, comme indiqué par 1

Utiliser les cibles de partage direct pour faciliter et accélérer le travail des utilisateurs d'autres applications pour partager des URL, des images ou d'autres types de données avec votre application. Le partage direct fonctionne en présentant vos contacts à partir d'applications de messagerie et de réseaux sociaux directement sur l'appareil Sharesheet, sans que les utilisateurs n'aient à sélectionner l'application ni à 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 moyen de publier à la fois les raccourcis de partage et ChooserTargets. Pour obtenir des instructions, Voir la section Utiliser AndroidX pour fournir à la fois des raccourcis de partage et des cibles de choix sur cette page.

Publier les cibles de partage direct

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

  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.

    Plus l'index est bas, plus l'importance est importante. Si vous faites une communication dans l'application, il peut s'agir de conversations principales, classées par récence au fur et à mesure qu'elles apparaissent votre application. Ne publiez pas de raccourcis obsolètes. une conversation sans l'activité des utilisateurs 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 l'utilisation des raccourcis via pushDynamicShortcut immédiatement chaque fois que l'utilisateur reçoit ou envoie un message à un contact. Voir Rapport sur l'utilisation des raccourcis pour applications de communication sur cette page. Par exemple, signalez l'utilisation des messages envoyés par l'utilisateur spécifiant des liaisons de fonctionnalité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);

  4. Si l'utilisateur supprime un contact, utilisez removeLongLivedShortcut Il s'agit de la méthode moyen de supprimer le raccourci, qu'il soit mis en cache par le système ou non services. 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 indique un nombre fixe de cibles de partage direct. Ces les suggestions sont triées par rang. Vous pouvez améliorer le classement 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, signaler l'utilisation des raccourcis pour les messages sortants et entrants en republiant les raccourcis correspondants à ShortcutManagerCompat.pushDynamicShortcut. Consultez Signaler l'utilisation des raccourcis pour les applications de communication à ce sujet. pour en savoir plus.
  • Évitez de fournir des cibles de partage direct non pertinentes ou obsolètes (par exemple, 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 numéros abrégés ou des conversations identifiés comme des spams potentiels. Il est peu probable que les utilisateurs partagent avec ces conversations.
  • Appelez setCategories() pour associer le raccourci au approprié mimeType caractéristiques. Par exemple : Pour une application de SMS, si le contact n'est pas compatible avec les RCS ou MMS, associer le raccourci correspondant à des types MIME non textuels tels que image/* et video/*.
  • Pour une conversation donnée, une fois qu'un raccourci dynamique est déployé et que l'utilisation est ne modifiez pas l'identifiant du raccourci. Les données d'utilisation sont ainsi conservées pour le classement.

Si l'utilisateur appuie sur une cible de partage direct, votre application doit le rediriger vers une interface utilisateur dans laquelle il peut effectuer une action directement sur le sujet de la cible. Ne pas présenter une interface utilisateur de sélection d'application, et ne les placez pas dans une interface utilisateur sans rapport avec cible tactile. Par exemple, dans une application de chat, vous pouvez appuyer sur cible redirige l'utilisateur vers une conversation avec la personne qu'il a sélectionnée. La clavier est visible et le message est prérempli avec les données partagées.

API Share 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 servent également à filtrer les raccourcis qui peuvent gérer des actions ou des intents de partage. Reportez-vous à la section Déclarer une action cible pour en savoir plus. Champ obligatoire pour les raccourcis destinées à être utilisées comme cibles de partage.
setLongLived()

Indique si un raccourci est valide ou non lorsqu'il a été annulé rendu invisible par l'application (sous forme de 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 si a été annulé en tant que raccourci dynamique.

Créer un raccourci de longue durée peut améliorer son classement. Consultez l'article Obtenir le meilleur classement.

setShortLabel(), setLongLabel()

Lorsque vous publiez un raccourci pour une seule personne, veuillez inclure son nom en setLongLabel() et tout nom court, comme 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 différentes surfaces du système et être remodelés. De plus, certains appareils équipés d'Android 7, 8 ou 9 (niveau d'API 25, 26, 27 et 28) peuvent afficher des icônes de type bitmap uniquement sans arrière-plan, ce qui réduit considérablement le contraste. Pour vous assurer que votre raccourci se présente comme prévu, fournir 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. Le moyen le plus courant d'y parvenir est de mettre à l'échelle le bitmap carré prévu pour 72 x 72 dp et centrez-la 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 zones transparentes apparaissent noires.

Ne fournissez pas d'images masquées selon une forme spécifique. Par exemple, avant Sous Android 10 (niveau d'API 29), il était courant de fournir des avatars aux utilisateurs pour le partage direct. ChooserTarget masqués dans un cercle. Android Sharesheet et autres les surfaces système d'Android 10 créent désormais des images de raccourci pour la forme et le thème. La méthode privilégiée pour fournir des raccourcis de partage, via ShortcutManagerCompat, configurer automatiquement les objets ChooserTarget de type "Partage direct" en rétrocompatibilité 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 les définitions de raccourcis statiques. Ajouter une part les définitions de cible 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ées, les catégories correspondantes et la classe cible qui gérera l'intent de partage. Le code XML ressemble à quelque chose comme 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 avoir Plusieurs catégories, qui ne sont utilisées que pour correspondre aux raccourcis publiés d'une application avec ses définitions de cible de partage. Les catégories peuvent avoir n'importe quelle catégorie définie par l'application valeurs.

Si l'utilisateur sélectionne le raccourci de partage dans Android Sharesheet qui correspond à l'exemple de partage cible ci-dessus, l'application obtiendra Intention de partage:

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 depuis les raccourcis du lanceur d'applications, l'application reçoit l'intent créé lors de l'ajout du raccourci de partage à ShortcutManagerCompat ; Comme il s'agit d'un intent différent, Intent.EXTRA_SHORTCUT_ID ne sera pas disponible. et vous devrez transmettre l'ID manuellement si nécessaire.

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 le Android Sharesheet en indiquant 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

D'un point de vue fonctionnel, l'utilisation de la création de rapports pour les messages envoyés par l'utilisateur est semblable à celle cliquez sur le bouton "Envoyer" après la création du message.

Pour déclencher les rapports sur l'utilisation, spécifiez des 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é à 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);

Signaler l'utilisation des raccourcis pour les messages entrants

Pour déclencher les rapports d'utilisation lorsque l'utilisateur reçoit un message (SMS, par exemple), les messages de chat, les e-mails ou les notifications, vous devez également spécifier la 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'un chat de groupe, vous devez également ajouter l'Audience valeur de paramètre comme type sender est associée à la capacité.

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 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-target-service et les filtres d'intent définis. Voir l'API Direct Share ChooserTargetService actuelle.

Ce service est déjà déclaré dans la bibliothèque de compatibilité. L'utilisateur le fait donc pas besoin de déclarer le service dans le fichier manifeste de l'application. Cependant, le lien de l'activité de partage avec le service doit être prise en compte en tant que cible du sélecteur. d'un fournisseur de services agréé.

Dans l'exemple suivant, l'implémentation de ChooserTargetService est androidx.core.content.pm.ChooserTargetServiceCompat, qui est déjà défini Sous 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 stockés entièrement sur l'appareil, dans le répertoire de données système partition de disque chiffrée. Les informations contenues dans les raccourcis tels que l'icône, l'intent et les noms de personnes et de ressources ne sont accessibles que par les services système la même application qui publie les raccourcis.

Quelle est l'histoire du partage direct ?

Nous avons lancé Direct Share 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ées de façon réactive à la demande, ce qui ralentit le temps de chargement des cibles.

Dans Android 10 (niveau d'API 29), nous avons remplacé la commande directe ChooserTargetService Partagez des API avec la nouvelle API Sharing Shortcuts. Au lieu de récupérer des résultats de façon réactive et à la demande, l'API Sharing Shortcuts permet aux applications de publier cibles à l'avance. Cela a rapidement accéléré le processus de récupération du partage direct cibles lors de la préparation de la ShareSheet. Le partage direct de ChooserTargetService mécanisme de sécurité continue de fonctionner, mais le système classe les cibles fournies ainsi qu'une cible qui utilise l'API Sharing Shortcuts.

Android 11 (niveau d'API 30) a rendu obsolète le service ChooserTargetService. 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 sont-ils différents du lanceur d'applications ? raccourcis (l'utilisation habituelle des raccourcis lorsque l'on appuie de manière prolongée sur les icônes d'application dans lanceur d'applications) ?

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 Le nombre maximal de raccourcis par activité s'applique également au nombre total raccourcis qu'une application publie (cibles de partage et anciens raccourcis de lanceur d'applications) combinés).

Quelle est la consigne concernant le nombre de raccourcis de partage qu'un utilisateur doit publier ?

Le nombre de raccourcis de partage est limité à la même limite de raccourcis raccourcis disponibles via getMaxShortcutCountPerActivity(android.content.Context) On peut publier à cette limite, mais vous devez garder à l'esprit que les raccourcis de partage dans le lanceur d'applications, appuyez de manière prolongée sur et dans la feuille de partage. La plupart des lanceurs d'applications activés appuyer de manière prolongée sur afficher un maximum de quatre ou cinq raccourcis en mode Portrait et huit en mode Paysage. Voir ceci Questions fréquentes pour en savoir plus et obtenir des conseils sur le partage des raccourcis.

Précédent
Recevoir des données simples depuis d'autres applications