Podaj cele udostępniania bezpośredniego

Cele bezpośredniego udostępniania pozwalają użytkownikom innych aplikacji łatwiej i szybciej udostępniać w Twojej aplikacji adresy URL, obrazy i inne rodzaje danych. Bezpośrednie udostępnianie pozwala zaprezentować kontakty z komunikatorów i aplikacji społecznościowych bezpośrednio w arkuszu udostępniania na Androidzie bez konieczności wybierania aplikacji, a potem 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 preferowany sposób publikowania zarówno skrótów do udostępniania, jak i ChooserTargets. Instrukcje znajdziesz w sekcji Korzystanie z AndroidaX do udostępniania skrótów i wyboru celów na tej stronie.

Opublikuj wartości docelowe bezpośredniego udostępniania

Wiersz bezpośredniego udostępniania w arkuszu udostępniania zawiera tylko dynamiczne skróty udostępniane przez interfejsSharing Shortcuts API. Aby opublikować cele bezpośredniego udostępniania, wykonaj poniższe czynności.

1. W pliku zasobów 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>
   

2. 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);
   
   

3. Jeśli tworzysz aplikację do komunikacji, zgłaszaj użycie skrótów w pushDynamicShortcut natychmiast za każdym razem, gdy użytkownik otrzyma lub wyśle wiadomość do kontaktu. Więcej informacji znajdziesz w sekcji Zgłaszanie użycia skrótów w aplikacjach do komunikacji na tej stronie. 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ą funkcji ShortcutInfoCompat.Builder#addCapabilityBinding z 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);
   

4. Jeśli użytkownik usunie kontakt, użyj metody 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. Fragment kodu poniżej pokazuje przykładowy, jak to zrobić.

   Kotlin

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
   

   Java

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));
   
   

Popraw rankingi docelowych wartości bezpośredniego udostępniania

Arkusz udostępniania Androida pokazuje stałą liczbę celów bezpośredniego udostępniania. Sugestie są sortowane według pozycji. Możesz poprawić pozycję skrótów, wykonując następujące czynności:

• Upewnij się, że wszystkie elementy shortcutIds są unikalne i nigdy nie były używane w różnych środowiskach 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. Więcej informacji znajdziesz w sekcji Zgłaszanie użycia skrótów w aplikacjach do komunikacji na tej stronie.
• Unikaj podawania nietrafnych lub nieaktualnych celów bezpośredniego udostępniania – na przykład takich, do których użytkownik nie wysłał wiadomości 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. Użytkownicy najprawdopodobniej nie udostępnią danych w tych rozmowach.
• Wywołaj setCategories(), aby powiązać skrót z odpowiednimi atrybutami mimeType. Na przykład w aplikacji do obsługi SMS-ów, jeśli kontakt nie obsługuje czatów RCS lub MMS, nie możesz powiązać odpowiedniego skrótu z typami MIME nietekstowymi, takimi jak image/* i video/*.
• Po przekazaniu dynamicznego skrótu i zgłoszeniu użycia w danym wątku nie zmieniaj identyfikatora skrótu. Zapewni to przechowywanie danych o korzystaniu 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 pokazuj użytkownikowi interfejsu ujednoznacznienia ani nie umieszczaj go w interfejsie niepowiązanym z klikniętym elementem docelowym. Na przykład w aplikacji do obsługi wiadomości kliknięcie celu bezpośredniego udostępniania powoduje wyświetlenie widoku rozmowy z wybraną osobą. Widoczna jest klawiatura, a wiadomość jest wstępnie wypełniona udostępnionymi danymi.

Interfejs Share Shortcuts API

Począwszy od Androida 10 (poziom interfejsu API 29) do ShortcutInfo.Builder dodano metody i ulepszenia, które zapewniają dodatkowe informacje o docelowym zakresie udostępniania:

setCategories()

Począwszy od Androida 10 kategorie służą też do filtrowania skrótów, które mogą obsługiwać intencje i działania związane z udostępnianiem. Szczegółowe informacje znajdziesz w sekcji Deklarowanie celu udziału. To pole jest wymagane, jeśli skróty mają być używane jako elementy docelowe udostępniania.

setLongLived()

Określa, czy skrót jest prawidłowy, gdy został wycofany lub stał się niewidoczny przez aplikację (jako skrót dynamiczny lub przypięty). Jeśli skrót jest od dłuższego czasu, może być zapisany w pamięci podręcznej przez różne usługi systemowe, nawet po cofnięciu publikacji jako skrótu dynamicznego.

Długotrwałe zastosowanie skrótu może poprawić jego pozycję w rankingu. Więcej informacji znajdziesz w sekcji Uzyskiwanie najlepszej pozycji w rankingu.

setShortLabel(), setLongLabel()

Gdy publikujesz skrót dla konkretnej osoby, umieść w polu setLongLabel() jej pełne imię i nazwisko, a w setShortLabel() – imię i nazwisko.

Zobacz przykład publikowania na GitHubie skrótów do udostępniania.

Dodaj zdjęcia skrótu

Aby utworzyć skrót do udostępniania, musisz dodać obraz za pomocą usługi setIcon().

Skróty udostępniania mogą wyświetlać się na platformach systemowych i mogą zmieniać ich kształt. 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 skrót wyglądał prawidłowo, udostępnij adaptacyjną bitmapę 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 zamaskowanych do określonego kształtu. Na przykład przed Androidem 10 (poziom interfejsu API 29) powszechnie udostępniano awatary użytkowników ChooserTarget do bezpośredniego udostępniania, które były zamaskowane dla kręgu. Arkusz udostępniania Androida i inne platformy systemowe w Androidzie 10 są teraz kształtami i obrazami skrótów do motywów. Preferowaną metodą udostępniania skrótów do udostępniania jest ShortcutManagerCompat, która automatycznie przekształca w kręgi obiekty ChooserTargetbezpośredniego udostępniania wstecznego.

Deklarowanie celu udostępnienia

Cele udostępniania muszą być zadeklarowane w pliku zasobów aplikacji, podobnie jak w przypadku statycznych definicji skrótów. Dodaj definicje miejsca docelowego udziału w elemencie głównym <shortcuts> w pliku zasobów oraz inne statyczne definicje 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 celu udziału 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 definiowane przez aplikację.

Jeśli użytkownik wybierze w arkuszu udostępniania Androida skrót do skrótu do udostępniania, który pasuje do przykładowego udziału docelowego powyżej, aplikacja otrzyma taką intencję 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 cel udostępniania za pomocą skrótów w programie uruchamiającym, aplikacja otrzyma intencję utworzoną podczas dodawania skrótu udostępniania do ShortcutManagerCompat. Ponieważ ma to inną intencję, obiekt Intent.EXTRA_SHORTCUT_ID będzie niedostępny i w razie potrzeby trzeba będzie przekazać identyfikator 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 do rozmowy reprezentujący kontakt za pomocą narzędzia ShortcutManagerCompat.pushDynamicShortcut.

Wykorzystanie skrótów i powiązania funkcji są zgodne wstecznie z Androidem 5.0 (API 21).

Zgłaszanie użycia skrótów do wiadomości wychodzących

Raportowanie wykorzystania wiadomości wysłanych przez użytkownika działa podobnie do klikania przycisku „Wyślij” po utworzeniu wiadomości.

Aby aktywować raportowanie wykorzystania, określ powiązania możliwości w skrócie za pomocą metody ShortcutInfoCompat.Builder#addCapabilityBinding z funkcją actions.intent.SEND_MESSAGE.

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);

Jeśli wiadomość wychodząca dotyczy czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ recipient jest powiązany z tą funkcją.

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);

Zgłaszanie użycia skrótów do 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.

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);

Jeśli wiadomość przychodząca pochodzi z czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ sender jest powiązany z tą funkcją.

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);

Korzystaj z AndroidaX, aby udostępniać skróty udostępniania i cele wyboru

Aby można było korzystać z biblioteki zgodności AndroidX, plik manifestu aplikacji musi zawierać zestaw metadanych selectr-target-service i intent-filter. Zobacz obecny interfejs ChooserTargetService Direct Share API.

Ta usługa jest już zadeklarowana w bibliotece zgodności, więc użytkownik nie musi deklarować usługi 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 poniższym przykładzie implementacją ChooserTargetService jest androidx.core.content.pm.ChooserTargetServiceCompat, który jest już zdefiniowany w AndroidzieX:

<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 na temat udostępniania skrótów

Jak są przechowywane dane o korzystaniu ze skrótów i czy użytkownik opuszcza urządzenie?

Skróty są w całości przechowywane na urządzeniu, w systemowym katalogu danych, w 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.

Jaka jest historia bezpośredniego udostępniania?

Wprowadziliśmy bezpośrednie udostępnianie 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 odpowiedzi na żądanie, co prowadziło do długiego czasu wczytywania celów.

W Androidzie 10 (poziom API 29) zastąpiliśmy interfejsy API ChooserTargetService Direct Share nowym interfejsem Share Shortcuts API. Zamiast reaktywnego pobierania wyników na żądanie, interfejs Share Shortcuts API umożliwia aplikacjom z wyprzedzeniem publikowanie celów bezpośredniego udostępniania. Podczas przygotowywania arkusza ShareSheet szybko przyspieszyło to pobieranie celów bezpośredniego udostępniania. Mechanizm ChooserTargetService bezpośredniego udostępniania będzie nadal działać, ale system będzie klasyfikować cele udostępniane w ten sposób niżej od wszystkich celów, które korzystają z interfejsu Share Shortcuts API.

Android 11 (poziom interfejsu API 30) wycofał usługę ChooserTargetService, a interfejsSharing Shortcuts API to jedyny sposób określania wartości docelowych w ramach bezpośredniego udostępniania.

Czym opublikowane skróty do celów udostępniania różnią się od skrótów w Menu z aplikacjami (typowego korzystania ze skrótów przy przytrzymaniu ikony aplikacji w programie uruchamiającym)?

Wszystkie skróty opublikowane do celów udostępniania są również skrótem w programie uruchamiającym i będą widoczne w menu po przytrzymaniu ikony aplikacji. Limit maksymalnej liczby skrótów na działanie dotyczy też łącznej liczby skrótów publikowanych przez aplikację (kombinacji elementów docelowych i starszych skrótów w programie uruchamiającym).

Jaką liczbę skrótów do udostępniania należy opublikować?

Liczba skrótów do udostępniania jest ograniczona do tego samego limitu dynamicznych skrótów, które jest dostępne w getMaxShortcutCountPerActivity(android.content.Context). Do tego limitu można opublikować dowolną liczbę, ale trzeba pamiętać, że skróty udostępniania mogą być widoczne po przytrzymaniu w menu z aplikacjami i w arkuszu udostępniania. Większość programów uruchamiających aplikacje po długim naciśnięciu wyświetla maksymalnie 4–5 skrótów w trybie pionowym i 8 w trybie poziomym. Przeczytaj te najczęstsze pytania, aby dowiedzieć się więcej i uzyskać wskazówki na temat udostępniania skrótów.