Direct Share-Ziele angeben

Mit Direct Share-Zielen können Nutzer anderer Apps URLs, Bilder oder andere Arten von Daten einfacher und schneller für Ihre App freigeben. Bei Direct Share werden Kontakte aus Messaging- und Social-Media-Apps direkt im Android-Freigabeblatt 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 mit der eingestellten ChooserTargetService API abwärtskompatibel ist. Dies ist die bevorzugte Methode zum Veröffentlichen von Sharing Shortcuts und ChooserTargets. Eine Anleitung finden Sie auf dieser Seite unter AndroidX verwenden, um Sharing Shortcuts und ChooserTargets bereitzustellen.

Direct Share-Ziele veröffentlichen

In der Zeile „Direct Share“ des Freigabeblatts 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 bedeutet eine höhere Wichtigkeit. Wenn Sie eine Kommunikations-App entwickeln, können Sie die wichtigsten Unterhaltungen nach Aktualität sortieren, so 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 Verknüpfungsnutzung sofort über pushDynamicShortcut, wenn der Nutzer eine Nachricht an einen Kontakt sendet oder von ihm erhält. Weitere Informationen finden Sie auf dieser Seite unter Verknüpfungsnutzung für Kommunikations-Apps melden. Melden Sie beispielsweise die Nutzung von Nachrichten, die vom Nutzer gesendet wurden, indem Sie über ShortcutInfoCompat.Builder#addCapabilityBinding mit der actions.intent.SEND_MESSAGE Funktion Funktionsbindungen in der Verknüpfung 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 zum Entfernen der Verknüpfung, unabhängig davon, ob sie von Systemdiensten im Cache gespeichert wird. Das folgende Codebeispiel zeigt, wie Sie das tun.

   Kotlin

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

   Java

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

Ranking 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 niemals für verschiedene Ziele wiederverwendet werden.
• Achten Sie darauf, dass die Verknüpfung langlebig ist, indem Sie setLongLived(true) aufrufen.
• Melden Sie für Verknüpfungen im Zusammenhang mit Unterhaltungen die Verknüpfungsnutzung für gesendete und empfangene Nachrichten, indem Sie entsprechende Verknüpfungen über ShortcutManagerCompat.pushDynamicShortcut neu veröffentlichen. Weitere Informationen finden Sie auf dieser Seite unter Verknüpfungsnutzung für Kommunikations-Apps melden.
• Vermeiden Sie es, irrelevante oder veraltete Direct Share-Ziele bereitzustellen, z. B. Kontakte, mit denen der Nutzer in den letzten 30 Tagen keine Nachrichten ausgetauscht hat.
• Vermeiden Sie bei SMS-Apps Verknüpfungen für Kurzwahlnummern oder Unterhaltungen, die als potenzieller Spam identifiziert wurden. Es ist sehr unwahrscheinlich, dass Nutzer diese Unterhaltungen teilen.
• Rufen Sie setCategories() auf, um die Verknüpfung den entsprechenden mimeType Attributen zuzuordnen. Wenn der Kontakt beispielsweise in einer SMS-App nicht für RCS oder MMS aktiviert ist, ordnen Sie die entsprechende Verknüpfung nicht Nicht-Text-MIME-Typen wie image/* und video/* zu.
• Ändern Sie die Verknüpfungs-ID nicht mehr, nachdem eine dynamische Verknüpfung für eine bestimmte Unterhaltung gesendet und die Nutzung gemeldet wurde. So bleiben die Nutzungsdaten für das Ranking erhalten.

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. Präsentieren Sie dem Nutzer keine Benutzeroberfläche zur Unterscheidung und leiten Sie ihn nicht zu einer Benutzeroberfläche weiter, die nicht mit dem ausgewählten Ziel zusammenhängt. Wenn der Nutzer beispielsweise in einer Messaging-App auf ein Direct Share-Ziel tippt, wird er zu einer Konversationsansicht mit der ausgewählten Person weitergeleitet. Die Tastatur ist sichtbar und die Nachricht ist mit den weitergegebenen Daten vorab ausgefüllt.

Sharing Shortcuts API

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

setCategories()

Ab Android 10 werden Kategorien auch verwendet, um Verknüpfungen zu filtern, die Freigabe-Intents oder -Aktionen verarbeiten können. Weitere Informationen finden Sie unter Freigabeziel 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 nicht mehr veröffentlicht oder ausgeblendet wurde (als dynamische oder angepinnte Verknüpfung). Wenn eine Verknüpfung langlebig ist, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, auch nachdem sie als dynamische Verknüpfung nicht mehr veröffentlicht wurde.

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

setShortLabel(), setLongLabel()

Wenn Sie eine Verknüpfung für eine bestimmte Person veröffentlichen, geben Sie ihren vollständigen Namen in setLongLabel() und einen Kurznamen wie einen Spitznamen oder einen Vornamen in setShortLabel() an.

Ein Beispiel für das Veröffentlichen von Sharing Shortcuts finden Sie auf GitHub.

Bilder für Verknüpfungen bereitstellen

Um eine Sharing Shortcut zu erstellen, müssen Sie über setIcon() ein Bild hinzufügen.

Sharing Shortcuts können auf verschiedenen Systemoberflächen angezeigt und möglicherweise 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 nur Bitmap-Symbole ohne Hintergrund angezeigt, was den Kontrast erheblich verringert. Damit Ihre Verknüpfung wie gewünscht aussieht, stellen Sie eine adaptive Bitmap mit IconCompat.createWithAdaptiveBitmap() bereit.

Adaptive Bitmaps müssen denselben Richtlinien und Abmessungen entsprechen, die für adaptive Symbole festgelegt wurden. Am häufigsten wird dazu die gewünschte quadratische Bitmap auf 72 × 72 dp skaliert und in einem transparenten 108 × 108 dp-Canvas zentriert. Wenn Ihr Symbol transparente Bereiche enthält, müssen Sie eine Hintergrundfarbe angeben. Andernfalls werden transparente Bereiche schwarz angezeigt.

Stellen Sie keine Bilder bereit, die auf eine bestimmte Form maskiert sind. Vor Android 10 (API-Level 29) war es beispielsweise üblich, Nutzeravatare für Direct Share-ChooserTargets bereitzustellen, die auf einen Kreis maskiert waren. Im Android-Freigabeblatt und auf anderen Systemoberflächen in Android 10 werden die Bilder von Verknüpfungen jetzt geformt und mit einem Design versehen. Bei der bevorzugten Methode zum Bereitstellen von Sharing Shortcuts über ShortcutManagerCompat, werden Direct Share ChooserTarget-Objekte automatisch in Kreise umgewandelt, um die Abwärtskompatibilität zu gewährleisten.

Freigabeziel deklarieren

Freigabeziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie Definitionen statischer Verknüpfungen. Fügen Sie Definitionen für Freigabe ziele im <shortcuts> Stammelement in der Ressourcendatei zusammen mit anderen Definitionen statischer Verknüpfungen hinzu. Jedes <share-targets> Element enthält Informationen zum weitergegebenen 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 Freigabeziel ä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 mit ihren Definitionen für Freigabeziele abzugleichen. Kategorien können beliebige von der App definierte Werte haben.

Wenn der Nutzer im Android-Freigabeblatt die Sharing Shortcut auswählt, die mit dem oben genannten Beispiel für das Freigabeziel übereinstimmt, erhält die App den folgenden Freigabe-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 Launcher-Verknüpfungen öffnet, erhält die App den Intent, der beim Hinzufügen der Verknüpfung zum Teilen zu ShortcutManagerCompat erstellt wurde. Da es sich um einen anderen Intent handelt, ist Intent.EXTRA_SHORTCUT_ID nicht verfügbar. Sie müssen die ID manuell übergeben, wenn Sie sie benötigen.

Verknüpfungsnutzung für Kommunikations-Apps melden

Wenn Sie eine Kommunikations-App entwickeln, können Sie Ihr Ranking im Android-Freigabeblatt verbessern, indem Sie die Nutzung für gesendete und empfangene Nachrichten melden. Veröffentlichen Sie dazu die Unterhaltungsverknüpfung, die den Kontakt darstellt, über ShortcutManagerCompat.pushDynamicShortcut neu.

Die Verknüpfungsnutzung und die Funktionsbindungen sind abwärtskompatibel mit Android 5.0 (API-Level 21).

Verknüpfungsnutzung für gesendete Nachrichten melden

Die Meldung der Nutzung von Nachrichten, die vom Nutzer gesendet wurden, ähnelt funktional dem Klicken auf die Schaltfläche „Senden“ nach dem Erstellen einer Nachricht.

Um die Nutzungsmeldung auszulösen, geben Sie über ShortcutInfoCompat.Builder#addCapabilityBinding mit der actions.intent.SEND_MESSAGE Funktion Funktionsbindungen in der Verknüpfung 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 Audience Parameterwert hinzufügen, da der recipient Typ 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);

Verknüpfungsnutzung für empfangene Nachrichten melden

Um die Nutzungsmeldung auszulösen, wenn der Nutzer eine Nachricht wie eine SMS, eine Chatnachricht, eine E-Mail oder Benachrichtigungen erhält, müssen Sie zusätzlich über ShortcutInfoCompat.Builder#addCapabilityBinding mit der actions.intent.RECEIVE_MESSAGE Funktion Funktionsbindungen in der Verknüpfung 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 Audience Parameterwert hinzufügen, da der sender Typ 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 Sharing Shortcuts und ChooserTargets bereitzustellen

Damit Sie mit der AndroidX-Kompatibilitätsbibliothek arbeiten können, muss das Manifest der App die Metadaten „chooser-target-service“ und die festgelegten 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 ihn nicht im Manifest der App deklarieren muss. Die Verknüpfung von der Freigabeaktivität zum Dienst muss jedoch als Anbieter von Chooser-Zielen berücksichtigt werden.

Im folgenden Beispiel ist die Implementierung von ChooserTargetService ist androidx.core.content.pm.ChooserTargetServiceCompat, die bereits definiert in AndroidX 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 Sharing Shortcuts

Wie werden die Daten zur Verknüpfungsnutzung 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, der Intent und die Namen von Personen und Ressourcen sind nur für Systemdienste und dieselbe App zugänglich, die die Verknüpfungen veröffentlicht.

Was ist die Geschichte von Direct Share?

Wir haben Direct Share in Android 6.0 (API-Level 23) eingeführt, damit Apps bereitstellen ChooserTarget Objekte über einen ChooserTargetService. 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 Direct Share APIs durch die neue Sharing Shortcuts API ersetzt. Anstatt Ergebnisse reaktiv auf Anfrage abzurufen, können Apps mit der Sharing Shortcuts API Direct Share-Ziele im Voraus veröffentlichen. Dadurch wurde der Abruf von Direct Share-Zielen beim Vorbereiten des Freigabeblatts erheblich beschleunigt. Der ChooserTargetService Direct Share-Mechanismus 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 „Freigabeziel“ veröffentlicht wurden, sind auch Launcher-Verknüpfungen und werden im Menü angezeigt, wenn Sie lange auf das Symbol Ihrer App drücken. 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 (Freigabeziele und ältere Launcher-Verknüpfungen zusammen).

Wie viele Sharing Shortcuts sollten veröffentlicht werden?

Die Anzahl der Sharing Shortcuts ist auf dasselbe Limit für dynamische Verknüpfungen beschränkt, das über getMaxShortcutCountPerActivity(android.content.Context) verfügbar ist. Sie können eine beliebige Anzahl bis zu diesem Limit veröffentlichen, müssen aber bedenken, dass Verknüpfungen zum Teilen im App-Launcher beim langen Drücken und im Freigabeblatt sichtbar sein können. Die meisten App-Launcher zeigen beim langen Drücken im Hochformat maximal vier oder fünf Verknüpfungen und im Querformat acht Verknüpfungen an. Weitere Informationen und Anleitungen zu Sharing Shortcuts finden Sie in diesen häufig gestellten Fragen.