Podaj cele udostępniania bezpośredniego

Użyj odbiorców udostępniania bezpośredniego, aby ułatwić i przyspieszyć użytkownikom innych aplikacji udostępnianie adresów URL, obrazów lub innych rodzajów danych w 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 w arkuszu udostępniania Androida, bez konieczności wybierania aplikacji przez użytkowników, a następnie wyszukiwania kontaktu.

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

Publikowanie odbiorców udostępniania bezpośredniego

Wiersz udostępniania bezpośredniego w arkuszu udostępniania wyświetla tylko skróty dynamiczne udostępniane przez interfejs Sharing Shortcuts API. Aby opublikować odbiorców 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 się zainicjuje, użyj setDynamicShortcuts aby uporządkować skróty dynamiczne według ważności.

   Niższy indeks oznacza większą ważność. Jeśli tworzysz aplikację do komunikacji, mogą to być najważniejsze rozmowy uporządkowane według daty, w jakiej pojawiły się w aplikacji. Nie publikuj nieaktualnych skrótów. Rozmowa, w której nie było aktywności użytkownika w ciągu ostatnich 30 dni, jest uważana 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ą 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. Na przykład zgłoś użycie wiadomości wysłanych przez użytkownika, określając powiązania możliwości w skrócie 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);

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 zapisany w pamięci podręcznej usług systemowych. 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 w Androidzie wyświetla stałą liczbę odbiorców udostępniania bezpośredniego. Te sugestie są sortowane według pozycji. Pozycję skrótów możesz poprawić, wykonując te czynności:

• Upewnij się, że wszystkie shortcutIds są unikalne i nigdy nie są ponownie używane w przypadku różnych odbiorców.
• Upewnij się, że skrót jest długotrwały, wywołując setLongLived(true).
• W przypadku skrótów związanych z rozmową zgłaszaj użycie skrótu w przypadku wiadomości wychodzących i przychodzących, ponownie publikując odpowiednie skróty za pomocą ShortcutManagerCompat.pushDynamicShortcut. Więcej informacji znajdziesz w sekcji Zgłaszanie użycia skrótów w aplikacjach do komunikacji na tej stronie.
• Unikaj udostępniania nieistotnych lub nieaktualnych odbiorców udostępniania bezpośredniego, np. kontaktów, z którymi użytkownik nie kontaktował się w ciągu ostatnich 30 dni.
• W przypadku aplikacji SMS unikaj udostępniania skrótów do krótkich kodów lub rozmów oznaczonych jako potencjalny spam. Jest mało prawdopodobne, że użytkownicy będą udostępniać treści w tych rozmowach.
• Wywołaj setCategories(), aby powiązać skrót z odpowiednimi mimeType atrybutami. Na przykład w przypadku aplikacji do SMS-ów, jeśli kontakt nie obsługuje RCS ani MMS, nie powiążesz odpowiedniego skrótu z typami MIME innymi niż tekstowe, takimi jak image/* i video/*.
• W przypadku danej rozmowy, gdy skrót dynamiczny zostanie przesłany i zgłoszone zostanie jego użycie, nie zmieniaj identyfikatora skrótu. Zapewnia to zachowanie danych o użyciu na potrzeby ustalania pozycji.

Jeśli użytkownik kliknie dowolnego odbiorcę udostępniania bezpośredniego, Twoja aplikacja musi przenieść go do interfejsu, w którym może wykonać działanie bezpośrednio na obiekcie odbiorcy. Nie wyświetlaj użytkownikowi interfejsu do rozróżniania i nie przenoś go do interfejsu niezwiązanego z klikniętym odbiorcą. Na przykład w komunikatorze kliknięcie odbiorcy 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

Od Androida 10 (interfejs API na poziomie 29), ShortcutInfo.Builder dodaliśmy metody i ulepszenia które zapewniają dodatkowe informacje o odbiorcy 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 udostępniania. Więcej informacji znajdziesz w sekcji Deklarowanie odbiorcy udostępniania. To pole jest wymagane w przypadku skrótów, które mają być używane jako odbiorcy udostępniania.

setLongLived()

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

Ustawienie skrótu jako długotrwałego może poprawić jego pozycję. Więcej informacji znajdziesz w sekcji Uzyskiwanie najlepszej pozycji.

setShortLabel(), setLongLabel()

Podczas publikowania skrótu dla konkretnej osoby podaj jej pełne imię i nazwisko w setLongLabel() oraz dowolną krótką nazwę, np. pseudonim lub imię, w setShortLabel().

Przykład publikowania skrótów udostępniania znajdziesz na GitHubie.

Udostępnianie obrazów skrótów

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

Skróty udostępniania mogą pojawiać się w różnych usługach systemowych i mogą być zmieniane. Dodatkowo niektóre urządzenia z Androidem w wersji 7, 8 lub 9 (interfejs API na poziomie 25, 26, 27 i 28) mogą wyświetlać ikony tylko w formacie bitmapy bez tła, co znacznie zmniejsza kontrast. Aby skrót wyglądał zgodnie z oczekiwaniami, użyj IconCompat.createWithAdaptiveBitmap() i podaj bitmapę adaptacyjną.

Upewnij się, że bitmapy adaptacyjne są zgodne z tymi samymi wytycznymi i wymiarami co ikony adaptacyjne. Najczęstszym sposobem na to jest przeskalowanie docelowej kwadratowej bitmapy do rozmiaru 72 x 72 dp i wyśrodkowanie jej na przezroczystym obszarze o wymiarach 108 x 108 dp. Jeśli ikona zawiera przezroczyste obszary, musisz dodać kolor tła. W przeciwnym razie przezroczyste obszary będą czarne.

Nie udostępniaj 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 dla ChooserTarget udostępniania bezpośredniego, które były maskowane do kształtu koła. Arkusz udostępniania w Androidzie i inne platformy systemowe w Androidzie 10 kształtują i stylizują obrazy skrótów. Preferowana metoda udostępniania skrótów udostępniania za pomocą ShortcutManagerCompat, automatycznie kształtuje obiekty udostępniania bezpośredniego ChooserTarget w kształt koła.

Deklarowanie odbiorcy udostępniania

Odbiorcy udostępniania muszą być zadeklarowani w pliku zasobów aplikacji, podobnie jak definicje skrótów statycznych. Dodaj definicje odbiorców udostępniania w elemencie głównym <shortcuts> w pliku zasobów wraz z innymi definicjami skrótów statycznych. Każdy <share-targets> element 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 odbiorcy udostępniania jest podobny do specyfikacji danych w filtrze intencji. Każdy odbiorca udostępniania może mieć wiele kategorii, które są używane tylko do dopasowywania opublikowanych skrótów aplikacji do definicji odbiorców udostępniania. Kategorie mogą mieć dowolne wartości zdefiniowane przez aplikację.

Jeśli użytkownik wybierze skrót udostępniania w arkuszu udostępniania w Androidzie, który pasuje do powyższego przykładu odbiorcy udostępniania, aplikacja otrzyma tę 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 odbiorcę udostępniania ze skrótów w programie uruchamiającym, aplikacja otrzyma intencję utworzoną podczas dodawania skrótu do udostępnienia do ShortcutManagerCompat. Ponieważ jest to inna intencja, Intent.EXTRA_SHORTCUT_ID nie będzie dostępny i w razie potrzeby będziesz musiał ręcznie przekazać identyfikator.

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 w Androidzie, zgłaszając użycie 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ótów i powiązania możliwości są wstecznie zgodne z Androidem 5.0 (interfejs API na poziomie 21).

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

Zgłaszanie użycia wiadomości wysłanych przez użytkownika jest funkcjonalnie podobne do kliknięcia przycisku „Wyślij” po utworzeniu wiadomości.

Aby wywołać zgłaszanie użycia, określ powiązania możliwości w skrócie za pomocą ShortcutInfoCompat.Builder#addCapabilityBinding z możliwością 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ść Audience parametru, ponieważ typ recipient jest powiązany z możliwością.

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 w przypadku wiadomości przychodzących

Aby wywołać zgłaszanie użycia, gdy użytkownik otrzyma wiadomość, np. SMS, wiadomość na czacie, e-mail lub powiadomienie, musisz dodatkowo określić powiązania możliwości w skrócie za pomocą ShortcutInfoCompat.Builder#addCapabilityBinding z możliwością 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ść Audience parametru, ponieważ typ sender jest powiązany z możliwością.

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

Korzystanie z AndroidX do udostępniania skrótów udostępniania i ChooserTargets

Aby móc korzystać z biblioteki zgodności AndroidX, manifest aplikacji musi zawierać metadane chooser-target-service i ustawione filtry intencji. Zobacz bieżący 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. Należy jednak wziąć pod uwagę link z aktywności udostępniania do usługi jako dostawcy odbiorców.

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życiu skrótów i czy opuszczają one 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 imiona i nazwiska 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 (interfejs API na poziomie 23) wprowadziliśmy udostępnianie bezpośrednie, aby umożliwić aplikacjom udostępnianie obiektów ChooserTarget za pomocą ChooserTargetService. Wyniki były pobierane reaktywnie na żądanie, co powodowało długi czas wczytywania odbiorców.

W Androidzie 10 (interfejs API na poziomie 29) zastąpiliśmy interfejsy ChooserTargetService Direct Share API nowym interfejsem Sharing Shortcuts API. Zamiast pobierać wyniki reaktywnie na żądanie, interfejs Sharing Shortcuts API umożliwia aplikacjom publikowanie odbiorców udostępniania bezpośredniego z wyprzedzeniem. Znacznie przyspieszyło to proces pobierania odbiorców udostępniania bezpośredniego podczas przygotowywania arkusza udostępniania. Mechanizm udostępniania bezpośredniego ChooserTargetService będzie nadal działać, ale system będzie przyznawać odbiorcom udostępnianym w ten sposób niższą pozycję niż odbiorcom korzystającym z interfejsu Sharing Shortcuts API.

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

Czym różnią się opublikowane skróty dla odbiorców udostępniania od skrótów w programie uruchamiającym (typowe użycie skrótów podczas długiego naciśnięcia ikon aplikacji w programie uruchamiającym)?

Wszystkie skróty opublikowane na potrzeby „odbiorcy udostępniania” są też skrótami w programie uruchamiającym i będą wyświetlane 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ę (odbiorców udostępniania i starszych skrótów w programie uruchamiającym).

Ile skrótów udostępniania należy opublikować?

Liczba skrótów udostępniania jest ograniczona do tego samego limitu skrótów dynamicznych dostępnych za pomocą getMaxShortcutCountPerActivity(android.content.Context). Możesz opublikować dowolną liczbę skrótów do tego limitu, ale musisz pamiętać, że skróty udostępniania mogą być widoczne w programie uruchamiającym aplikację po długim naciśnięciu i w arkuszu udostępniania. Większość programów uruchamiających aplikacje wyświetla maksymalnie 4 lub 5 skrótów w trybie pionowym i 8 w trybie poziomym. Więcej informacji i wskazówek dotyczących skrótów udostępniania znajdziesz w tym artykule.