Direct Share-Ziele angeben

)

Mit Direktfreigabe-Zielen können Nutzer anderer Apps URLs, Bilder oder andere Daten einfacher und schneller mit Ihrer App teilen. Bei der Direktfreigabe werden Kontakte aus Messaging- und Social-Media-Apps direkt in der Android-Freigabeliste angezeigt, ohne dass Nutzer die App auswählen und dann nach dem Kontakt suchen müssen.

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

Ziele für die direkte Freigabe veröffentlichen

In der Zeile „Direkte Freigabe“ des Freigabebereichs werden nur dynamische Verknüpfungen angezeigt, die von der Sharing Shortcuts API bereitgestellt werden. Führen Sie die folgenden Schritte aus, um Ziele für die direkte Freigabe 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. Wenn Ihre App initialisiert wird, können Sie mit setDynamicShortcuts dynamische Verknüpfungen nach Wichtigkeit sortieren.

   Je niedriger der Index, desto wichtiger ist die Information. Wenn Sie eine Kommunikations-App entwickeln, können Sie die Top-Unterhaltungen nach Aktualität sortieren, wie sie in Ihrer App angezeigt werden. Veröffentlichen Sie keine veraltete Verknüpfungen. Eine Unterhaltung, in der in den letzten 30 Tagen keine Nutzeraktivität stattgefunden hat, 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 Tastenkürzeln über pushDynamicShortcut sofort, wenn der Nutzer eine Nachricht von einem Kontakt erhält oder an einen Kontakt sendet. Weitere Informationen finden Sie auf dieser Seite unter Verwendung von Tastenkürzeln für Kommunikations-Apps melden. Sie können beispielsweise die Nutzung von Nachrichten erfassen, die vom Nutzer gesendet wurden, indem Sie im Shortcut über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Funktion actions.intent.SEND_MESSAGE Bindungen für Funktionen 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 empfohlene Methode, um die Verknüpfung zu entfernen, unabhängig davon, ob sie von Systemdiensten im Cache gespeichert ist. 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));
   
   

Ranking der Ziele für die direkte Freigabe verbessern

Das Android-Teilen-Menü zeigt eine feste Anzahl von Direktfreigabezielen an. Diese Vorschläge sind nach Rang sortiert. So können Sie das Ranking Ihrer Verknüpfungen möglicherweise verbessern:

• Alle shortcutIds-Elemente müssen eindeutig sein und dürfen nicht für verschiedene Ziele wiederverwendet werden.
• Rufen Sie setLongLived(true) auf, damit der Verknüpfung eine lange Lebensdauer zugewiesen wird.
• Wenn Sie die Verwendung von Tastenkürzeln für ausgehende und eingehende Nachrichten melden möchten, die sich auf eine Unterhaltung beziehen, veröffentlichen Sie die entsprechenden Tastenkürzel über ShortcutManagerCompat.pushDynamicShortcut noch einmal. Weitere Informationen finden Sie auf dieser Seite unter Nutzung von Tastenkürzeln für Kommunikations-Apps melden.
• Geben Sie keine irrelevanten oder veralteten Ziele für die direkte Freigabe an, z. B. Kontakte, mit denen der Nutzer in den letzten 30 Tagen nicht gechattet hat.
• Bei SMS-Apps sollten Sie keine Tastenkürzel für Kurzwahlnummern oder Unterhaltungen angeben, die als potenzieller Spam eingestuft wurden. Die Wahrscheinlichkeit, dass Nutzer Inhalte in diesen Unterhaltungen teilen, ist äußerst gering.
• Rufen Sie setCategories() auf, um den Verknüpfung die entsprechenden mimeType-Attribute zuzuweisen. Wenn der Kontakt beispielsweise für eine SMS-App nicht RCS- oder MMS-fähig ist, sollten Sie den entsprechenden Shortcut nicht mit MIME-Typen für andere Medien als Text wie image/* und video/* verknüpfen.
• Ändern Sie die Tastenkürzel-ID für eine bestimmte Unterhaltung nicht, nachdem ein dynamischer Tastenkürzel gesendet und die Nutzung erfasst wurde. So bleiben 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 auf das Subjekt des Ziels ausführen kann. Zeigen Sie dem Nutzer keine Benutzeroberfläche zur Klärung von Mehrdeutigkeiten an und leiten Sie ihn nicht zu einer Benutzeroberfläche weiter, die nichts mit dem angetippten Ziel zu tun hat. Wenn Nutzer in einer Messaging-App auf ein Ziel für die direkte Freigabe tippen, werden sie beispielsweise zu einer Konversationsansicht 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-Ebene 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 Intents oder Aktionen für die Freigabe verarbeiten können. Weitere Informationen finden Sie unter Teilen-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 veröffentlicht oder unsichtbar gemacht wurde (als dynamische oder angepinnte Verknüpfung). Wenn eine Verknüpfung eine lange Lebensdauer hat, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, auch nachdem sie als dynamische Verknüpfung veröffentlicht wurde.

Wenn Sie einen dauerhaften Verknüpfungslink erstellen, kann sich das positiv auf das Ranking auswirken. Weitere Informationen finden Sie unter Den besten Rang erzielen.

setShortLabel(), setLongLabel()

Wenn Sie einen Verknüpfungs-Shortcut zu einer einzelnen Person veröffentlichen, geben Sie in setLongLabel() den vollständigen Namen und in setShortLabel() einen Kurznamen wie einen Alias oder einen Vornamen an.

Hier finden Sie ein Beispiel für die Veröffentlichung von Freigabeverknüpfungen auf GitHub.

Bilder für Verknüpfungen bereitstellen

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

Tastenkürzel für die Freigabe können auf verschiedenen Systemoberflächen angezeigt werden und können angepasst werden. Außerdem werden auf einigen Geräten mit Android-Versionen 7, 8 oder 9 (API-Ebenen 25, 26, 27 und 28) möglicherweise nur Bitmap-Symbole ohne Hintergrund angezeigt, was den Kontrast drastisch verringert. Damit Ihr Shortcut wie vorgesehen aussieht, sollten Sie eine adaptive Bitmap mit IconCompat.createWithAdaptiveBitmap() bereitstellen.

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

Verwenden Sie keine Bilder, 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 in einem Kreis maskiert waren. Das Android-Teilen-Menü und andere Systemoberflächen in Android 10 haben jetzt ein einheitliches Design für Verknüpfungsbilder. Die bevorzugte Methode zum Bereitstellen von Freigabeverknüpfungen über ShortcutManagerCompat ist die automatische Umwandlung von Direct Share ChooserTarget-Objekten in Kreise.

Ziel für die Anzeigenbereitstellung angeben

Freigabeziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie statische Verknüpfungsdefinitionen. Fügen Sie in der Ressourcendatei im Stammelement <shortcuts> Zieldefinitionen für die Freigabe sowie andere Definitionen für statische Verknüpfungen hinzu. Jedes <share-targets>-Element enthält Informationen zum freigegebenen Datentyp, zu übereinstimmenden Kategorien und zur Zielklasse, die die Freigabeabsicht 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 dazu dienen, die veröffentlichten Verknüpfungen einer App mit den Definitionen für Freigabeziele abzugleichen. Kategorien können beliebige von der App definierte Werte haben.

Wenn der Nutzer im Android-Freigabebereich die Verknüpfung für die Freigabe auswählt, die dem Beispiel für die Zielfreigabe oben entspricht, erhält die App die folgende Freigabeabsicht:

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 die Intent, die beim Hinzufügen der Freigabeverknüpfung zu ShortcutManagerCompat erstellt wurde. Da es sich um eine andere Absicht handelt, ist Intent.EXTRA_SHORTCUT_ID nicht verfügbar. Wenn Sie die ID benötigen, müssen Sie sie manuell übergeben.

Nutzung von Tastenkombinationen für Kommunikations-Apps melden

Wenn Sie eine Kommunikations-App entwickeln, können Sie Ihr Ranking im Android-Freigabe-Menü verbessern, indem Sie die Nutzung sowohl für ausgehende als auch für eingehende Nachrichten erfassen. Dazu müssen Sie den Konversations-Shortcut, der den Kontakt darstellt, über ShortcutManagerCompat.pushDynamicShortcut noch einmal veröffentlichen.

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

Verwendung von Tastenkürzeln für ausgehende Nachrichten melden

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

Wenn Sie Nutzungsberichte auslösen möchten, geben Sie in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding die Bindung mit der actions.intent.SEND_MESSAGE-Funktion 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 an einen Gruppenchat gesendet wird, 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 Tastenkürzeln für eingehende Nachrichten melden

Wenn Sie Nutzungsberichte auslösen möchten, 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 Funktion actions.intent.RECEIVE_MESSAGE Verknüpfungen für Funktionen im Shortcut 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 von 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);

Mit AndroidX sowohl Freigabe-Verknüpfungen als auch ChooserTargets bereitstellen

Damit die AndroidX-Kompatibilitätsbibliothek verwendet werden kann, muss das Manifest der App die Metadaten-Auswahl-Zieldienste und Intent-Filter enthalten. Weitere Informationen finden Sie in der aktuellen ChooserTargetService Direct Share API.

Dieser Dienst ist bereits in der Kompatibilitätsbibliothek deklariert. Der Nutzer muss ihn also nicht im Manifest der App deklarieren. Die Verknüpfung der Freigabeaktivität mit dem Dienst muss jedoch als Zielanbieter für die Auswahl berücksichtigt werden.

Im folgenden Beispiel ist androidx.core.content.pm.ChooserTargetServiceCompat die Implementierung von ChooserTargetService, 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 Nutzung 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 Laufwerkpartition gespeichert. Auf Informationen in Verknüpfungen wie das Symbol, die Intents und die Namen von Personen und Ressourcen können nur Systemdienste und die App zugreifen, die die Verknüpfungen veröffentlicht.

Wie ist Direct Share entstanden?

Wir haben Direct Share in Android 6.0 (API-Ebene 23) eingeführt, damit Apps ChooserTarget-Objekte über eine ChooserTargetService bereitstellen können. Die Ergebnisse wurden reaktiv auf Anfrage abgerufen, was zu einer langen 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 Abruf abzurufen, können Apps mit der Sharing Shortcuts API Ziele für die direkte Freigabe im Voraus veröffentlichen. Dadurch wurde das Abrufen von Zielen für die direkte Freigabe bei der Vorbereitung des Freigabe-Sheets erheblich beschleunigt. Der ChooserTargetService-Direktfreigabemechanismus funktioniert weiterhin, aber das System ordnet Ziele, die auf diese Weise angegeben werden, niedriger ein als Ziele, für die die Sharing Shortcuts API verwendet wird.

Mit Android 11 (API-Level 30) wurde der ChooserTargetService-Dienst eingestellt. Die Sharing Shortcuts API ist die einzige Möglichkeit, Ziele für die direkte Freigabe anzugeben.

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

Alle Verknüpfungen, die mit dem Zweck „Teilen“ veröffentlicht wurden, sind auch Launcher-Verknüpfungen und werden im Menü angezeigt, wenn Sie lange auf das Symbol Ihrer App drücken. Die maximale Anzahl von Verknüpfungen pro Aktivität gilt auch für die Gesamtzahl der Verknüpfungen, die in einer App veröffentlicht werden (Share Targets und alte Launcher-Verknüpfungen zusammen).

Wie viele Verknüpfungen für die Freigabe sollten veröffentlicht werden?

Die Anzahl der Freigabe-Verknüpfungen ist auf die gleiche Anzahl von dynamischen Verknüpfungen beschränkt, die über getMaxShortcutCountPerActivity(android.content.Context) verfügbar sind. Sie können beliebig viele Verknüpfungen veröffentlichen, müssen jedoch beachten, dass Freigabeverknüpfungen im App Launcher durch langes Drücken und im Freigabebereich sichtbar sein können. Die meisten App-Launcher zeigen beim langen Drücken maximal vier oder fünf Verknüpfungen im Hochformat und acht im Querformat an. Weitere Informationen und Anleitungen zum Freigeben von Verknüpfungen finden Sie in diesen FAQs.