Podaj cele udostępniania bezpośredniego

Rysunek 1. Wiersz udostępniania bezpośredniego w arkuszu udostępniania, jak widać na przykładzie 1

Korzystaj z celów udostępniania bezpośredniego, aby użytkownicy innych aplikacji mogli łatwiej i szybciej udostępniać adresy URL, obrazy lub inne dane Twojej aplikacji. Udostępnianie bezpośrednie polega na wyświetlaniu kontaktów z komunikatorów i aplikacji społecznościowych bezpośrednio w arkuszu udostępniania Androida bez konieczności wyboru aplikacji, a następnie wyszukiwania kontaktu.

ShortcutManagerCompat to interfejs API AndroidX, który udostępnia skróty udostępniania, zgodny wstecznie 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 dotyczącej używania AndroidaX do podawania skrótów udostępniania i celów wyboru na tej stronie.

Publikowanie celów udostępniania bezpośredniego

Wiersz udostępniania bezpośredniego arkusza udostępniania zawiera tylko skróty dynamiczne udostępnione przez interfejsSharing Skróty API. Aby opublikować docelowe udostępnianie bezpośrednie, wykonaj te 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 funkcji 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ć najpopularniejsze rozmowy uporządkowane według czasu pojawienia się w aplikacji. Nie publikuj nieaktualnych skrótów. Rozmowy bez aktywności użytkownika w ciągu ostatnich 30 dni 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 opracowujesz aplikację do komunikacji, zgłaszaj użycie skrótu na stronie pushDynamicShortcut natychmiast za każdym razem, gdy użytkownik otrzyma lub wyśle do kontaktu wiadomość. Więcej informacji znajdziesz w artykule na temat zgłaszania używania skrótów do aplikacji do komunikacji na tej stronie. Możesz na przykład raportować użycie wiadomości wysyłanych przez użytkownika, określając w skrócie powiązania możliwości 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 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. 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));

Popraw rankingi celów udostępniania bezpośredniego

Arkusz udostępniania Androida pokazuje stałą liczbę celów udostępniania bezpośredniego. Są one sortowane według pozycji w rankingu. Możesz poprawić pozycję swoich skrótów, wykonując te czynności:

  • Upewnij się, że wszystkie elementy typu shortcutIds są unikalne i nigdy nie są wykorzystywane ponownie na potrzeby różnych celów.
  • Aby skrót był długotrwały, wywołaj metodę setLongLived(true).
  • W przypadku skrótów związanych z rozmowami zgłoś ich użycie do wiadomości wychodzących i przychodzących, ponownie publikując te skróty za pomocą narzędzia ShortcutManagerCompat.pushDynamicShortcut. Więcej informacji znajdziesz w sekcji na temat zgłaszania używania skrótów do aplikacji do komunikacji na tej stronie.
  • Unikaj podawania nietrafnych lub nieaktualnych celów udostępniania bezpośredniego, np. kontaktów, z którymi użytkownik nie wysyłał wiadomości w ciągu ostatnich 30 dni.
  • W przypadku aplikacji do obsługi SMS-ów nie podawaj skrótów do krótkich kodów lub rozmów zidentyfikowanych jako potencjalny spam. Użytkownicy z dużym prawdopodobieństwem nie będą udostępniać informacji w tych rozmowach.
  • Wywołaj setCategories(), aby powiązać skrót z odpowiednimi atrybutami mimeType. Na przykład w przypadku aplikacji do obsługi SMS-ów, jeśli kontakt nie obsługuje czatów RCS ani MMS-ów, skrót nie powinien być powiązany z typami MIME nietekstowymi, takimi jak image/* czy video/*.
  • Po przekazaniu skrótu dynamicznego i zgłoszeniu użycia w przypadku danego wątku nie zmieniaj identyfikatora skrótu. Zapewnia to przechowywanie danych o korzystaniu na potrzeby rankingu.

Jeśli użytkownik kliknie cel udostępniania bezpośredniego, aplikacja musi wyświetlić go w interfejsie, w którym będzie mógł wykonać działanie na obiekcie docelowym. Nie przedstawiaj użytkownikowi interfejsu umożliwiającego ujednoznacznienie wyboru ani nie umieszczaj go w interfejsie niepowiązanym z klikniętym celem. Na przykład w aplikacji do obsługi wiadomości kliknięcie celu udostępniania bezpośredniego powoduje przejście do widoku rozmowy z wybraną osobą. Klawiatura jest widoczna, a wiadomość jest wstępnie uzupełniona udostępnianymi danymi.

Udostępnianie skrótów API

W Androidzie 10 (poziom interfejsu API 29) usługa ShortcutInfo.Builder dodała metody i ulepszenia, które dostarczają dodatkowe informacje o celu udostępniania:

setCategories()
Począwszy od Androida 10 kategorie są też używane do filtrowania skrótów obsługujących intencje lub działania związane z udostępnianiem. Szczegółowe informacje znajdziesz w sekcji Deklarowanie celu udziału. To pole jest wymagane w przypadku skrótów, które mają być używane jako cele udostępniania.
setLongLived()

Określa, czy skrót jest prawidłowy, gdy został wycofany z publikacji lub stał się niewidoczny przez aplikację (jako skrót dynamiczny lub przypięty). Jeśli skrót działa przez długi czas, różne usługi systemowe mogą go zapisywać w pamięci podręcznej, nawet jeśli ich publikacja została cofnięta jako skrót dynamiczny.

Długotrwałe skróty mogą poprawić jej pozycję w rankingu. Więcej informacji znajdziesz w artykule Uzyskiwanie najlepszych wyników.

setShortLabel(), setLongLabel()

Publikując skrót do osoby, umieść jej imię i nazwisko w polu setLongLabel(), a wszelkie krótkie imię, np. pseudonim lub imię, w polu setShortLabel().

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

Dodaj zdjęcia do skrótów

Aby utworzyć skrót do udostępniania, musisz dodać obraz w aplikacji setIcon().

Skróty udostępniania mogą pojawiać się na różnych platformach systemu, a ich kształt może się zmieniać. Poza tym na niektórych urządzeniach z Androidem w wersji 7, 8 lub 9 (poziomy interfejsu API 25, 26, 27 i 28) mogą wyświetlać się ikony bitmapy bez tła, co znacznie zmniejsza kontrast. Aby skrót wyglądał prawidłowo, udostępnij adaptacyjną mapę bitową za pomocą narzędzia IconCompat.createWithAdaptiveBitmap().

Upewnij się, że adaptacyjne mapy bitowe są zgodne z wytycznymi i wymiarami ustawionymi dla ikon adaptacyjnych. Najczęstszym sposobem na osiągnięcie tego celu jest przeskalowanie odpowiedniej kwadratowej mapy bitowej do 72 x 72 dp i wyśrodkowanie jej na przezroczystej mapie o wymiarach 108 x 108 dp. Jeśli ikona zawiera przezroczyste obszary, musisz też użyć koloru tła. W przeciwnym razie przezroczyste obszary będą miały kolor czarny.

Nie udostępniaj obrazów zamaskowanego określonego kształtu. Na przykład przed Androidem 10 (poziom interfejsu API 29) często udostępniać awatary użytkowników na potrzeby udostępniania bezpośredniego ChooserTarget, które były zamaskowane w kółku. Arkusz udostępniania Androida i inne elementy systemu w Androidzie 10 mają teraz kształt i motywy skrótów. Preferowana metoda udostępniania skrótów do udostępniania (ShortcutManagerCompat) automatycznie kształtuje obiekty Backcompat bezpośredniego udostępniania ChooserTarget w kręgach za Ciebie.

Deklarowanie docelowego udostępniania

Cele udostępniania muszą być zadeklarowane w pliku zasobów aplikacji, podobnie jak definicje skrótów statycznych. Dodaj definicje celów udostępniania wewnątrz elementu głównego <shortcuts> w pliku zasobów, wraz z innymi statycznymi definicjami skrótów. Każdy element <share-targets> zawiera informacje o typie danych udostępnianych, 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 miejscu docelowym udostępniania jest podobny do specyfikacji danych w filtrze intencji. Każde miejsce docelowe udostępniania może mieć wiele kategorii, które służą tylko do dopasowywania opublikowanych skrótów aplikacji do definicji celów udostępniania. Kategorie mogą mieć dowolne wartości zdefiniowane przez aplikację.

Jeśli w arkuszu udostępniania Androida użytkownik wybierze skrót do udostępniania, który pasuje do podanego wyżej przykładu udostępniania celu, 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 cel udostępniania za pomocą skrótów programu uruchamiającego, aplikacja pobierze intencję utworzoną podczas dodawania skrótu do udostępniania do metody SkrótyManagerCompat. Intencją jest inna intencja, więc Intent.EXTRA_SHORTCUT_ID nie będzie dostępny, a w razie potrzeby trzeba będzie przekazać identyfikator ręcznie.

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

Jeśli opracowujesz aplikację do komunikacji, możesz poprawić jej 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 reprezentujący kontakt za pomocą ShortcutManagerCompat.pushDynamicShortcut.

Powiązania skrótów i funkcji są zgodne wstecz z Androidem 5.0 (API 21).

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

Raportowanie wykorzystania wiadomości wysyłanych przez użytkownika działa podobnie do kliknięcia przycisku „Wyślij” po utworzeniu wiadomości.

Aby aktywować raportowanie wykorzystania, określ powiązania możliwości w skrócie, używając 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);

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

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łoś użycie skrótu do wiadomości przychodzących

Aby aktywować raportowanie wykorzystania, gdy użytkownik otrzyma wiadomość, np. SMS-a, wiadomość na czacie, e-maila lub powiadomienie, musisz dodatkowo określić w skrócie powiązania możliwości za pomocą metody 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 wiadomość przychodząca pochodzi z czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ sender jest powiązany z możliwością.

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żyj AndroidX, aby zapewnić zarówno skróty udostępniania, jak i cele wyboru

Aby aplikacja mogła korzystać z biblioteki zgodności AndroidX, jej plik manifestu musi zawierać zestaw metadanych-dataChooser-target-service i Intent-filters. Zapoznaj się z obecnym interfejsem API ChooserTargetService do udostępniania bezpośredniego.

Ta usługa jest już zadeklarowana w bibliotece zgodności, więc użytkownik nie musi jej deklarować w pliku manifestu aplikacji. Link z udostępniania do usługi musi być jednak traktowany jako dostawca docelowy wyboru.

W tym przykładzie implementacja ChooserTargetService to androidx.core.content.pm.ChooserTargetServiceCompat, która jest już zdefiniowana 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>

Skróty udostępniania – najczęstsze pytania

W jaki sposób dane o korzystaniu ze skrótu są przechowywane i czy użytkownik opuszcza urządzenie?

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

Jak wygląda historia udostępniania bezpośredniego?

Wprowadziliśmy funkcję udostępniania bezpośredniego 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 spowodowało wydłużenie czasu wczytywania celów.

W Androidzie 10 (poziom API 29) zastąpiliśmy interfejsy ChooserTargetService Direct Share API w ramach nowego interfejsu Share Skróty API. Zamiast pobierać wyniki reaktywnie na żądanie, interfejs udostępniania Skróty API umożliwia aplikacjom publikowanie celów udostępniania bezpośredniego z wyprzedzeniem. To szybko przyspieszyło proces pobierania celów udostępniania bezpośredniego podczas przygotowywania arkusza ShareSheet. Mechanizm udostępniania bezpośredniego ChooserTargetService będzie nadal działać, ale system określa podawane w ten sposób wartości docelowe poniżej poziomu celu, który korzysta z interfejsu Udostępnianie Skróty API.

Android 11 (poziom interfejsu API 30) wycofał usługę ChooserTargetService, a interfejs Udostępnianie skrótów to jedyny sposób udostępniania celów udostępniania bezpośredniego.

Czym opublikowane skróty do celów udostępniania różnią się od skrótów w Menu z aplikacjami (to typowe użycie skrótów przy długim naciśnięciu ikon w Menu z aplikacjami)?

Wszystkie skróty opublikowane w celu udostępniania celu są również skrótami programu uruchamiającego i są wyświetlane w menu po długim naciśnięciu ikony aplikacji. Limit maksymalnej liczby skrótów na działanie odnosi się też do łącznej liczby skrótów publikowanych przez aplikację (połączonych elementów docelowych i starszych skrótów programu uruchamiającego).

Jaka jest wskazówka dotycząca liczby skrótów udostępniania, które należy opublikować?

Liczba skrótów udostępniania jest ograniczona do tego samego limitu dynamicznych skrótów dostępnych w getMaxShortcutCountPerActivity(android.content.Context). W ramach tego limitu można opublikować dowolną liczbę, ale pamiętaj, że skróty do udostępnienia mogą być widoczne po naciśnięciu i przytrzymaniu w menu z aplikacjami oraz w arkuszu udostępniania. Większość programów uruchamiających aplikacje po naciśnięciu przy długim naciśnięciu wyświetla maksymalnie 4 lub 5 skrótów w trybie pionowym i osiem w trybie poziomym. Więcej informacji i wskazówek na temat udostępniania skrótów znajdziesz w Najczęstszych pytaniach.

Wstecz
Odbieranie prostych danych z innych aplikacji