Direct Share-Ziele angeben

Abbildung 1 : Zeile „Direct Share“ in Sharesheet, wie in 1

Mit Direct Share-Zielen können Nutzer anderer Apps einfacher und schneller URLs, Bilder oder andere Daten mit deiner App teilen. Dabei werden Kontakte aus Messaging- und sozialen Apps direkt im Android-Sharesheet präsentiert, ohne dass Nutzer die App auswählen und dann nach dem Kontakt suchen müssen.

Hinweis :Ab Android 11 (API-Level 30) kannst du Direct Share-Ziele nur über die Sharing Shortcuts API bereitstellen, die weiter unten auf dieser Seite beschrieben wird.

ShortcutManagerCompat ist eine AndroidX API, die Freigabeverknüpfungen bietet und mit der eingestellten ChooserTargetService API abwärtskompatibel ist. Dies ist die bevorzugte Methode, um sowohl Freigabeverknüpfungen als auch ChooserTargets zu veröffentlichen. Eine Anleitung dazu finden Sie auf dieser Seite unter Mit AndroidX sowohl Freigabeverknüpfungen als auch ChooserTargets bereitstellen.

Direct Share-Ziele veröffentlichen

In der Zeile „Sharesheet Direct Share“ werden nur dynamische Verknüpfungen angezeigt, die von der Sharing Shortcuts API bereitgestellt werden. So veröffentlichen Sie Direct Share-Ziele:

1. Deklariere in der XML-Ressourcendatei deiner App share-target-Elemente.

   <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. Verwende beim Initialisieren deiner App setDynamicShortcuts, um dynamische Verknüpfungen nach Wichtigkeit zu sortieren.

   Ein niedrigerer Index weist auf eine höhere Bedeutung hin. Wenn Sie eine Kommunikationsanwendung entwickeln, können die Top-Unterhaltungen nach Aktualität sortiert sein, wie sie in Ihrer App angezeigt werden. Veröffentlichen Sie keine veralteten Verknüpfungen. Eine Unterhaltung ohne Nutzeraktivität in den letzten 30 Tagen gilt als veraltet.

   Kotlin

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

   Java

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

3. Wenn Sie eine Kommunikations-App entwickeln, melden Sie die Nutzung der Kurzbefehle sofort über pushDynamicShortcut, sobald der Nutzer eine Nachricht an einen Kontakt erhält oder sendet. Weitere Informationen finden Sie unter Nutzung von Kurzbefehlen für Kommunikations-Apps melden auf dieser Seite. Sie können beispielsweise die Nutzung für vom Nutzer gesendete Nachrichten melden, indem Sie Funktionsbindungen in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Funktion actions.intent.SEND_MESSAGE angeben.

   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. Wenn der Nutzer einen Kontakt löscht, verwenden Sie removeLongLivedShortcut. Dies ist die bevorzugte Methode, um die Verknüpfung zu entfernen, unabhängig davon, ob sie von den Systemdiensten im Cache gespeichert wird. Das folgende Code-Snippet zeigt ein Beispiel, wie dies funktioniert.

   Kotlin

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
   

   Java

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));
   
   

Ranking der Direct Share-Ziele verbessern

Das Android Sharesheet zeigt eine feste Anzahl von Direct Share-Zielen an. Diese Vorschläge sind nach Rang sortiert. Sie können das Ranking Ihrer Verknüpfungen möglicherweise verbessern, indem Sie Folgendes tun:

• Achten Sie darauf, dass alle shortcutIds eindeutig sind und niemals für unterschiedliche Ziele wiederverwendet werden.
• Sorgen Sie dafür, dass die Verknüpfung langlebig ist, indem Sie setLongLived(true) aufrufen.
• Melden Sie die Nutzung von Tastenkombinationen für ausgehende und eingehende Nachrichten für Unterhaltungsverknüpfungen, indem Sie die entsprechenden Verknüpfungen über ShortcutManagerCompat.pushDynamicShortcut noch einmal veröffentlichen. Weitere Informationen finden Sie unter Nutzung von Kurzbefehlen für Kommunikations-Apps melden auf dieser Seite.
• Geben Sie keine irrelevanten oder veralteten Direct Share-Ziele an, z. B. Kontakte, denen der Nutzer in den letzten 30 Tagen keine Nachricht gesendet hat.
• Geben Sie bei SMS-Apps keine Kurzcodes für Kurzcodes oder Unterhaltungen an, die als potenzieller Spam identifiziert werden können. Es ist sehr unwahrscheinlich, dass Nutzer in diesen Unterhaltungen etwas teilen.
• Rufen Sie setCategories() auf, um die Verknüpfung mit den entsprechenden mimeType-Attributen zu verknüpfen. Wenn der Kontakt beispielsweise bei einer SMS-App nicht RCS oder MMS aktiviert ist, wird die entsprechende Verknüpfung nicht mit Nicht-Text-MIME-Typen wie image/* und video/* verknüpft.
• Ändern Sie die Verknüpfungs-ID für eine bestimmte Unterhaltung nicht, nachdem eine dynamische Verknüpfung gesendet und die Nutzung gemeldet wurde. Dadurch wird sichergestellt, dass Nutzungsdaten für das Ranking gespeichert werden.

Wenn der Nutzer auf ein Direct Share-Ziel tippt, muss er von Ihrer App zu einer Benutzeroberfläche weitergeleitet werden, auf der er eine Aktion direkt im Betreff des Ziels ausführen kann. Zeige dem Nutzer keine Benutzeroberfläche zur Begriffsklärung und platziere ihn nicht auf einer Benutzeroberfläche, die nichts mit dem angetippten Ziel zu tun hat. Wenn der Nutzer in einer Messaging-App beispielsweise auf ein Direct Share-Ziel tippt, wird er zu einer Konversationsansicht mit der ausgewählten Person weitergeleitet. Die Tastatur wird angezeigt und die Meldung ist mit den freigegebenen Daten vorausgefüllt.

Freigabe Shortcuts API

Ab Android 10 (API-Level 29) wurden in ShortcutInfo.Builder Methoden und Verbesserungen hinzugefügt, die zusätzliche Informationen zum Freigabeziel enthalten:

setCategories()

Ab Android 10 werden Kategorien auch zum Filtern von Verknüpfungen verwendet, die Freigabe-Intents oder -Aktionen verarbeiten können. Weitere Informationen finden Sie unter Freigabeziel deklarieren. Dieses Feld ist erforderlich, damit Verknüpfungen als Freigabeziele verwendet werden können.

setLongLived()

Gibt an, ob eine Verknüpfung gültig ist, wenn sie nicht veröffentlicht oder von der App unsichtbar wird (als dynamische oder angepinnte Verknüpfung). Wenn eine Verknüpfung lange gültig ist, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, auch nachdem sie nicht als dynamische Verknüpfung veröffentlicht wurde.

Wenn Sie eine Verknüpfung langlebiger machen, kann sich das Ranking verbessern. Weitere Informationen finden Sie unter Bestes Ranking erhalten.

setShortLabel(), setLongLabel()

Wenn du eine Verknüpfung für eine einzelne Person veröffentlichst, gib bitte den vollständigen Namen in setLongLabel() und einen beliebigen Kurznamen, z. B. einen Spitznamen oder Vornamen, in setShortLabel() an.

Ein Beispiel für die Veröffentlichung von Freigabeverknüpfungen auf GitHub

Bilder für Kurzbefehle bereitstellen

Wenn du eine Verknüpfung zum Teilen erstellen möchtest, musst du über setIcon() ein Bild hinzufügen.

Verknüpfungen zum Teilen können auf allen Systemoberflächen angezeigt und neu gestaltet werden. Außerdem werden auf einigen Geräten mit Android 7, 8 oder 9 (API-Level 25, 26, 27 und 28) möglicherweise reine Bitmapsymbole ohne Hintergrund angezeigt, was den Kontrast erheblich verringert. Damit die Verknüpfung wie gewünscht aussieht, können Sie mit IconCompat.createWithAdaptiveBitmap() eine adaptive Bitmap bereitstellen.

Achten Sie darauf, dass adaptive Bitmaps denselben Richtlinien und Abmessungen für adaptive Symbole entsprechen. Die am häufigsten verwendete Methode besteht darin, die beabsichtigte quadratische Bitmap auf 72 x 72 dp zu skalieren und sie innerhalb eines transparenten Canvas mit 108 x 108 dp zu zentrieren. Wenn Ihr Symbol transparente Bereiche enthält, müssen Sie eine Hintergrundfarbe hinzufügen. Andernfalls werden transparente Bereiche schwarz angezeigt.

Stellen Sie keine Bilder bereit, die in einer bestimmten Form maskiert sind. Vor Android 10 (API-Level 29) war es beispielsweise üblich, Nutzeravatare für Direct Share-ChooserTargets zur Verfügung zu stellen, die in einem Kreis verborgen waren. Das Android Sharesheet und andere Systemoberflächen in Android 10 sind jetzt mit Formen und Designverknüpfungen verknüpft. Die bevorzugte Methode zum Bereitstellen von Verknüpfungen zum Teilen über ShortcutManagerCompat ist, dass Backcompat-Direct Share-ChooserTarget-Objekte automatisch in Kreise umgewandelt werden.

Freigabeziel deklarieren

Freigabeziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie bei den Definitionen statischer Tastenkombinationen. Fügen Sie Definitionen zum Freigabeziel sowie andere statische Kurzbefehle im Stammelement <shortcuts> der Ressourcendatei hinzu. Jedes <share-targets>-Element enthält Informationen zum freigegebenen Datentyp, zu übereinstimmenden Kategorien und zur Zielklasse, die den Freigabe-Intent verarbeitet. Der XML-Code sieht in etwa so aus:

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

Das Datenelement in einem Ziel für die gemeinsame Nutzung ähnelt der Datenspezifikation in einem Intent-Filter. Jedes Freigabeziel kann mehrere Kategorien haben, die nur verwendet werden, um die veröffentlichten Verknüpfungen einer App den entsprechenden Definitionen der Freigabeziele zuzuordnen. Kategorien können beliebige App-definierte Werte haben.

Wenn der Nutzer im Android-Sharesheet die Verknüpfungsverknüpfung auswählt, die mit dem obigen Beispiel für die Zielfreigabe übereinstimmt, erhält die App den folgenden Share-Intent:

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>

Wenn der Nutzer das Freigabeziel über die Verknüpfungen im Launcher öffnet, erhält die App den Intent, der beim Hinzufügen der Verknüpfungsverknüpfung zu ShortcutManagerCompat erstellt wurde. Da es sich um einen anderen Intent handelt, ist Intent.EXTRA_SHORTCUT_ID nicht verfügbar und Sie müssen die ID bei Bedarf manuell übergeben.

Nutzung von Kurzbefehlen für Kommunikations-Apps melden

Wenn du eine Kommunikations-App entwickelst, kannst du dein Ranking im Android-Sharesheet verbessern, indem du die Nutzung sowohl für ausgehende als auch für eingehende Nachrichten meldest. Veröffentlichen Sie dazu die Verknüpfung für die Unterhaltung, die den Kontakt repräsentiert, über ShortcutManagerCompat.pushDynamicShortcut noch einmal.

Die Nutzung von Verknüpfungen und Funktionsbindungen ist abwärtskompatibel zu Android 5.0 (API 21).

Nutzung von Kurzbefehlen für ausgehende Nachrichten melden

Die Verwendung der Berichterstellung für vom Nutzer gesendete Nachrichten ähnelt der Funktion, mit der nach dem Erstellen einer Nachricht auf die Schaltfläche „Senden“ geklickt wird.

Wenn Sie Nutzungsberichte auslösen möchten, geben Sie Funktionsbindungen in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Funktion actions.intent.SEND_MESSAGE an.

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

Wenn sich die ausgehende Nachricht auf einen Gruppenchat bezieht, müssen Sie auch den Parameterwert Audience hinzufügen, da der Funktion der Typ recipient zugeordnet ist.

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

Nutzung von Kurzbefehlen für eingehende Nachrichten melden

Wenn Nutzungsberichte ausgelöst werden sollen, wenn der Nutzer eine SMS, Chatnachricht, E-Mail oder Benachrichtigung erhält, müssen Sie in der Verknüpfung zusätzlich über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Funktion actions.intent.RECEIVE_MESSAGE Funktionsbindungen angeben.

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

Wenn die eingehende Nachricht aus einem Gruppenchat stammt, müssen Sie auch den Parameterwert Audience hinzufügen, da der Typ sender der Funktion zugeordnet ist.

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

AndroidX verwenden, um sowohl Freigabeverknüpfungen als auch ChooserTargets bereitzustellen

Damit Sie mit der AndroidX-Kompatibilitätsbibliothek arbeiten können, muss das Manifest der App die festgelegten Metadaten-Auswahl- und Intent-Filter enthalten. Weitere Informationen finden Sie in der aktuellen ChooserTargetService Direct Share API.

Dieser Dienst ist bereits in der Kompatibilitätsbibliothek deklariert, sodass der Nutzer den Dienst nicht im Manifest der App deklarieren muss. Der Link von der Freigabeaktivität zum Dienst muss jedoch als Zielanbieter zur Auswahl berücksichtigt werden.

Im folgenden Beispiel ist die Implementierung von ChooserTargetService androidx.core.content.pm.ChooserTargetServiceCompat, was bereits in AndroidX definiert ist:

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

Häufig gestellte Fragen zum Teilen von Verknüpfungen

Wie werden die Nutzungsdaten der Verknüpfung gespeichert und verlassen sie das Gerät?

Verknüpfungen werden vollständig auf dem Gerät im Systemdatenverzeichnis in einer verschlüsselten Laufwerkpartition gespeichert. Informationen in Verknüpfungen wie das Symbol, der Intent und die Namen von Personen und Ressourcen sind nur für Systemdienste und die App zugänglich, die die Verknüpfungen veröffentlicht.

Was ist der bisherige Verlauf von Direct Share?

Wir haben Direct Share in Android 6.0 (API-Level 23) eingeführt, damit Apps ChooserTarget-Objekte über eine ChooserTargetService bereitstellen können. Die Ergebnisse wurden reaktiv bei Bedarf abgerufen, was zu einer langsamen Ladezeit für Ziele führte.

In Android 10 (API-Level 29) haben wir die ChooserTargetService Direct Share APIs durch die neue Sharing Shortcuts API ersetzt. Anstatt Ergebnisse reaktiv bei Bedarf abzurufen, können Apps mit der Sharing Shortcuts API Direct Share-Ziele im Voraus veröffentlichen. Dadurch wurde das Abrufen von Direct Share-Zielen bei der Vorbereitung der ShareSheet schnell beschleunigt. Der Direct Share-Mechanismus ChooserTargetService funktioniert zwar weiterhin, allerdings werden die so bereitgestellten Ziele vom System viel niedriger eingestuft als alle Ziele, für die die Sharing Shortcuts API verwendet wird.

Android 11 (API-Level 30) hat den Dienst ChooserTargetService eingestellt. Die Sharing Shortcuts API ist die einzige Möglichkeit, Direct Share-Ziele bereitzustellen.

Wie unterscheiden sich veröffentlichte Verknüpfungen für Freigabeziele von Verknüpfungen im Launcher (die typische Verwendung von Verknüpfungen, wenn lange auf App-Symbole im Launcher gedrückt wird)?

Alle Verknüpfungen, die für einen „Ziel teilen“-Zweck veröffentlicht wurden, sind auch eine Verknüpfung im Launcher und werden im Menü angezeigt, wenn du lange auf das Symbol deiner App drückst. Das Limit für die maximale Anzahl von Verknüpfungen pro Aktivität gilt auch für die Gesamtzahl der Verknüpfungen, die eine App veröffentlicht (gemeinsam genutzte Ziele und alte Launcher-Verknüpfungen).

Wie viele Tastenkombinationen zum Teilen sollte veröffentlicht werden?

Die Anzahl der Freigabeverknüpfungen ist auf dasselbe Limit für dynamische Verknüpfungen beschränkt, die über getMaxShortcutCountPerActivity(android.content.Context) verfügbar sind. Bis zu diesem Limit kann eine beliebige Anzahl veröffentlicht werden. Beachten Sie jedoch, dass die Freigabeverknüpfungen im App Launcher durch langes Drücken und im Freigabetabellenblatt sichtbar sein können. Die meisten App Launchers zeigen bei langem Drücken maximal vier oder fünf Tastenkombinationen im Hochformat und acht im Querformat an. Weitere Informationen und Anleitungen zum Teilen von Verknüpfungen finden Sie in diesen FAQs.