Podaj cele udostępniania bezpośredniego

Ilustracja 1. Wiersz Direct Share w arkuszu udostępniania (1

)

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 użytkownikom 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 na karcie udostępniania w Androidzie, bez konieczności wybierania aplikacji i wyszukiwania kontaktu.

Uwaga: od Androida 11 (poziom interfejsu API 30) można udostępniać bezpośrednie udostępnianie są kierowane tylko za pomocą interfejsu API Sharing Shortcuts opisanym w dalszej części wiadomości. tę stronę.

ShortcutManagerCompat to interfejs API AndroidaX, który udostępnia skróty do udostępniania zgodne z wycofanym interfejsem ChooserTargetService API. To jest preferowane sposób opublikowania skrótów do udostępniania i ChooserTargets. Instrukcje: Więcej informacji znajdziesz w sekcji Korzystanie z AndroidaX do obsługi skrótów udostępniania oraz wyboru celów. na tej stronie.

Opublikuj wartości docelowe bezpośredniego udostępniania

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 setDynamicShortcuts aby uporządkować skróty dynamiczne według ważności.

   Im niższy indeks, tym większa ważność. Jeśli komunikujesz się w aplikacji, mogą to być najważniejsze rozmowy uporządkowane według czasu do aplikacji. Nie publikuj nieaktualnych skrótów; rozmowa bez aktywność użytkowników w ciągu ostatnich 30 dni 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 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. Zobacz Raport o użyciu skrótów dla aplikacji do komunikacji na tej stronie. Na przykład zgłoś użycie wiadomości wysyłanych przez użytkownika przez określ powiązania możliwości 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. To jest preferowane sposób usunięcia skrótu niezależnie od tego, czy jest on zapisany w pamięci podręcznej usług Google. Poniżej znajdziesz 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));

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

Arkusz udostępniania Androida pokazuje stałą liczbę celów bezpośredniego udostępniania. Te sugestie są sortowane według rangi. Aby poprawić pozycję swoich skrótów:

• 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, używając polecenia setLongLived(true).
• W przypadku skrótów dotyczących rozmów zgłoś użycie skrótów dla wiadomości wychodzących i przychodzących przez ponowne opublikowanie odpowiednich skrótów do ShortcutManagerCompat.pushDynamicShortcut. Więcej informacji znajdziesz w sekcji Zgłaszanie korzystania z skrótów w komunikatorach na tej stronie.
• Unikaj podawania nietrafnych lub nieaktualnych celów bezpośredniego udziału, np. Kontakty, z którymi użytkownik nie wysłał wiadomości w ciągu ostatnich 30 dni.
• W przypadku aplikacji do obsługi SMS-ów unikaj podawania skrótów do krótkich kodów lub 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-a, nie będziesz wiązać odpowiadającego mu skrótu z typami MIME innych niż tekst, takimi jak image/* i video/*.
• Po przekazaniu dynamicznego skrótu i zastosowaniu w danej rozmowie nie zmieniaj identyfikatora skrótu. Zapewni to przechowywanie danych o korzystaniu dotyczące pozycji w rankingu.

Jeśli użytkownik kliknie cel bezpośredniego udostępniania, aplikacja musi przenieść go do interfejsu, w którym mogą wykonać działanie bezpośrednio na obiekcie, na który są kierowane. Nie prezentuj użytkownik zobaczy interfejs ujednoznacznienia i nie umieszczaj go w interfejsie niepowiązanym z kliknij cel. Na przykład w aplikacji do obsługi 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. Przeczytaj sekcję Deklarowanie udostępnienia . To pole jest wymagane w przypadku skrótów do wykorzystania jako wartości docelowych udostępniania.

setLongLived()

Określa, czy skrót jest prawidłowy po cofnięciu jego publikacji lub stały się niewidoczne 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 dynamicznego skrótu.

Długotrwałe zastosowanie skrótu może poprawić jego pozycję w rankingu. Zobacz najlepsze tytuły ranking, by dowiedzieć się więcej.

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.

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

Dodaj obrazy skrótów

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

Skróty udostępnione mogą pojawiać się w różnych miejscach w systemie i mogą być zmieniane. 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 formacie bitmapy bez tła, co znacznie zmniejsza kontrast. Aby mieć pewność, że skrót wygląda poprawnie, aby zapewnić adaptacyjną mapę bitową za pomocą interfejsu 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 osiągnięcia tego celu jest skalowanie odpowiedniej mapy bitowej do 72 x 72 dp i środek na przezroczystym obszarze 108 x 108 dp. Jeśli ikona zawiera przezroczyste obszary, musisz dodać kolor tła; w przeciwnym razie, przezroczyste obszary są czarne.

Nie przesyłaj obrazów zamaskowanych do określonego kształtu. Na przykład przed Androida 10 (poziom interfejsu API 29) i na potrzeby bezpośredniego udostępniania najczęściej umieszczano awatary użytkowników. Elementy ChooserTarget, które zostały zamaskowane pod kątem okręgu. 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 zasobów wraz z innymi definicjami statycznych skrótów. Każdy element <share-targets> zawiera informacje o typie udostępnianych danych, kategorii dopasowania oraz klasa docelowa, która będzie obsługiwać intencję udostępniania. Kod XML wygląda podobny do tego:

<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 obiekt udostępniania może mieć wiele kategorii, które są używane tylko do dopasowywania opublikowanych skrótów aplikacji do definicji obiektów udostępniania. Kategorie mogą mieć dowolne zdefiniowane aplikacje .

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 element 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życia skrótów w aplikacjach do komunikacji

Jeśli tworzysz aplikację do komunikacji, możesz poprawić swoją pozycję w Arkusz udostępniania na Androidzie obejmujący raportowanie wykorzystania wiadomości wychodzących i przychodzących. Aby to zrobić, ponownie opublikuj skrót rozmowy, który reprezentuje kontakt za pomocą 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 jest funkcjonalnie podobne 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.

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 wychodząca wiadomość jest przeznaczona do czatu grupowego, musisz też dodać wartość parametru Audience, ponieważ typ recipient jest powiązany z tą funkcją.

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łaszanie użycia skrótów do wiadomości przychodzących

Aby aktywować raportowanie użytkowania, gdy użytkownik otrzyma wiadomość, taką jak SMS, wiadomości czatu, e-maila lub powiadomień, należy dodatkowo określić możliwość w skrócie przez 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ć Audience jako typ sender. jest powiązana z daną funkcją.

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ż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ć metadane chooser-target-service i zestaw filtrów intencji. Zapoznaj się z aktualnym interfejsem ChooserTargetService Direct Share API.

Ta usługa jest już zadeklarowana w bibliotece zgodności, więc użytkownik to robi nie muszą deklarować usługi w pliku manifestu aplikacji. Należy jednak wziąć pod uwagę link z działania udostępniania do usługi jako dostawcy celu w wybieraczu.

W poniższym przykładzie implementacja ChooserTargetService to androidx.core.content.pm.ChooserTargetServiceCompat, która jest już zdefiniowany W Androidzie X:

<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 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: dostarcza obiekty ChooserTarget za pomocą ChooserTargetService. Wyniki były pobieranych w odpowiedzi na żądanie, co wydłuża czas wczytywania wartości docelowych.

W Androidzie 10 (poziom interfejsu API 29) zastąpiliśmy interfejsy API ChooserTargetService DirectShare interfejsami Share Shortcuts API. Zamiast pobierać wyniki reaktywnie na żądanie, interfejs Share Shortcuts API umożliwia publikowanie bezpośredniego udostępniania cele z wyprzedzeniem. Dzięki temu znacznie przyspieszyliśmy proces pobierania danych dotyczących bezpośredniego udostępniania podczas przygotowywania arkusza udostępniania. Mechanizm ChooserTargetService bezpośredniego udostępniania będzie nadal działać, ale system będzie niższe pozycje w rankingu przypisywać celom udostępnianym w ten sposób niż celom, które korzystają z interfejsu API skrótów udostępniania.

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

Czym opublikowane skróty do celów udostępniania różnią się od programu uruchamiającego skrótów (typowe korzystanie ze skrótów po długim naciśnięciu ikon aplikacji w program uruchamiający)?

Wszystkie skróty opublikowane w celu 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 działanie dotyczy również łącznej liczby skróty publikowane przez aplikację (udostępnianie celów i starszych skrótów programu uruchamiającego; łącznie).

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 jest włączona przytrzymanie może wyświetlić maksymalnie 4 lub 5 skrótów w trybie pionowym; 8 w trybie poziomym. Więcej informacji i wskazówek na temat udostępniania skrótów znajdziesz w najczęstszych pytaniach.