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.
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>Wenn Ihre App initialisiert wird, können Sie mit
setDynamicShortcutsdynamische Verknüpfungen nach Wichtigkeit sortieren.Je niedriger der Index, desto wichtiger ist die Information. Wenn Sie eine Kommunikations-App entwickeln, können die Top-Unterhaltungen nach Aktualität sortiert werden, 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);
Wenn Sie eine Kommunikations-App entwickeln, melden Sie die Verwendung von Tastenkürzeln über
pushDynamicShortcutsofort, 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 überShortcutInfoCompat.Builder#addCapabilityBindingmit der Funktionactions.intent.SEND_MESSAGEBindungen für die Fähigkeiten 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);
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));
Rang 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.pushDynamicShortcutnoch 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 entsprechendenmimeType-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 wieimage/*undvideo/*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 platzieren Sie ihn nicht in einer Benutzeroberfläche, 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 insetShortLabel()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 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 Freigabe 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 Tastenkürzeln 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.
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 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.
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);
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.
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 von einem Gruppenchat stammt, müssen Sie auch den Parameterwert Audience hinzufügen, da der Typ sender mit der Funktion verknüpft 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);
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 lange auf App-Symbole im Launcher 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 dynamischer 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.