Podaj cele udostępniania bezpośredniego

Używaj elementów docelowych udostępniania bezpośredniego, aby ułatwić i przyspieszyć udostępnianie adresów URL, obrazów i innych rodzajów danych w Twojej aplikacji przez użytkowników innych aplikacji. Udostępnianie bezpośrednie działa w ten sposób, że wyświetla kontakty z aplikacji do przesyłania wiadomości i aplikacji społecznościowych bezpośrednio na arkuszu udostępniania Androida, bez konieczności wybierania aplikacji przez użytkowników, a następnie wyszukiwania kontaktu.

ShortcutManagerCompat to interfejs API AndroidX, który udostępnia skróty do udostępniania i jest wstecznie zgodny z wycofanym interfejsem API ChooserTargetService. Jest to preferowany sposób publikowania zarówno skrótów do udostępniania, jak i ChooserTargets. Instrukcje znajdziesz w sekcji Używanie biblioteki AndroidX do udostępniania skrótów i elementów docelowych selektora na tej stronie.

Publikowanie odbiorców udostępniania bezpośredniego

Wiersz bezpośredniego udostępniania na arkuszu udostępniania zawiera tylko skróty dynamiczne udostępniane przez interfejs Sharing Shortcuts API. Aby opublikować miejsca docelowe udostępniania bezpośredniego:

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. Gdy aplikacja zostanie zainicjowana, użyj setDynamicShortcuts, aby uporządkować skróty dynamiczne według ważności.

   Niższy indeks oznacza większe znaczenie. Jeśli tworzysz aplikację do komunikacji, mogą to być najnowsze rozmowy uporządkowane według daty, tak jak pojawiają się w aplikacji. Nie publikuj skrótów, które są nieaktualne. Rozmowa, w której w ciągu ostatnich 30 dni nie było aktywności użytkownika, jest uznawana za nieaktualną.

   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ótu za pomocą funkcji pushDynamicShortcut natychmiast za każdym razem, gdy użytkownik otrzyma lub wyśle wiadomość do kontaktu. Więcej informacji znajdziesz w sekcji Raportowanie użycia skrótów w aplikacjach do komunikacji na tej stronie. Możesz na przykład raportować wykorzystanie wiadomości wysłanych przez użytkownika, określając powiązania funkcji w skrócie za pomocą 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 removeLongLivedShortcut. Jest to preferowany sposób usuwania skrótu, niezależnie od tego, czy jest on buforowany przez usługi systemowe. Poniższy fragment kodu pokazuje, jak to zrobić.

   Kotlin

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

   Java

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

Poprawianie pozycji odbiorców udostępniania bezpośredniego

Arkusz udostępniania na Androidzie wyświetla stałą liczbę odbiorców udostępniania bezpośredniego. Te sugestie są sortowane według rangi. Aby potencjalnie poprawić pozycję skrótów, możesz wykonać te czynności:

• Upewnij się, że wszystkie shortcutIds są unikalne i nigdy nie są używane ponownie w przypadku różnych miejsc docelowych.
• Aby skrót był długotrwały, wywołaj setLongLived(true).
• W przypadku skrótów związanych z rozmową zgłaszaj użycie skrótów w przypadku wiadomości wychodzących i przychodzących, ponownie publikując odpowiednie skróty za pomocą ShortcutManagerCompat.pushDynamicShortcut. Szczegółowe informacje znajdziesz w sekcji Zgłaszanie skrótów w aplikacjach do komunikacji na tej stronie.
• Unikaj podawania nieistotnych lub nieaktualnych elementów docelowych udostępniania bezpośredniego, np. kontaktów, do których użytkownik nie wysyłał wiadomości w ciągu ostatnich 30 dni.
• W przypadku aplikacji do SMS-ów unikaj udostępniania skrótów do krótkich kodów lub rozmów oznaczonych jako potencjalny spam. Użytkownicy raczej nie będą udostępniać treści w tych rozmowach.
• Zadzwoń pod numer setCategories(), aby powiązać skrót z odpowiednimi atrybutami mimeType. Jeśli na przykład w przypadku aplikacji do obsługi SMS-ów kontakt nie ma włączonej obsługi RCS ani MMS-ów, nie powiążesz odpowiedniego skrótu z typami MIME innymi niż tekstowe, takimi jak image/* i video/*.
• W przypadku danego wątku, gdy dynamiczny skrót zostanie przesłany i zostanie zgłoszone jego użycie, nie zmieniaj identyfikatora skrótu. Zapewnia to przechowywanie danych o użytkowaniu na potrzeby określania pozycji.

Jeśli użytkownik kliknie dowolny element docelowy udostępniania bezpośredniego, aplikacja musi przekierować go do interfejsu, w którym może wykonać działanie bezpośrednio na obiekcie docelowym. Nie wyświetlaj użytkownikowi interfejsu disambiguation i nie umieszczaj go w interfejsie niezwiązanym z klikniętym elementem. Na przykład w aplikacji do przesyłania wiadomości kliknięcie elementu docelowego udostępniania bezpośredniego przenosi użytkownika do widoku rozmowy z wybraną osobą. Klawiatura jest widoczna, a wiadomość jest wstępnie wypełniona udostępnionymi danymi.

Sharing Shortcuts API

W Androidzie 10 (poziom interfejsu API 29)ShortcutInfo.Builder dodaliśmy metody i ulepszenia, które dostarczają dodatkowych informacji o docelowym miejscu udostępniania:

setCategories()

Od Androida 10 kategorie są też używane do filtrowania skrótów, które mogą obsługiwać intencje lub działania związane z udostępnianiem. Więcej informacji znajdziesz w artykule Deklarowanie celu udostępniania. To pole jest wymagane w przypadku skrótów, które mają być używane jako miejsca docelowe udostępniania.

setLongLived()

Określa, czy skrót jest prawidłowy, gdy został wycofany z publikacji lub ukryty przez aplikację (jako skrót dynamiczny lub przypięty). Jeśli skrót jest długotrwały, może być przechowywany w pamięci podręcznej różnych usług systemowych nawet po jego wycofaniu jako skrótu dynamicznego.

Długi czas przechowywania skrótu może poprawić jego pozycję. Więcej informacji znajdziesz w artykule Uzyskiwanie najlepszych wyników.

setShortLabel(), setLongLabel()

Jeśli publikujesz skrót dla konkretnej osoby, podaj jej pełne imię i nazwisko w polu setLongLabel(), a krótką nazwę, np. pseudonim lub imię, w polu setShortLabel().

Zapoznaj się z przykładem publikowania skrótów do udostępniania w GitHubie.

Dodaj obrazy skrótów

Aby utworzyć skrót do udostępniania, musisz dodać obraz, klikając setIcon().

Skróty do udostępniania mogą pojawiać się w różnych miejscach w systemie i mogą być zmieniane. Dodatkowo niektóre urządzenia z Androidem w wersji 7, 8 lub 9 (poziomy API 25, 26, 27 i 28) mogą wyświetlać ikony tylko w formacie bitmapy bez tła, co znacznie zmniejsza kontrast. Aby mieć pewność, że skrót będzie wyglądać zgodnie z oczekiwaniami, podaj adaptacyjną mapę bitową za pomocą IconCompat.createWithAdaptiveBitmap().

Upewnij się, że mapy bitowe adaptacyjne są zgodne z wytycznymi i wymiarami określonymi dla ikon adaptacyjnych. Najczęściej stosowanym sposobem jest skalowanie docelowej kwadratowej mapy bitowej do rozmiaru 72 x 72 dp i wyśrodkowanie jej na przezroczystym obszarze o rozmiarze 108 x 108 dp. Jeśli ikona zawiera przezroczyste obszary, musisz dodać kolor tła. W przeciwnym razie przezroczyste obszary będą czarne.

Nie podawaj obrazów zamaskowanych do określonego kształtu. Na przykład przed Androidem 10 (poziom interfejsu API 29) często udostępniano awatary użytkowników w przypadku funkcji bezpośredniego udostępnianiaChooserTarget, które były maskowane do kształtu koła. Arkusz udostępniania na Androidzie i inne usługi systemowe w Androidzie 10 mają teraz kształt i motyw obrazów skrótów. Preferowana metoda udostępniania skrótów do udostępniania, czyli ShortcutManagerCompat, automatycznie przekształca obiekty ChooserTarget bezpośredniego udostępniania w okręgi, aby zapewnić zgodność wsteczną.

Deklarowanie elementu docelowego udostępniania

Cele udostępniania muszą być zadeklarowane w pliku zasobów aplikacji, podobnie jak definicje skrótów statycznych. Dodaj definicje elementu shareTarget w elemencie głównym <shortcuts> w pliku zasobów wraz z innymi definicjami statycznych skrótów. Każdy element <share-targets> zawiera informacje o typie udostępnianych danych, pasujących kategoriach i klasie docelowej, która będzie obsługiwać 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 obiekcie docelowym udostępniania jest podobny do specyfikacji danych w filtrze intencji. Każdy cel udostępniania może mieć wiele kategorii, które są używane tylko do dopasowywania opublikowanych skrótów aplikacji do definicji celu udostępniania. Kategorie mogą mieć dowolne wartości zdefiniowane przez aplikację.

Jeśli użytkownik wybierze skrót udostępniania na arkuszu udostępniania Androida, który pasuje do powyższego przykładu udostępniania docelowego, 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 docelowy udostępniania ze skrótów w programie uruchamiającym, aplikacja otrzyma intencję utworzoną podczas dodawania skrótu udostępniania do ShortcutManagerCompat. Ponieważ jest to inny rodzaj intencji, funkcja Intent.EXTRA_SHORTCUT_ID nie będzie dostępna i w razie potrzeby musisz przekazać identyfikator ręcznie.

Zgłaszanie użycia skrótów w aplikacjach do komunikacji

Jeśli tworzysz aplikację do komunikacji, możesz poprawić jej pozycję w arkuszu udostępniania na Androidzie, zgłaszając użycie zarówno w przypadku wiadomości wychodzących, jak i przychodzących. Aby to zrobić, ponownie opublikuj skrót do rozmowy, który reprezentuje kontakt, za pomocą ikony ShortcutManagerCompat.pushDynamicShortcut.

Skróty i powiązania funkcji są wstecznie zgodne z Androidem 5.0 (API 21).

Raportowanie użycia skrótów w wiadomościach wychodzących

Raportowanie wykorzystania w przypadku wiadomości wysłanych przez użytkownika jest funkcjonalnie podobne do kliknięcia przycisku „Wyślij” po utworzeniu wiadomości.

Aby wywołać raportowanie użycia, określ powiązania funkcji w skrócie za pomocą 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 jest przeznaczona na czat grupowy, 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ótu w przypadku wiadomości przychodzących

Aby wywołać raportowanie użycia, gdy użytkownik otrzyma wiadomość, np. SMS-a, wiadomość na czacie, e-maila lub powiadomienie, musisz dodatkowo określić powiązania funkcji w skrócie za pomocą 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 przychodząca wiadomość 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);

Używaj AndroidX, aby udostępniać skróty udostępniania i elementy ChooserTarget

Aby można było korzystać z biblioteki zgodności AndroidX, plik manifestu aplikacji musi zawierać ustawienia metadanych chooser-target-service i filtrów intencji. Zobacz bieżący interfejs 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. Link z aktywności udostępniania do usługi musi być jednak brany pod uwagę jako dostawca celu 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 skrótów udostępniania

Jak są przechowywane dane o używaniu skrótów i czy opuszczają urządzenie?

Skróty są przechowywane w całości na urządzeniu w katalogu danych systemowych na zaszyfrowanej partycji dysku. Informacje w skrótach, takie jak ikona, intencja oraz 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 udostępniania bezpośredniego?

W Androidzie 6.0 (poziom interfejsu API 23) wprowadziliśmy funkcję bezpośredniego udostępniania, która umożliwia aplikacjom udostępnianie obiektów ChooserTarget za pomocą ChooserTargetService. Wyniki były pobierane reaktywnie na żądanie, co powodowało powolne wczytywanie celów.

W Androidzie 10 (poziom interfejsu API 29) zastąpiliśmy interfejsy ChooserTargetService Direct Share nowym interfejsem Sharing Shortcuts API. Zamiast pobierać wyniki reaktywnie na żądanie, interfejs Sharing Shortcuts API umożliwia aplikacjom publikowanie z wyprzedzeniem elementów docelowych udostępniania bezpośredniego. Znacznie przyspieszyło to proces pobierania elementów docelowych bezpośredniego udostępniania podczas przygotowywania arkusza udostępniania. Mechanizm ChooserTargetServicebezpośredniego udostępniania będzie nadal działać, ale system będzie klasyfikować cele dostarczane w ten sposób niżej niż cele korzystające z interfejsu Sharing Shortcuts API.

W Androidzie 11 (API na poziomie 30) usługa ChooserTargetService została wycofana, a interfejs Sharing Shortcuts API jest jedynym sposobem na udostępnianie bezpośrednich elementów docelowych.

Czym różnią się opublikowane skróty do celów udostępniania od skrótów do uruchamiania (typowego sposobu używania skrótów podczas długiego naciśnięcia ikon aplikacji w programie uruchamiającym)?

Każdy skrót opublikowany w celu „udostępniania” jest też skrótem do uruchamiania i będzie wyświetlany w menu po długim naciśnięciu ikony aplikacji. Limit maksymalnej liczby skrótów na aktywność dotyczy też łącznej liczby skrótów publikowanych przez aplikację (połączenie celów udostępniania i starszych skrótów do uruchamiania).

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 tego samego limitu skrótów dynamicznych dostępnych za pomocą getMaxShortcutCountPerActivity(android.content.Context). Można opublikować dowolną liczbę skrótów do tego limitu, ale należy pamiętać, że skróty do udostępniania mogą być widoczne po długim naciśnięciu ikony aplikacji w programie uruchamiającym i na karcie udostępniania. Większość programów uruchamiających aplikacje wyświetla maksymalnie 4–5 skrótów w trybie pionowym i 8 w trybie poziomym. Więcej informacji i wskazówek dotyczących udostępniania skrótów znajdziesz w tych najczęstszych pytaniach.