Direct Share-Ziele angeben

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

ShortcutManagerCompat ist eine AndroidX API, die Sharing Shortcuts bereitstellt und abwärtskompatibel mit der eingestellten ChooserTargetService API ist. Das ist die bevorzugte Methode, um sowohl Kurzbefehle zum Teilen als auch ChooserTargets zu veröffentlichen. Eine Anleitung finden Sie auf dieser Seite unter AndroidX verwenden, um sowohl Sharing Shortcuts als auch ChooserTargets bereitzustellen.

„Direct Share“-Ziele veröffentlichen

In der Zeile „Direct Share“ im Freigabeblatt werden nur dynamische Verknüpfungen angezeigt, die von der Sharing Shortcuts API bereitgestellt werden. Führen Sie die folgenden Schritte aus, um Direct Share-Ziele zu veröffentlichen.

1. Deklarieren Sie in der XML-Ressourcendatei Ihrer 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. Verwenden Sie beim Initialisieren Ihrer App setDynamicShortcuts, um dynamische Verknüpfungen nach Wichtigkeit zu sortieren.

   Ein niedrigerer Index weist auf eine höhere Wichtigkeit hin. Wenn Sie eine Kommunikations-App entwickeln, können Sie die wichtigsten Unterhaltungen nach Aktualität sortieren, 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 Verwendung von Verknüpfungen über pushDynamicShortcut, sobald der Nutzer eine Nachricht an einen Kontakt empfängt oder sendet. Weitere Informationen finden Sie auf dieser Seite unter Verwendung von Tastenkombinationen für Kommunikations-Apps melden. Sie können beispielsweise die Nutzung für Nachrichten melden, die vom Nutzer gesendet wurden, indem Sie die Capability-Bindungen im Shortcut über ShortcutInfoCompat.Builder#addCapabilityBinding mit der actions.intent.SEND_MESSAGE-Capability 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, verwende removeLongLivedShortcut. Das ist die bevorzugte Methode zum Entfernen der Verknüpfung, unabhängig davon, ob sie von Systemdiensten im Cache gespeichert wurde. Das folgende Code-Snippet zeigt ein Beispiel dafür.

   Kotlin

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

   Java

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

Rangfolge Ihrer „Direct Share“-Ziele verbessern

Im Android Sharesheet wird eine feste Anzahl von Direct Share-Zielen angezeigt. 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 nie für verschiedene Ziele wiederverwendet werden.
• Rufen Sie setLongLived(true) auf, um sicherzustellen, dass die Verknüpfung lange gültig ist.
• Für konversationsbezogene Verknüpfungen müssen Sie die Verwendung von Verknüpfungen für ausgehende und eingehende Nachrichten melden, indem Sie die entsprechenden Verknüpfungen über ShortcutManagerCompat.pushDynamicShortcut neu veröffentlichen. Weitere Informationen finden Sie auf dieser Seite unter Verwendung von Tastenkombinationen für Kommunikations-Apps melden.
• Vermeiden Sie es, irrelevante oder veraltete Direct Share-Ziele anzugeben, z. B. Kontakte, mit denen der Nutzer in den letzten 30 Tagen nicht kommuniziert hat.
• Vermeiden Sie bei SMS-Apps die Bereitstellung von Verknüpfungen für Kurzwahlnummern oder Unterhaltungen, die als potenzieller Spam identifiziert wurden. Es ist sehr unwahrscheinlich, dass Nutzer Inhalte in diesen Unterhaltungen teilen.
• Rufen Sie setCategories() auf, um die Verknüpfung der Verknüpfung mit den entsprechenden mimeType-Attributen herzustellen. Wenn es sich beispielsweise um eine SMS-App handelt und der Kontakt nicht für RCS oder MMS aktiviert ist, sollten Sie die entsprechende Verknüpfung nicht mit nicht textbasierten MIME-Typen wie image/* und video/* verknüpfen.
• Ändern Sie die Shortcut-ID für eine bestimmte Konversation nicht, nachdem ein dynamischer Shortcut gesendet und die Nutzung gemeldet wurde. So werden Nutzungsdaten für das Ranking beibehalten.

Wenn der Nutzer auf ein Direct Share-Ziel tippt, muss Ihre App ihn zu einer Benutzeroberfläche weiterleiten, auf der er eine Aktion direkt für das Ziel ausführen kann. Zeigen Sie dem Nutzer keine Benutzeroberfläche zur Mehrdeutigkeitsauflösung und keine Benutzeroberfläche, die nicht mit dem angetippten Ziel zusammenhängt. Wenn ein Nutzer beispielsweise in einer Messaging-App auf ein Direct Share-Ziel tippt, wird er zu einer Unterhaltungsansicht mit der ausgewählten Person weitergeleitet. Die Tastatur ist sichtbar und die Nachricht ist mit den freigegebenen Daten vorausgefüllt.

Sharing Shortcuts API

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

setCategories()

Ab Android 10 werden Kategorien auch verwendet, um Verknüpfungen zu filtern, die Share-Intents oder ‑Aktionen verarbeiten können. Weitere Informationen finden Sie unter Freigabe-Ziel deklarieren. Dieses Feld ist für Verknüpfungen erforderlich, die als Freigabeziele verwendet werden sollen.

setLongLived()

Gibt an, ob eine Verknüpfung gültig ist, wenn sie von der App (als dynamische oder angepinnte Verknüpfung) zurückgezogen oder unsichtbar gemacht wurde. Wenn eine Verknüpfung lange aktiv ist, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, auch nachdem sie als dynamische Verknüpfung deaktiviert wurde.

Wenn Sie eine Verknüpfung lange aktiv lassen, kann sich ihr Ranking verbessern. Weitere Informationen

setShortLabel(), setLongLabel()

Wenn Sie ein Tastenkürzel für eine einzelne Person veröffentlichen, geben Sie den vollständigen Namen in setLongLabel() und einen Kurznamen wie einen Spitznamen oder einen Vornamen in setShortLabel() an.

Beispiel für das Veröffentlichen von Sharing-Shortcuts auf GitHub

Bilder für Verknüpfungen bereitstellen

Wenn Sie eine Freigabe-Verknüpfung erstellen möchten, müssen Sie über setIcon() ein Bild hinzufügen.

Freigabe-Shortcuts können auf allen Systemoberflächen angezeigt und neu angeordnet werden. Außerdem werden auf einigen Geräten mit Android 7, 8 oder 9 (API-Ebenen 25, 26, 27 und 28) möglicherweise nur Bitmap-Symbole ohne Hintergrund angezeigt, was den Kontrast erheblich verringert. Damit Ihr Shortcut wie gewünscht aussieht, stellen Sie ein adaptives Bitmap mit IconCompat.createWithAdaptiveBitmap() bereit.

Achten Sie darauf, dass adaptive Bitmaps denselben Richtlinien und Abmessungen wie adaptive Symbole entsprechen. Am häufigsten wird dazu das quadratische Bitmap auf 72 × 72 dp skaliert und auf einem transparenten Canvas mit 108 × 108 dp zentriert. Wenn Ihr Symbol transparente Bereiche enthält, müssen Sie eine Hintergrundfarbe angeben. Andernfalls werden transparente Bereiche schwarz dargestellt.

Bilder dürfen nicht auf eine bestimmte Form maskiert sein. Vor Android 10 (API-Level 29) war es beispielsweise üblich, Nutzeravatare für Direct Share-ChooserTargets bereitzustellen, die als Kreis maskiert wurden. Das Android Sharesheet und andere Systemoberflächen in Android 10 passen die Form und das Design von Verknüpfungsbildern an. Die bevorzugte Methode zum Bereitstellen von Freigabe-Shortcuts über ShortcutManagerCompat ist, dass Direct Share-ChooserTarget-Objekte automatisch in Kreise umgewandelt werden.

Freigabeziel deklarieren

Share-Ziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie Definitionen statischer Verknüpfungen. Fügen Sie die Definitionen für das Freigabeziel in der Ressourcendatei in das Stammelement <shortcuts> ein, zusammen mit anderen statischen Verknüpfungsdefinitionen. Jedes <share-targets>-Element enthält Informationen zum freigegebenen Datentyp, zu übereinstimmenden Kategorien und zur Zielklasse, die den Share-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 Freigabe-Ziel ist ähnlich der Datenspezifikation in einem Intent-Filter. Jedes Share-Ziel kann mehrere Kategorien haben, die nur verwendet werden, um die veröffentlichten Verknüpfungen einer App mit den Definitionen des Share-Ziels abzugleichen. Kategorien können beliebige app-definierte Werte haben.

Wenn der Nutzer im Android-Sharesheet die Freigabeverknüpfung auswählt, die dem oben genannten Beispiel für die Zielfreigabe entspricht, erhält die App die folgende Freigabe-Intention:

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 Freigabe-Ziel über die Launcher-Verknüpfungen öffnet, erhält die App den Intent, der beim Hinzufügen der Freigabe-Verknüpfung zu ShortcutManagerCompat erstellt wurde. Da es sich um eine andere Intention handelt, ist Intent.EXTRA_SHORTCUT_ID nicht verfügbar und Sie müssen die ID manuell übergeben, wenn Sie sie benötigen.

Verwendung von Tastenkombinationen für Kommunikations-Apps melden

Wenn Sie eine Kommunikations-App entwickeln, können Sie Ihr Ranking im Android-Sharesheet verbessern, indem Sie die Nutzung sowohl für ausgehende als auch für eingehende Nachrichten melden. Dazu müssen Sie die Gesprächsverknüpfung, die den Kontakt repräsentiert, über ShortcutManagerCompat.pushDynamicShortcut neu veröffentlichen.

Die Verwendung von Verknüpfungen und die Bindung von Funktionen sind abwärtskompatibel mit Android 5.0 (API 21).

Tastenkombinationen für ausgehende Nachrichten melden

Die Meldung der Nutzung für Nachrichten, die vom Nutzer gesendet werden, ist funktional ähnlich wie das Klicken auf die Schaltfläche „Senden“ nach dem Erstellen einer Nachricht.

Wenn Sie die Nutzungsberichterstellung auslösen möchten, geben Sie die Capability-Bindungen in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding mit der actions.intent.SEND_MESSAGE-Capability an.

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

Wenn die ausgehende Nachricht für einen Gruppenchat bestimmt ist, müssen Sie auch den Parameterwert Audience hinzufügen, da der Typ recipient mit der Funktion verknüpft ist.

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

Verwendung von Tastenkombinationen für eingehende Nachrichten melden

Damit die Nutzungsberichterstellung ausgelöst wird, wenn der Nutzer eine Nachricht wie eine SMS, eine Chat-Nachricht, eine E-Mail oder Benachrichtigungen erhält, müssen Sie zusätzlich die Fähigkeitsbindungen im Shortcut über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Fähigkeit actions.intent.RECEIVE_MESSAGE angeben.

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

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

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

AndroidX verwenden, um sowohl Sharing Shortcuts als auch ChooserTargets bereitzustellen

Damit Sie mit der AndroidX-Kompatibilitätsbibliothek arbeiten können, muss das Manifest der App die Metadaten „chooser-target-service“ und „intent-filters“ 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 für die Auswahl berücksichtigt werden.

Im folgenden Beispiel ist die Implementierung von ChooserTargetService androidx.core.content.pm.ChooserTargetServiceCompat, die 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 zu Kurzbefehlen zum Teilen

Wie werden die Daten zur Verwendung von Verknüpfungen gespeichert und verlassen sie das Gerät?

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

Was ist die Funktion „Direkt teilen“?

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 auf Anfrage abgerufen, was zu einer langsamen Ladezeit für Ziele führte.

In Android 10 (API-Level 29) haben wir die ChooserTargetService-DirectShare-APIs durch die neue Sharing Shortcuts API ersetzt. Mit der Sharing Shortcuts API können Apps Direct Share-Ziele im Voraus veröffentlichen, anstatt Ergebnisse reaktiv auf Anfrage abzurufen. Dadurch wurde das Abrufen von Direct Share-Zielen beim Vorbereiten des ShareSheets erheblich beschleunigt. Der ChooserTargetService-Mechanismus für Direct Share funktioniert weiterhin, aber das System stuft Ziele, die auf diese Weise bereitgestellt werden, niedriger ein als Ziele, die die Sharing Shortcuts API verwenden.

In Android 11 (API‑Level 30) wurde der 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 Launcher-Verknüpfungen (die typische Verwendung von Verknüpfungen beim langen Drücken auf App-Symbole im Launcher)?

Alle Verknüpfungen, die für ein „Share Target“ veröffentlicht werden, sind auch Launcher-Verknüpfungen und werden im Menü angezeigt, wenn Sie das App-Symbol lange gedrückt halten. Das maximale Limit für die Anzahl der Verknüpfungen pro Aktivität gilt auch für die Gesamtzahl der Verknüpfungen, die eine App veröffentlicht (Kombination aus Share-Zielen und alten Launcher-Verknüpfungen).

Wie viele Freigabe-Shortcuts sollten veröffentlicht werden?

Die Anzahl der Freigabe-Shortcuts ist auf dieselbe Anzahl dynamischer Shortcuts begrenzt, die über getMaxShortcutCountPerActivity(android.content.Context) verfügbar sind. Es können beliebig viele Shortcuts bis zu diesem Limit veröffentlicht werden. Allerdings muss berücksichtigt werden, dass geteilte Shortcuts im App-Launcher bei langem Drücken und im Freigabe-Sheet sichtbar sein können. Die meisten App-Starter zeigen bei langem Drücken im Hochformat maximal vier oder fünf Verknüpfungen und im Querformat acht Verknüpfungen an. Weitere Informationen und Anleitungen zum Teilen von Tastenkombinationen finden Sie in diesen FAQs.