Użyj docelów udostępniania bezpośredniego, aby ułatwić i przyspieszyć udostępnianie adresów URL, obrazów i innych rodzajów danych z innych aplikacji użytkownikom Twojej aplikacji. Udostępnianie bezpośrednie działa poprzez wyświetlanie kontaktów z aplikacji do przesyłania wiadomości i aplikacji społecznościowych bezpośrednio na karcie udostępniania w Androidzie, bez konieczności wybierania aplikacji i wyszukiwania kontaktu.
ShortcutManagerCompat to interfejs API AndroidaX udostępniający skróty do udostępniania, który jest zgodny wstecznie z wycofanym interfejsem ChooserTargetService API. Jest to preferowana metoda publikowania skrótów do udostępniania i ChooserTargets. Instrukcje znajdziesz na tej stronie w sekcji Używanie AndroidX do udostępniania skrótów i celów selektora.
Publikowanie celów udostępniania bezpośredniego
W wierszu bezpośredniego udostępniania w Sharesheet wyświetlane są tylko dynamiczne skróty udostępniane przez interfejs API skrótów udostępniania. Aby opublikować docelowe grupy Direct Share:
W pliku zasobu XML aplikacji zadeklaruj elementy
share-target.<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>Po zainicjowaniu aplikacji użyj
setDynamicShortcuts, aby uporządkować dynamiczne skróty według ważności.Niższy indeks oznacza większą ważność. Jeśli tworzysz aplikację komunikacyjną, mogą to być najpopularniejsze rozmowy uporządkowane według czasu od poprzedniej wizyty w aplikacji. Nie publikuj nieaktualnych skrótów, ponieważ rozmowy, w których w ciągu ostatnich 30 dni nie było żadnych aktywności użytkowników, są uznawane za nieaktualne.
Kotlin
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
Jeśli opracowujesz aplikację do komunikacji, natychmiast po każdym otrzymaniu lub wysłaniu wiadomości do kontaktu zgłaszaj użycie skrótu za pomocą
pushDynamicShortcut. Więcej informacji znajdziesz na stronie Zgłoś użycie skrótu w komunikatorze. Możesz na przykład raportować użycie wiadomości wysyłanych przez użytkownika, określając powiązania możliwości w skrótie za pomocą funkcjiShortcutInfoCompat.Builder#addCapabilityBindingz funkcjąactions.intent.SEND_MESSAGE.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);
Jeśli użytkownik usunie kontakt, użyj
removeLongLivedShortcut. Jest to preferowany sposób usuwania skrótu niezależnie od tego, czy jest on przechowywany w pamięci podręcznej przez usługi systemowe. Poniżej znajdziesz fragment kodu, który pokazuje, jak to zrobić.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Poprawianie pozycji docelowych w ramach funkcji bezpośredniego udostępniania
Na karcie udostępniania w Androidzie jest widoczna stała liczba odbiorców bezpośredniego udostępniania. Te sugestie są sortowane według rangi. Aby poprawić pozycję swoich skrótów:
- Upewnij się, że wszystkie wartości atrybutu
shortcutIdssą unikalne i nigdy nie są używane ponownie w przypadku innych wartości docelowych. - Aby sprawdzić, czy skrót jest trwały, wywołaj
setLongLived(true). - W przypadku skrótów dotyczących wątków zgłoś użycie skrótów do wiadomości wychodzących i przychodzących, ponownie publikując odpowiednie skróty w
ShortcutManagerCompat.pushDynamicShortcut. Szczegółowe informacje znajdziesz w sekcji Zgłoś użycie skrótu w aplikacji do komunikacji na tej stronie. - Unikaj nieistotnych lub nieaktualnych wartości docelowych udostępniania bezpośredniego, np. kontaktów, z którymi użytkownik nie kontaktował się w ciągu ostatnich 30 dni.
- W przypadku aplikacji do obsługi SMS-ów unikaj podawanie skrótów do krótkich kodów lub rozmów uznanych za potencjalny spam. Jest duże prawdopodobieństwo, że użytkownicy udostępnią w tych rozmowach.
- Wywołaj funkcję
setCategories(), aby powiązać skrót z odpowiednimi atrybutamimimeType. Jeśli na przykład kontakt nie obsługuje RCS ani MMS-a, nie możesz powiązać odpowiedniego skrótu z typami MIME innych niż tekst, takimi jakimage/*ivideo/*. - W przypadku danej rozmowy, gdy skrót dynamiczny zostanie przesłany i użyty, nie zmieniaj identyfikatora skrótu. Zapewnia to przechowywanie danych o użytkowaniu na potrzeby rankingu.
Jeśli użytkownik kliknie dowolny cel bezpośredniego udostępniania, aplikacja musi otworzyć interfejs, w którym może wykonać działanie bezpośrednio wobec obiektu docelowego. Nie wyświetlaj użytkownikowi interfejsu rozróżniania ani nie umieszczaj go w interfejsie niezwiązanym z klikniętym celem. Na przykład w aplikacji do obsługi wiadomości kliknięcie elementu docelowego udostępniania bezpośredniego powoduje wyświetlenie rozmowy z wybraną osobą. Klawiatura jest widoczna, a wiadomość jest wstępnie wypełniona udostępnionymi danymi.
Interfejs API Sharing Shortcuts
Począwszy od Androida 10 (poziom interfejsu API 29) ShortcutInfo.Builder dodano metody i ulepszenia, które zapewniają dodatkowe informacje o docelowym obiekcie udostępniania:
setCategories()- Począwszy od Androida 10 kategorie są też używane do filtrowania skrótów, które mogą obsługiwać intencje lub działania udostępniania. Więcej informacji znajdziesz w sekcji Oznaczanie docelowych odbiorców udostępniania. To pole jest wymagane w przypadku skrótów przeznaczonych do udostępniania.
setLongLived()Określa, czy skrót jest prawidłowy, gdy został wycofany lub uczyniony niewidocznym przez aplikację (jako skrót dynamiczny lub przypięty). Jeśli skrót jest długotrwały, może zostać zapisany w pamięci podręcznej przez różne usługi systemowe nawet po wycofaniu go jako dynamicznego skrótu.
Długotrwałe wyświetlanie skrótu może poprawić jego pozycję w rankingu. Więcej informacji znajdziesz w sekcji Uzyskiwanie najlepszej pozycji w rankingu.
setShortLabel(),setLongLabel()Podczas publikowania skrótu do osoby fizycznej podaj jej pełne imię i nazwisko w polu
setLongLabel(), a w polusetShortLabel()– jej krótkie imię i nazwisko, np. pseudonim lub zdrobnienie imienia.
Zapoznaj się z przykładem publikowania skrótów udostępniania w GitHubzie.
Dodaj obrazy skrótów
Aby utworzyć skrót do udostępniania, musisz dodać obraz za pomocą setIcon().
Udostępnione skróty mogą pojawiać się w różnych miejscach w systemie i mogą być zmieniane.
Niektóre urządzenia z Androidem w wersji 7, 8 lub 9 (poziomy interfejsu API 25, 26, 27 i 28) mogą też wyświetlać ikony z mapą bitową bez tła, co znacznie zmniejsza kontrast. Aby mieć pewność, że skrót będzie wyglądał tak, jak chcesz, prześlij bitmapę adaptacyjną za pomocą IconCompat.createWithAdaptiveBitmap().
Upewnij się, że adaptacyjne mapy bitowe są zgodne z wytycznymi i wymiarami ustawionymi dla ikon adaptacyjnych. Najczęstszym sposobem realizacji jest przeskalowanie kwadratowej mapy bitowej do rozmiaru 72 x 72 dp i wyśrodkowanie jej w przezroczystym obszarze roboczym 108 x 108 dp. Jeśli ikona zawiera przezroczyste obszary, musisz podać kolor tła. W przeciwnym razie przezroczyste obszary będą czarne.
Nie przesyłaj obrazów zmaskowanych pod określony kształt. Na przykład przed Androidem 10 (poziom interfejsu API 29) często udostępniano użytkownikom awatary w ramach funkcji Direct ShareChooserTarget, które były zamaskowane w krąg. Płytka udostępniania w Androidzie i inne elementy systemu w Androidzie 10 mają teraz kształt i motyw zgodne z obrazami skrótów.
Preferowaną metodą udostępniania skrótów udostępniania za pomocą ShortcutManagerCompat jest automatyczne przekształcanie obiektów udostępniania bezpośredniego ChooserTarget w obiekty kompatybilne wstecz w ramach kręgów.
Określanie udziału docelowego
Docelowe miejsca udostępniania muszą być zadeklarowane w pliku zasobów aplikacji w sposób podobny do definicji statycznych skrótów. Dodaj definicje obiektów udostępniania w elemencie głównym <shortcuts> w pliku zasobu wraz z innymi definicjami statycznych skrótów. Każdy element <share-targets> zawiera informacje o typie udostępnianych danych, pasujących kategoriach oraz klasie docelowej, która obsługuje intencję udostępniania. Kod XML wygląda mniej więcej tak:
<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>
Element danych w docelowym miejscu udostępniania jest podobny do specyfikacji danych w filtrze intencji. Każdy docelowy udział może mieć wiele kategorii, które służą tylko do dopasowywania opublikowanych skrótów aplikacji do jej definicji miejsc docelowych udziału. Kategorie mogą mieć dowolne wartości zdefiniowane przez aplikację.
Jeśli użytkownik wybierze skrót udostępniania na karcie udostępniania na Androidzie, który odpowiada przykładowemu docelowi udostępniania powyżej, aplikacja otrzyma ten zamiar udostępniania:
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>
Jeśli użytkownik otworzy element udostępniania z poziomu skrótów w menu, aplikacja otrzyma intencję utworzoną podczas dodawania skrótu udostępniania do ShortcutManagerCompat.
Ponieważ jest to inna intencja, Intent.EXTRA_SHORTCUT_ID nie będzie dostępny. Jeśli go potrzebujesz, musisz go przekazać ręcznie.
Zgłaszanie użycia skrótów w aplikacjach do komunikacji
Jeśli tworzysz aplikację do komunikacji, możesz poprawić swoją pozycję w arkuszu udostępniania Androida, zgłaszając wykorzystanie zarówno wiadomości wychodzących, jak i przychodzących.
Aby to zrobić, ponownie opublikuj skrót rozmowy, który reprezentuje kontakt za pomocą ShortcutManagerCompat.pushDynamicShortcut.
Użycie skrótu i wiązania z możliwościami są zgodne z Androidem 5.0 (interfejs API 21).
Zgłaszanie korzystania ze skrótów w przypadku wiadomości wychodzących
Raportowanie wykorzystania wiadomości wysłanych przez użytkownika jest funkcjonalnie podobne do kliknięcia przycisku „wyślij” po utworzeniu wiadomości.
Aby wywołać raportowanie wykorzystania, określ w skrótach powiązania z możliwościami za pomocą ShortcutInfoCompat.Builder#addCapabilityBinding z możliwością actions.intent.SEND_MESSAGE.
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);
Jeśli wychodząca wiadomość jest przeznaczona do czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ recipient jest powiązany z tą funkcją.
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);
Zgłaszanie korzystania ze skrótów w przypadku wiadomości przychodzących
Aby aktywować raportowanie użytkowania, gdy użytkownik otrzyma wiadomość, np. SMS, wiadomość na czacie, e-maila lub powiadomienie, musisz dodatkowo określić w skrócie powiązania z funkcją ShortcutInfoCompat.Builder#addCapabilityBinding z funkcją actions.intent.RECEIVE_MESSAGE.
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);
Jeśli przychodząca wiadomość pochodzi z czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ sender jest powiązany z tą funkcją.
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);
Używanie AndroidX do udostępniania skrótów i obiektów ChooserTargets
Aby możliwe było korzystanie z biblioteki zgodności z Androidem, plik manifestu aplikacji musi zawierać zestaw metadanych selectr-target-service i intent-filter. Zapoznaj się z aktualnym interfejsem ChooserTargetService Direct Share API.
Ta usługa jest już zadeklarowana w bibliotece zgodności, więc użytkownik nie musi deklarować jej w pliku manifestu aplikacji. Połączenie aktywności związanej z udostępnianiem z usługą musi być jednak traktowane jako dostawca docelowego elementu wyboru.
W tym przykładzie implementacja ChooserTargetService to androidx.core.content.pm.ChooserTargetServiceCompat, która jest już zdefiniowana w AndroidX:
<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>
Najczęstsze pytania dotyczące udostępniania skrótów
Jak są przechowywane dane dotyczące korzystania z skrótów i czy opuszczają one urządzenie?
Skróty są przechowywane na urządzeniu w katalogu danych systemu na zaszyfrowanej partycji dysku. Informacje zawarte w skrótach, takie jak ikona, intencja czy nazwy osób i zasobów, są dostępne tylko dla usług systemowych i tej samej aplikacji, która publikuje skróty.
Co to jest historia udostępniania bezpośredniego?
Wprowadziliśmy udostępnianie bezpośrednie w Androidzie 6.0 (poziom interfejsu API 23), aby umożliwić aplikacjom udostępnianie obiektów ChooserTarget za pomocą ChooserTargetService. Wyniki były pobierane w reakcji na żądanie, co powodowało długi czas wczytywania wartości docelowych.
W Androidzie 10 (poziom API 29) zastąpiliśmy interfejsy API ChooserTargetService Direct Share nowym interfejsem Share Shortcuts API. Zamiast pobierania wyników w reakcji na żądanie interfejs API ShortCuts do udostępniania pozwala aplikacjom publikować cele udostępniania bezpośredniego z wyprzedzeniem. Dzięki temu znacznie przyspieszyliśmy proces pobierania danych dotyczących bezpośredniego udostępniania podczas przygotowywania arkusza udostępniania. Mechanizm ChooserTargetService bezpośredniego udostępniania będzie nadal działać, ale system będzie niższe wartości celów udostępnianych w ten sposób niż dowolny cel korzystający z interfejsu API skrótów udostępniania.
W Androidzie 11 (poziom interfejsu API 30) usługa ChooserTargetService została wycofana, a interfejs API skrótów udostępniania jest jedynym sposobem na udostępnianie docelowych danych w ramach funkcji bezpośredniego udostępniania.
Czym różnią się opublikowane skróty do celów udostępniania od skrótów w menu (typowe wykorzystanie skrótów po długim naciśnięciu ikony aplikacji w menu)?
Wszystkie skróty opublikowane w celu udostępniania są też skrótami w menu. Po naciśnięciu i przytrzymaniu ikony aplikacji pojawią się w menu. Maksymalna liczba skrótów na aktywność dotyczy również łącznej liczby skrótów publikowanych przez aplikację (do celów udostępniania i starszych skrótów w menu).
Jakie są wytyczne dotyczące liczby skrótów do udostępniania, które należy opublikować.
Liczba skrótów do udostępniania jest ograniczona do tej samej liczby dynamicznych skrótów, która jest dostępna w getMaxShortcutCountPerActivity(android.content.Context). Można opublikować dowolną liczbę skrótów, ale należy pamiętać, że skróty do udostępniania mogą być widoczne po długim naciśnięciu aplikacji w programie uruchamiającym i na karcie udostępniania. Większość programów uruchamiających aplikacje po długim naciśnięciu wyświetla maksymalnie 4 lub 5 skrótów w orientacji pionowej i 8 w orientacji poziomej. Więcej informacji i wskazówek na temat udostępniania skrótów znajdziesz w najczęstszych pytaniach.