Mit Direct Share-Zielen können Nutzer anderer Apps URLs, Bilder oder andere Arten von Daten einfacher und schneller mit Ihrer App teilen. Dabei werden Kontakte aus Messaging- und sozialen Apps direkt auf dem Android-Sharesheet präsentiert, ohne dass Nutzer erst die App auswählen und dann nach dem Kontakt suchen müssen.
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 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. Führen Sie die folgenden Schritte aus, um Direct Share-Ziele 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>Verwenden Sie beim Initialisieren Ihrer App
setDynamicShortcuts, um dynamische Verknüpfungen nach Wichtigkeit zu sortieren.Ein niedrigerer Index deutet auf eine größere Wichtigkeit hin. Wenn Sie eine Kommunikations-App erstellen, können dies die Top-Unterhaltungen sein, die nach Aktualität sortiert sind, wie sie in Ihrer App angezeigt wird. 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);
Wenn Sie eine Kommunikations-App entwickeln, melden Sie sofort jedes Mal, wenn der Nutzer eine Nachricht an einen Kontakt erhält oder an einen Kontakt sendet, sofort über
pushDynamicShortcutdie Nutzung der Verknüpfung. Weitere Informationen finden Sie auf dieser Seite unter Nutzung von Verknüpfungen für Kommunikations-Apps melden. Sie können beispielsweise die Nutzung für vom Nutzer gesendete Nachrichten erfassen, indem Sie in der Verknüpfung überShortcutInfoCompat.Builder#addCapabilityBindingmit der Funktionactions.intent.SEND_MESSAGEFunktionsbindungen 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 bevorzugte Methode zum Entfernen der Verknüpfung, unabhängig davon, ob sie von Systemdiensten im Cache gespeichert wird. 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 Ihrer Direct Share-Ziele verbessern
Auf dem Android Sharesheet ist eine feste Anzahl von Direct Share-Zielen angegeben. Diese Vorschläge sind nach Rang sortiert. So können Sie das Ranking Ihrer Tastenkombinationen verbessern:
- Achten Sie darauf, dass alle
shortcutIdseindeutig sind und nie für andere Ziele wiederverwendet werden. - Sorgen Sie dafür, dass die Verknüpfung langlebig ist, indem Sie
setLongLived(true)aufrufen. - Sie können die Nutzung von Verknüpfungen für ausgehende und eingehende Nachrichten für unterhaltungsbezogene Verknüpfungen melden. Dazu veröffentlichen Sie die entsprechenden Verknüpfungen über
ShortcutManagerCompat.pushDynamicShortcutnoch einmal. Weitere Informationen finden Sie auf dieser Seite unter Nutzung von Verknüpfungen für Kommunikations-Apps melden. - Vermeiden Sie es, irrelevante oder veraltete Direct Share-Ziele anzugeben, z. B. Kontakte, denen der Nutzer in den letzten 30 Tagen keine Nachricht gesendet hat.
- Vermeiden Sie für SMS-Apps die Bereitstellung von Verknüpfungen für Kurzcodes oder Unterhaltungen, die als potenzieller Spam erkannt werden. Es ist höchst unwahrscheinlich, dass Nutzende in diesen Gesprächen Inhalte teilen.
- Rufen Sie
setCategories()auf, um die Verknüpfung mit den entsprechendenmimeType-Attributen zu verknüpfen. Wenn der Kontakt bei einer SMS-App beispielsweise nicht RCS oder MMS aktiviert ist, wird die entsprechende Verknüpfung nicht mit Nicht-Text-MIME-Typen wieimage/*undvideo/*verknüpft. - Ändern Sie für eine bestimmte Unterhaltung die Verknüpfungs-ID nicht, nachdem eine dynamische Verknüpfung gesendet und die Nutzung gemeldet wurde. Dadurch werden Nutzungsdaten für das Ranking aufbewahrt.
Wenn der Nutzer auf ein Direct Share-Ziel tippt, muss er von der App zu einer Benutzeroberfläche weitergeleitet werden, auf der er eine Aktion direkt in Bezug auf das Ziel ausführen kann. Zeigen Sie dem Nutzer keine Bezeichnungs-UI und platzieren Sie sie nicht in einer UI, die nichts mit dem angetippten Ziel zu tun hat. Wenn der Nutzer in einer Messaging-App beispielsweise auf ein Direct Share-Ziel antippt, wird er zu einer Unterhaltungsansicht mit der ausgewählten Person weitergeleitet. Die Tastatur ist sichtbar und die Nachricht wird 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 Freigabeziel liefern:
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 für Verknüpfungen erforderlich, die als Freigabeziele verwendet werden sollen.
setLongLived()Gibt an, ob eine Verknüpfung gültig ist, wenn sie nicht veröffentlicht oder von der App unsichtbar gemacht wurde (als dynamische oder angepinnte Verknüpfung). Wenn eine Verknüpfung langlebig ist, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, selbst wenn sie als dynamische Verknüpfung aufgehoben wurde.
Langfristige Abkürzungen können das Ranking verbessern. Weitere Informationen finden Sie unter Bestes Ranking erzielen.
setShortLabel(),setLongLabel()Wenn du eine Verknüpfung für eine einzelne Person veröffentlichst, gib bitte ihren vollständigen Namen in
setLongLabel()und einen Kurznamen wie einen Spitznamen oder Vornamen insetShortLabel()an.
Sehen Sie sich ein Beispiel für das Veröffentlichen von Freigabeverknüpfungen auf GitHub an.
Bilder für Verknüpfungen zur Verfügung stellen
Wenn du einen Kurzbefehl zum Teilen erstellen möchtest, musst du über setIcon() ein Bild hinzufügen.
Verknüpfungen zum Teilen können auf verschiedenen Systemoberflächen angezeigt und möglicherweise umgestaltet werden.
Außerdem können auf einigen Geräten mit Android-Version 7, 8 oder 9 (API-Level 25, 26, 27 und 28) nur Bitmapsymbole ohne Hintergrund angezeigt werden, was den Kontrast erheblich verringert. Damit Ihre Verknüpfung wie beabsichtigt aussieht, stellen Sie mit IconCompat.createWithAdaptiveBitmap() eine adaptive Bitmap bereit.
Achten Sie darauf, dass adaptive Bitmaps denselben Richtlinien und Maßen für adaptive Symbole entsprechen. Meistens wird die gewünschte quadratische Bitmap auf 72 x 72 dp skaliert und innerhalb eines transparenten Canvas mit 108 x 108 dp zentriert. Falls Ihr Symbol transparente Bereiche enthält, müssen Sie eine Hintergrundfarbe einfügen. Andernfalls erscheinen die transparenten Bereiche schwarz.
Stellen Sie keine Bilder bereit, die durch eine bestimmte Form maskiert sind. Vor Android 10 (API-Level 29) waren beispielsweise Nutzeravatare für Direct Share-ChooserTargets üblich, die als Kreis maskiert waren. Android Sharesheet und andere Systemoberflächen in Android 10 können jetzt Verknüpfungsbilder für Formen und Designs erstellen.
Die bevorzugte Methode zur Bereitstellung von Freigabeverknüpfungen ist, dass über ShortcutManagerCompat die Backcompat-Direct Share-ChooserTarget-Objekte automatisch Kreise für Sie gestaltet werden.
Beteiligungsziel deklarieren
Freigabeziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie bei Definitionen statischer Verknüpfungen. Fügen Sie im Stammelement <shortcuts> der Ressourcendatei Definitionen für gemeinsame Ziele zusammen mit anderen statischen Verknüpfungsdefinitionen hinzu. Jedes <share-targets>-Element enthält Informationen zum freigegebenen Datentyp, zu übereinstimmenden Kategorien und zur Zielklasse, mit der der Freigabe-Intent verarbeitet wird. 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 den Definitionen der Freigabeziele abzugleichen. Kategorien können beliebige, von der Anwendung definierte Werte haben.
Wenn der Nutzer im Android-Sharesheet die Verknüpfung zum Teilen im Android-Sharesheet auswählt, die mit dem Beispiel für die Zielfreigabe oben ü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 Freigabeverknüpfung zu ShortcutManagerCompat erstellt wurde.
Da es sich um einen anderen Intent handelt, steht Intent.EXTRA_SHORTCUT_ID nicht zur Verfügung. Sie müssen die ID bei Bedarf manuell übergeben.
Verknüpfungsnutzung 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 die Funktionsbindungen sind abwärtskompatibel mit Android 5.0 (API 21).
Nutzung von Verknüpfungen für ausgehende Nachrichten melden
Die Berichterstellung 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 mit der Funktion actions.intent.SEND_MESSAGE Funktionsbindungen 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 für einen Gruppenchat bestimmt ist, müssen Sie auch den Parameterwert Audience hinzufügen, da der Typ recipient der Funktion 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);
Verknüpfungsnutzung für eingehende Nachrichten melden
Wenn Sie Nutzungsberichte auslösen möchten, wenn der Nutzer eine Nachricht erhält, z. B. eine SMS, eine Chatnachricht, eine E-Mail oder eine Benachrichtigung, müssen Sie zusätzlich in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding mit der Funktion actions.intent.RECEIVE_MESSAGE Capability-Bindungen 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 Funktion der Typ sender 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 Freigabeverknüpfungen und Auswahlziele bereitzustellen
Um mit der AndroidX-Kompatibilitätsbibliothek arbeiten zu können, muss das Manifest der App den Parameter „meta-data chooser-target-service“ 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 für die Auswahl berücksichtigt werden.
Im folgenden Beispiel ist die Implementierung von ChooserTargetService androidx.core.content.pm.ChooserTargetServiceCompat, das 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>
FAQs zu Freigabeverknü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 Laufwerkspartition gespeichert. Informationen in Verknüpfungen wie das Symbol, der Intent und die Namen von Personen und Ressourcen sind nur für Systemdienste und die Anwendung zugänglich, die die Verknüpfungen veröffentlicht.
Wie ist der 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 bei Bedarf reaktiv abgerufen, was zu langen Ladezeiten 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 über die 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 ChooserTargetService Direct Share-Mechanismus funktioniert weiterhin, aber das System stuft Ziele, die auf diese Weise bereitgestellt werden, wesentlich niedriger ein als alle Ziele, die die Sharing Shortcuts API verwenden.
Android 11 (API-Level 30) hat den Dienst ChooserTargetService eingestellt. Die einzige Möglichkeit zum Bereitstellen von Direct Share-Zielen ist die Sharing Shortcuts API.
Wie unterscheiden sich veröffentlichte Tastenkombinationen für Freigabeziele von Launcher-Tastenkombinationen (die typische Verwendung von Tastenkombinationen beim langen Drücken auf App-Symbole im Launcher)?
Alle Tastenkombinationen, die zum Zweck des Teilens veröffentlicht werden, sind auch Launcher-Verknüpfungen und werden im Menü angezeigt, wenn Sie das Symbol Ihrer App lange drücken. Das Limit für die Anzahl der Kurzbefehle pro Aktivität gilt auch für die Gesamtzahl der Verknüpfungen, die eine App veröffentlicht (Freigabeziele und Legacy-Launcher-Tastenkombinationen zusammen).
Wie lautet die Anzahl der Kurzbefehle zum Teilen, die veröffentlicht werden sollten?
Die Anzahl der Freigabeverknüpfungen ist auf das gleiche Limit der dynamischen Tastenkombinationen beschränkt, die über getMaxShortcutCountPerActivity(android.content.Context) verfügbar sind. Sie können eine beliebige Anzahl innerhalb dieses Limits veröffentlichen. Beachten Sie jedoch, dass Freigabeverknüpfungen im App Launcher sichtbar sein können, wenn Sie lange drücken, und im Share Sheet. Die meisten App-Launcher zeigen bei langem Drücken maximal vier oder fünf Tastenkombinationen im Hochformat und acht im Querformat. Weitere Informationen und eine Anleitung zum Teilen von Tastenkombinationen finden Sie in diesen FAQs.