Mit Direct Share-Zielen können Nutzer anderer Apps einfacher und schneller URLs, Bilder oder andere Daten mit deiner App teilen. Dabei werden Kontakte aus Messaging- und sozialen Apps direkt im Android-Sharesheet präsentiert, ohne dass Nutzer 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 dazu 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. So veröffentlichen Sie Direct Share-Ziele:
Deklariere in der XML-Ressourcendatei deiner 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>
Verwende beim Initialisieren deiner App
setDynamicShortcuts
, um dynamische Verknüpfungen nach Wichtigkeit zu sortieren.Ein niedrigerer Index weist auf eine höhere Bedeutung hin. Wenn Sie eine Kommunikationsanwendung entwickeln, können die Top-Unterhaltungen nach Aktualität sortiert sein, 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);
Wenn Sie eine Kommunikations-App entwickeln, melden Sie die Nutzung der Kurzbefehle sofort über
pushDynamicShortcut
, sobald der Nutzer eine Nachricht an einen Kontakt erhält oder sendet. Weitere Informationen finden Sie unter Nutzung von Kurzbefehlen für Kommunikations-Apps melden auf dieser Seite. Sie können beispielsweise die Nutzung für vom Nutzer gesendete Nachrichten melden, indem Sie Funktionsbindungen in der Verknüpfung überShortcutInfoCompat.Builder#addCapabilityBinding
mit der Funktionactions.intent.SEND_MESSAGE
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, um die Verknüpfung zu entfernen, unabhängig davon, ob sie von den Systemdiensten im Cache gespeichert wird. Das folgende Code-Snippet zeigt ein Beispiel, wie dies funktioniert.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Ranking der Direct Share-Ziele verbessern
Das Android Sharesheet zeigt eine feste Anzahl von Direct Share-Zielen an. 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 unterschiedliche Ziele wiederverwendet werden. - Sorgen Sie dafür, dass die Verknüpfung langlebig ist, indem Sie
setLongLived(true)
aufrufen. - Melden Sie die Nutzung von Tastenkombinationen für ausgehende und eingehende Nachrichten für Unterhaltungsverknüpfungen, indem Sie die entsprechenden Verknüpfungen über
ShortcutManagerCompat.pushDynamicShortcut
noch einmal veröffentlichen. Weitere Informationen finden Sie unter Nutzung von Kurzbefehlen für Kommunikations-Apps melden auf dieser Seite. - Geben Sie keine irrelevanten oder veralteten Direct Share-Ziele an, z. B. Kontakte, denen der Nutzer in den letzten 30 Tagen keine Nachricht gesendet hat.
- Geben Sie bei SMS-Apps keine Kurzcodes für Kurzcodes oder Unterhaltungen an, die als potenzieller Spam identifiziert werden können. Es ist sehr unwahrscheinlich, dass Nutzer in diesen Unterhaltungen etwas teilen.
- Rufen Sie
setCategories()
auf, um die Verknüpfung mit den entsprechendenmimeType
-Attributen zu verknüpfen. Wenn der Kontakt beispielsweise bei einer SMS-App nicht RCS oder MMS aktiviert ist, wird die entsprechende Verknüpfung nicht mit Nicht-Text-MIME-Typen wieimage/*
undvideo/*
verknüpft. - Ändern Sie die Verknüpfungs-ID für eine bestimmte Unterhaltung nicht, nachdem eine dynamische Verknüpfung gesendet und die Nutzung gemeldet wurde. Dadurch wird sichergestellt, dass Nutzungsdaten für das Ranking gespeichert werden.
Wenn der Nutzer auf ein Direct Share-Ziel tippt, muss er von Ihrer App zu einer Benutzeroberfläche weitergeleitet werden, auf der er eine Aktion direkt im Betreff des Ziels ausführen kann. Zeige dem Nutzer keine Benutzeroberfläche zur Begriffsklärung und platziere ihn nicht auf einer Benutzeroberfläche, die nichts mit dem angetippten Ziel zu tun hat. Wenn der Nutzer in einer Messaging-App beispielsweise auf ein Direct Share-Ziel tippt, wird er zu einer Konversationsansicht mit der ausgewählten Person weitergeleitet. Die Tastatur wird angezeigt und die Meldung ist mit den freigegebenen Daten vorausgefüllt.
Freigabe Shortcuts API
Ab Android 10 (API-Level 29) wurden in ShortcutInfo.Builder
Methoden und Verbesserungen hinzugefügt, die zusätzliche Informationen zum Freigabeziel enthalten:
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 erforderlich, damit Verknüpfungen als Freigabeziele verwendet werden können.
setLongLived()
Gibt an, ob eine Verknüpfung gültig ist, wenn sie nicht veröffentlicht oder von der App unsichtbar wird (als dynamische oder angepinnte Verknüpfung). Wenn eine Verknüpfung lange gültig ist, kann sie von verschiedenen Systemdiensten im Cache gespeichert werden, auch nachdem sie nicht als dynamische Verknüpfung veröffentlicht wurde.
Wenn Sie eine Verknüpfung langlebiger machen, kann sich das Ranking verbessern. Weitere Informationen finden Sie unter Bestes Ranking erhalten.
setShortLabel()
,setLongLabel()
Wenn du eine Verknüpfung für eine einzelne Person veröffentlichst, gib bitte den vollständigen Namen in
setLongLabel()
und einen beliebigen Kurznamen, z. B. einen Spitznamen oder Vornamen, insetShortLabel()
an.
Ein Beispiel für die Veröffentlichung von Freigabeverknüpfungen auf GitHub
Bilder für Kurzbefehle bereitstellen
Wenn du eine Verknüpfung zum Teilen erstellen möchtest, musst du über setIcon()
ein Bild hinzufügen.
Verknüpfungen zum Teilen können auf allen Systemoberflächen angezeigt und 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 reine Bitmapsymbole ohne Hintergrund angezeigt, was den Kontrast erheblich verringert. Damit die Verknüpfung wie gewünscht aussieht, können Sie mit IconCompat.createWithAdaptiveBitmap()
eine adaptive Bitmap bereitstellen.
Achten Sie darauf, dass adaptive Bitmaps denselben Richtlinien und Abmessungen für adaptive Symbole entsprechen. Die am häufigsten verwendete Methode besteht darin, die beabsichtigte quadratische Bitmap auf 72 x 72 dp zu skalieren und sie innerhalb eines transparenten Canvas mit 108 x 108 dp zu zentrieren. Wenn Ihr Symbol transparente Bereiche enthält, müssen Sie eine Hintergrundfarbe hinzufügen. Andernfalls werden transparente Bereiche schwarz angezeigt.
Stellen Sie keine Bilder bereit, die in einer bestimmten Form maskiert sind. Vor Android 10 (API-Level 29) war es beispielsweise üblich, Nutzeravatare für Direct Share-ChooserTarget
s zur Verfügung zu stellen, die in einem Kreis verborgen waren. Das Android Sharesheet und andere Systemoberflächen in Android 10 sind jetzt mit Formen und Designverknüpfungen verknüpft.
Die bevorzugte Methode zum Bereitstellen von Verknüpfungen zum Teilen über ShortcutManagerCompat
ist, dass Backcompat-Direct Share-ChooserTarget
-Objekte automatisch in Kreise umgewandelt werden.
Freigabeziel deklarieren
Freigabeziele müssen in der Ressourcendatei der App deklariert werden, ähnlich wie bei den Definitionen statischer Tastenkombinationen. Fügen Sie Definitionen zum Freigabeziel sowie andere statische Kurzbefehle im Stammelement <shortcuts>
der Ressourcendatei hinzu. Jedes <share-targets>
-Element enthält Informationen zum freigegebenen 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 Ziel für die gemeinsame Nutzung ä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 den entsprechenden Definitionen der Freigabeziele zuzuordnen. Kategorien können beliebige App-definierte Werte haben.
Wenn der Nutzer im Android-Sharesheet die Verknüpfungsverknüpfung auswählt, die mit dem obigen Beispiel für die Zielfreigabe übereinstimmt, erhält die App den folgenden Share-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 Verknüpfungen im Launcher öffnet, erhält die App den Intent, der beim Hinzufügen der Verknüpfungsverknüpfung zu ShortcutManagerCompat erstellt wurde.
Da es sich um einen anderen Intent handelt, ist Intent.EXTRA_SHORTCUT_ID
nicht verfügbar und Sie müssen die ID bei Bedarf manuell übergeben.
Nutzung von Kurzbefehlen 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 Funktionsbindungen ist abwärtskompatibel zu Android 5.0 (API 21).
Nutzung von Kurzbefehlen für ausgehende Nachrichten melden
Die Verwendung der Berichterstellung für vom Nutzer gesendete Nachrichten ähnelt der Funktion, mit der nach dem Erstellen einer Nachricht auf die Schaltfläche „Senden“ geklickt wird.
Wenn Sie Nutzungsberichte auslösen möchten, geben Sie Funktionsbindungen in der Verknüpfung über ShortcutInfoCompat.Builder#addCapabilityBinding
mit der Funktion actions.intent.SEND_MESSAGE
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 sich die ausgehende Nachricht auf einen Gruppenchat bezieht, müssen Sie auch den Parameterwert Audience
hinzufügen, da der Funktion der Typ recipient
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);
Nutzung von Kurzbefehlen für eingehende Nachrichten melden
Wenn Nutzungsberichte ausgelöst werden sollen, wenn der Nutzer eine SMS, Chatnachricht, E-Mail oder Benachrichtigung erhält, müssen Sie in der Verknüpfung zusätzlich über ShortcutInfoCompat.Builder#addCapabilityBinding
mit der Funktion actions.intent.RECEIVE_MESSAGE
Funktionsbindungen 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 Typ sender
der Funktion 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 sowohl Freigabeverknüpfungen als auch ChooserTargets bereitzustellen
Damit Sie mit der AndroidX-Kompatibilitätsbibliothek arbeiten können, muss das Manifest der App die festgelegten Metadaten-Auswahl- 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 zur Auswahl berücksichtigt werden.
Im folgenden Beispiel ist die Implementierung von ChooserTargetService
androidx.core.content.pm.ChooserTargetServiceCompat
, was 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 zum Teilen von Verknü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 Laufwerkpartition gespeichert. Informationen in Verknüpfungen wie das Symbol, der Intent und die Namen von Personen und Ressourcen sind nur für Systemdienste und die App zugänglich, die die Verknüpfungen veröffentlicht.
Was ist der bisherige 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 reaktiv bei Bedarf 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 bei Bedarf abzurufen, können Apps mit der 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 Direct Share-Mechanismus ChooserTargetService
funktioniert zwar weiterhin, allerdings werden die so bereitgestellten Ziele vom System viel niedriger eingestuft als alle Ziele, für die die Sharing Shortcuts API verwendet wird.
Android 11 (API-Level 30) hat den 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 Verknüpfungen im Launcher (die typische Verwendung von Verknüpfungen, wenn lange auf App-Symbole im Launcher gedrückt wird)?
Alle Verknüpfungen, die für einen „Ziel teilen“-Zweck veröffentlicht wurden, sind auch eine Verknüpfung im Launcher und werden im Menü angezeigt, wenn du lange auf das Symbol deiner App drückst. 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 (gemeinsam genutzte Ziele und alte Launcher-Verknüpfungen).
Wie viele Tastenkombinationen zum Teilen sollte veröffentlicht werden?
Die Anzahl der Freigabeverknüpfungen ist auf dasselbe Limit für dynamische Verknüpfungen beschränkt, die über getMaxShortcutCountPerActivity(android.content.Context)
verfügbar sind. Bis zu diesem Limit kann eine beliebige Anzahl veröffentlicht werden. Beachten Sie jedoch, dass die Freigabeverknüpfungen im App Launcher durch langes Drücken und im Freigabetabellenblatt sichtbar sein können. Die meisten App Launchers zeigen bei langem Drücken maximal vier oder fünf Tastenkombinationen im Hochformat und acht im Querformat an. Weitere Informationen und Anleitungen zum Teilen von Verknüpfungen finden Sie in diesen FAQs.