Podaj cele udostępniania bezpośredniego

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

)

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 do Twojej aplikacji. Udostępnianie bezpośrednie działa poprzez wyświetlanie kontaktów z aplikacji do obsługi wiadomości i mediów społecznościowych bezpośrednio na karcie udostępniania w Androidzie, bez konieczności wybierania aplikacji i wyszukiwania kontaktu.

ShortcutManagerCompat to interfejs API AndroidX, który udostępnia skróty do udostępniania i jest zgodny wstecz z wycofanym interfejsem API ChooserTargetService. Jest to preferowany sposób 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 odbiorcó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ć cele udostępniania bezpośredniego:

1. 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>
   

2. Podczas inicjowania aplikacji użyj atrybutu setDynamicShortcuts, aby uporządkować skróty dynamiczne według ich ważności.

   Im niższy indeks, tym większa ważność. Jeśli tworzysz aplikację do komunikacji, mogą to być najczęściej prowadzone rozmowy uporządkowane według daty, w jakiej pojawiają 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 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łaszanie korzystania z skrótów w komunikatorach. Na przykład możesz zgłaszać wykorzystanie w raportach w przypadku wiadomości wysyłanych przez użytkownika, określając w skrótach powiązania z funkcjami 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 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 znajduje się 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 w rankingu odbiorców udostępniania bezpośredniego

Na karcie udostępniania w Androidzie jest widoczna stała liczba odbiorców udostępniania bezpośredniego. Te sugestie są sortowane według rangi. Aby poprawić pozycję swoich skrótów, wykonaj te czynności:

• Upewnij się, że wszystkie wartości atrybutu shortcutIds są unikalne i nigdy nie są używane ponownie w przypadku innych wartości docelowych.
• Aby mieć pewność, że skrót będzie długotrwały, wywołaj go za pomocą polecenia setLongLived(true).
• W przypadku skrótów związanych z rozmowami możesz zgłaszać korzystanie z nich w przypadku wiadomości wychodzących i przychodzących, publikując odpowiednie skróty za pomocą 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 SMS-ów nie podawaj skrótów do krótkich kodów ani rozmów zidentyfikowanych jako potencjalny spam. Użytkownicy prawdopodobnie nie będą udostępniać tych rozmów.
• Wywołaj funkcję setCategories(), aby powiązać skrót z odpowiednimi atrybutami mimeType. Jeśli na przykład kontakt nie obsługuje RCS ani MMS-ów, nie będziesz mógł powiązać odpowiedniego skrótu z typami MIME innych niż tekst, takimi jak image/* i video/*.
• 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 obiekt udostępniania bezpośredniego, aplikacja musi przekierować go do interfejsu, w którym może wykonać działanie bezpośrednio na obiekcie. Nie wyświetlaj użytkownikowi interfejsu rozróżniania ani nie umieszczaj go w interfejsie niezwiązanym z docelowym elementem dotykowym. Na przykład w aplikacji do przesyłania 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 Oświadczenie o 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 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 skrótu dynamicznego.

Długotrwałość skrótu może poprawić jego pozycję w rankingu. Więcej informacji znajdziesz w artykule Osiąganie najlepszej pozycji w wynikach wyszukiwania.

setShortLabel(), setLongLabel()

Podczas publikowania skrótu do osoby fizycznej podaj jej pełne imię i nazwisko w polu setLongLabel(), a w polu setShortLabel() – 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().

Skróty udostępniania mogą pojawiać się w różnych miejscach w systemie i mogą mieć zmieniony kształt. Dodatkowo na niektórych urządzeniach z Androidem 7, 8 lub 9 (poziom interfejsu API 25, 26, 27 lub 28) mogą wyświetlać się ikony tylko w formie bitmapy 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 bitmapy adaptacyjne są zgodne z tymi samymi wytycznymi i wymiarami, które obowiązują w przypadku ikon adaptacyjnych. Najczęstszym sposobem na to jest przeskalowanie kwadratowej bitmapy do rozmiaru 72 x 72 dp i umieszczenie jej na przezroczystym płótnie 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 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 maskowane 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 skrótów statycznych. 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 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 docelowym obiekcie udostępniania jest podobny do specyfikacji danych w filtrze intencji. Każdy obiekt udostępniania może mieć kilka kategorii, które są używane tylko do dopasowywania opublikowanych skrótów aplikacji do definicji obiektów udostępniania. 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 docel 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żywania skrótów w aplikacjach do komunikacji

Jeśli tworzysz aplikację do komunikacji, możesz poprawić swoje miejsce w ramach panelu udostępniania Androida, zgłaszając wykorzystanie zarówno wiadomości wychodzących, jak i przyjmowanych. Aby to zrobić, ponownie opublikuj skrót rozmowy reprezentujący 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 działa podobnie 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.

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 wychodząca wiadomość jest przeznaczona do 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 korzystania ze skrótów w przypadku wiadomości przychodzących

Aby wywołać raportowanie użycia, gdy użytkownik otrzyma wiadomość SMS, wiadomość w Google Chat, e-maila lub powiadomienie, musisz dodatkowo określić powiązania możliwości w skrótach za pomocą funkcji 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 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żywanie AndroidX do udostępniania skrótów i obiektów ChooserTargets

Aby można było korzystać z biblioteki zgodności AndroidX, manifest aplikacji musi zawierać zestaw metadanych chooser-target-service i intent-filters. 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. Należy jednak wziąć pod uwagę link z działania udostępniania do usługi jako dostawcę celu w wybieraczu.

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 w skrótach, takie jak ikona, intencje oraz 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 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 reakcji na żądanie, co powodowało długi czas wczytywania elementów docelowych.

W Androidzie 10 (poziom interfejsu API 29) zastąpiliśmy interfejsy API ChooserTargetService DirectShare interfejsem Sharing Shortcuts API. Zamiast pobierania wyników w reakcji na żądanie interfejs API skrótów udostępniania pozwala aplikacjom publikować cele udostępniania bezpośredniego z wyprzedzeniem. Dzięki temu znacznie przyspieszyliśmy proces pobierania danych dotyczących odbiorców udostępniania bezpośredniego podczas przygotowywania arkusza udostępniania. Mechanizm ChooserTargetService bezpośredniego udostępniania będzie nadal działać, ale system będzie wyżej klasyfikować cele udostępniane w ten sposób niż cele korzystające 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ę publikowane skróty do celów udostępniania od skrótów w menu (czyli skrótów, które są używane po przytrzymaniu ikony aplikacji w menu)?

Wszystkie skróty opublikowane jako „docelnik udostępniania” są też skrótami w menu i pojawiają się w menu po długim naciśnięciu ikony aplikacji. 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 trybie pionowym i 8 w trybie poziomym. Więcej informacji i wskazówek na temat udostępniania skrótów znajdziesz w najczęstszych pytaniach.