Zarządzaj skrótami

Po utworzeniu skrótów może być konieczne zarządzanie nimi przez cały okres istnienia aplikacji. Możesz na przykład zoptymalizować aplikację, określając, jak często użytkownicy wykonują określone działania za pomocą skrótów. W innym przypadku możesz wyłączyć przypięty skrót, aby uniemożliwić aplikacji wykonywanie nieaktualnych lub brakujących działań. W przypadku skrótów, do których odwołują się rozmowy, możesz śledzić ich użycie, aby dostarczać sygnały poprawiające ich pozycję.

Na tej stronie opisujemy te i inne typowe sposoby zarządzania skrótami.

Działanie skrótu

W sekcjach poniżej znajdziesz ogólne informacje o działaniu skrótów, w tym o ich widoczności, kolejności wyświetlania i pozycjach.

Widoczność skrótu

Skróty statyczne i dynamiczne pojawiają się w obsługiwanym programie uruchamiającym lub Asystencie, gdy użytkownik wykona określony gest lub polecenie głosowe. W obsługiwanych programach uruchamiających gest polega na dotknięciu i przytrzymaniu ikony aplikacji, ale w innych programach uruchamiających może być inny. W przypadku Asystenta Google skróty mogą być wyświetlane w Asystencie lub uruchamiane za pomocą polecenia głosowego użytkownika.

Klasa LauncherApps udostępnia interfejsy API, które umożliwiają programom uruchamiającym dostęp do skrótów.

Ponieważ przypięte skróty pojawiają się w samym programie uruchamiającym, są zawsze widoczne. Przypięty skrót jest usuwany z programu uruchamiającego tylko w tych sytuacjach:

  • Użytkownik go usunie.
  • Aplikacja powiązana ze skrótem zostanie odinstalowana.
  • Użytkownik wyczyści dane aplikacji, otwierając Ustawienia > Aplikacje i powiadomienia, wybierając aplikację, a następnie klikając Pamięć > Wyczyść pamięć.

Cele udostępniania to podzbiór skrótów dynamicznych, które pojawiają się w wierszu udostępniania bezpośredniego w arkuszu udostępniania w Androidzie.

arkusz udostępniania w Androidzie,
Rysunek 1. Arkusz udostępniania w Androidzie. Cele udostępniania bezpośredniego pojawiają się w pierwszym wierszu, a następnie aplikacje posortowane według pozycji i listy aplikacji.

Kolejność wyświetlania skrótów

Gdy program uruchamiający wyświetla skróty aplikacji, muszą one pojawiać się w tej kolejności:

  1. Skróty statyczne: skróty, których metoda isDeclaredInManifest() zwraca wartość true.
  2. Skróty dynamiczne: skróty, których ShortcutInfo.isDynamic() metoda zwraca wartość true.

W obrębie każdego typu skrótu – statycznego i dynamicznego – skróty są sortowane w kolejności rosnącej pozycji zgodnie z ShortcutInfo.getRank. Asystent Google bierze też pod uwagę pozycję skrótu, gdy określa skróty kontekstowe, które mają być wyświetlane użytkownikom.

Pozycje to nieujemne, kolejne liczby całkowite. Skróty statyczne są sortowane od pierwszego do ostatniego w kolejności, w jakiej pojawiają się w pliku shortcuts.xml. W przypadku skrótów dynamicznych możesz aktualizować pozycje istniejących skrótów, wywołując updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat), lub setDynamicShortcuts(Context, List).

Kolejność celów udostępniania zależy od różnych czynników, w tym od historii użytkownika, aktualności, częstotliwości, wskazówki dotyczącej pozycji, użycia aplikacji i priorytetu ustawionego w rozmowie powiązanej ze skrótem do udostępnienia. Cele udostępniania utworzone za pomocą interfejsu Sharing Shortcuts API mają wyższy priorytet niż cele udostępniania utworzone przez ChooserTargetService, który został wycofany w Androidzie 11. W Androidzie 12 i nowszych wersjach cele udostępniania wygenerowane przez wycofaną usługę ChooserTargetService nie będą już wyświetlane w arkuszu udostępniania.

Większość programów uruchamiających wyświetla maksymalnie 4 skróty. W przypadku dowolnej kombinacji zdefiniowanych skrótów statycznych i dynamicznych program uruchamiający wyświetla maksymalnie 2 skróty statyczne i 2 dynamiczne. Jeśli na przykład zdefiniujesz 4 skróty statyczne i programowo utworzysz 3 skróty dynamiczne, program uruchamiający wyświetli 2 pierwsze skróty statyczne i 2 skróty dynamiczne o najwyższej pozycji.

Zarządzanie wieloma intencjami i aktywnościami

Jeśli chcesz, aby aplikacja wykonywała wiele operacji, gdy użytkownik aktywuje skrót, możesz skonfigurować ją tak, aby uruchamiała kolejne aktywności. Możesz to zrobić, przypisując wiele intencji, uruchamiając jedną aktywność z innej lub ustawiając flagi intencji, w zależności od typu skrótu.

Uruchamianie jednej aktywności z innej

Skróty statyczne nie mogą mieć niestandardowych flag intencji. Pierwsza intencja skrótu statycznego zawsze ma ustawione flagi Intent.FLAG_ACTIVITY_NEW_TASK i Intent.FLAG_ACTIVITY_CLEAR_TASK. Oznacza to, że gdy aplikacja jest uruchomiona, wszystkie istniejące w niej aktywności są niszczone po uruchomieniu skrótu statycznego. Jeśli nie chcesz, aby tak się działo, możesz użyć aktywności pośredniej – niewidocznej aktywności, która uruchamia inną aktywność – wywołując metodę finish w bloku uruchamiania lub onCreate przed ustawieniem treści Compose:

  1. W pliku AndroidManifest.xml file dodaj przypisanie atrybutu android:taskAffinity="" do aktywności pośredniej.

  2. W pliku zasobów skrótów odwołaj się do aktywności pośredniej w intencji w skrócie statycznym.

Więcej informacji o aktywnościach pośrednich znajdziesz w artykule Uruchamianie jednej aktywności z innej.

Ustawianie flag intencji

Możesz publikować skróty dynamiczne z dowolnym zestawem Intent flag. Najlepiej w intencji skrótu określ kombinację flag Intent.FLAG_ACTIVITY_SINGLE_TOP i Intent.FLAG_ACTIVITY_CLEAR_TOP. Dzięki temu, jeśli Twoja ComponentActivity jest już aktywna, zostanie przeniesiona na pierwszy plan i ponownie użyta bez niszczenia, co pozwoli Twojej architekturze z jedną aktywnością prawidłowo obsługiwać zdarzenie skrótu za pomocą metody onNewIntent().

Więcej informacji o zadaniach i flagach intencji znajdziesz w artykule Zadania i stos wsteczny.

Aktualizowanie skrótów

Ikona programu uruchamiającego każdej aplikacji może zawierać co najwyżej liczbę skrótów statycznych i dynamicznych łącznie równą wartości zwracanej przez getMaxShortcutCountPerActivity. Nie ma limitu liczby przypiętych skrótów, które może utworzyć aplikacja.

Gdy skrót dynamiczny jest przypięty, nawet jeśli wydawca usunie go jako skrót dynamiczny, przypięty skrót jest nadal widoczny i można go uruchomić. Dzięki temu aplikacja może mieć więcej niż getMaxShortcutCountPerActivity skrótów.

Rozważmy ten przykład, w którym zakłada się, że wartość zwracana przez getMaxShortcutCountPerActivity to 4:

  1. Aplikacja do czatowania publikuje 4 skróty dynamiczne, które reprezentują 4 ostatnie rozmowy: c1, c2, c3 i c4.
  2. Użytkownik przypina wszystkie 4 skróty.
  3. Później użytkownik rozpoczyna 3 dodatkowe rozmowy: c5, c6 i c7. Aplikacja wydawcy ponownie publikuje swoje skróty dynamiczne. Nowa lista skrótów dynamicznych to: c4, c5, c6 i c7.

Aplikacja musi usunąć skróty c1, c2 i c3, ponieważ nie może wyświetlać więcej niż 4 skrótów dynamicznych. Jednak skróty c1, c2 i c3 są nadal przypięte i użytkownik może je uruchamiać.

Użytkownik może wtedy uzyskać dostęp do łącznie 7 skrótów, które prowadzą do aktywności w aplikacji wydawcy. Dzieje się tak, ponieważ łączna liczba obejmuje maksymalną liczbę skrótów i 3 przypięte skróty.

  1. Aplikacja może użyć metody updateShortcuts(Context, List), aby zaktualizować dowolny z 7 istniejących skrótów. Możesz na przykład zaktualizować ten zestaw skrótów, gdy zmienią się ikony rozmówców.
  2. Możesz użyć metod addDynamicShortcuts(Context, List) i setDynamicShortcuts(Context, List), aby zaktualizować istniejące skróty o tych samych identyfikatorach. Nie możesz ich jednak używać do aktualizowania nieprzypiętych skrótów, ponieważ te 2 metody próbują przekonwertować podane listy skrótów na skróty dynamiczne.

Nie ma limitu liczby skrótów, które można przesłać do wyświetlenia w aplikacjach asystenta, takich jak Asystent Google. Aby tworzyć i aktualizować skróty do użycia w aplikacjach asystenta, użyj pushDynamicShortcut metody z biblioteki Jetpack ShortcutManagerCompat. Dodaj też do aplikacji bibliotekę integracji skrótów Google, aby linki dynamiczne mogły się wyświetlać w Asystencie Google.

Więcej informacji o wytycznych dotyczących skrótów aplikacji, w tym o aktualizowaniu skrótów, zobacz Sprawdzone metody dotyczące skrótów.

Obsługa zmian ustawień regionalnych systemu

Gdy aplikacje otrzymają transmisję Intent.ACTION_LOCALE_CHANGED wskazującą na zmianę ustawień regionalnych systemu , muszą zaktualizować skróty dynamiczne i przypięte.

Śledzenie użycia skrótów

Aby określić sytuacje, w których pojawiają się skróty statyczne i dynamiczne, program uruchamiający sprawdza historię aktywacji skrótów. W przypadku skrótów statycznych, możesz śledzić, kiedy użytkownicy wykonują określone działania w aplikacji, wywołując metodę reportShortcutUsed i przekazując jej identyfikator skrótu, gdy wystąpi jedno z tych zdarzeń:

  • Użytkownik wybierze skrót o podanym identyfikatorze.
  • W aplikacji użytkownik ręcznie wykona działanie odpowiadające temu samemu skrótowi.

Aplikacja śledzi użycie skrótów dynamicznych, wywołując metodę pushDynamicShortcut i przekazując jej identyfikator skrótu, gdy wystąpi odpowiednie zdarzenie. Przesyłanie informacji o użyciu skrótów dynamicznych za pomocą tej metody umożliwia aplikacjom asystenta, takim jak Asystent Google, sugerowanie użytkownikom odpowiednich skrótów. Ponieważ metoda pushDynamicShortcut zgłasza użycie po wywołaniu, nie wywołuj metody reportShortcutUsed w przypadku tych samych skrótów.

W przypadku skrótów związanych z rozmowami ważne jest śledzenie użycia wiadomości wychodzących i przychodzących. Więcej informacji znajdziesz w artykule Sprawdzone metody dotyczące osób i rozmów.

Wyłączanie skrótów

Ponieważ aplikacja i jej użytkownicy mogą przypinać skróty do programu uruchamiającego urządzenia, możliwe jest, że te przypięte skróty będą kierować użytkowników do działań w aplikacji, które są nieaktualne lub już nie istnieją. Aby zaradzić tej sytuacji, możesz wyłączyć skróty, których użytkownicy nie powinni wybierać, wywołując metodę disableShortcuts. Spowoduje to usunięcie określonych skrótów z listy skrótów statycznych i dynamicznych oraz wyłączenie przypiętych kopii tych skrótów. Możesz też użyć przeciążonej wersji tej metody, która akceptuje CharSequence jako niestandardowy komunikat o błędzie. Ten komunikat o błędzie będzie się wyświetlać, gdy użytkownicy spróbują uruchomić dowolny wyłączony skrót.

Ograniczanie liczby żądań

Gdy używasz metod setDynamicShortcuts, addDynamicShortcuts lub updateShortcuts, możesz je wywoływać tylko określoną liczbę razy w aplikacji działającej w tle – aplikacji, która nie ma aktywności ani usług na pierwszym planie. Limit określonej liczby wywołań tych metod nazywa się ograniczaniem liczby żądań. Ta funkcja zapobiega ShortcutManagerCompat przed nadmiernym wykorzystywaniem zasobów urządzenia.

Gdy ograniczanie liczby żądań jest aktywne, isRateLimitingActive zwraca wartość true. Ograniczanie liczby żądań jest jednak resetowane podczas niektórych zdarzeń, więc nawet aplikacje działające w tle mogą wywoływać metody ShortcutManager, dopóki nie zostanie ponownie osiągnięty limit liczby żądań. Te zdarzenia to:

Jeśli podczas programowania lub testowania napotkasz ograniczanie liczby żądań, możesz w ustawieniach urządzenia wybrać Opcje programisty > Zresetuj ograniczanie liczby żądań w ShortcutManager z ustawień urządzenia lub wpisać to polecenie w adb:

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

Tworzenie i przywracanie kopii zapasowej

Możesz umożliwić użytkownikom tworzenie i przywracanie kopii zapasowych aplikacji podczas zmiany urządzenia, dodając do pliku manifestu aplikacji przypisanie atrybutu android:allowBackup="true". Jeśli obsługujesz tworzenie i przywracanie kopii zapasowych, pamiętaj o tych kwestiach dotyczących skrótów aplikacji:

  • Skróty statyczne są ponownie publikowane automatycznie, ale dopiero po ponownym zainstalowaniu aplikacji przez użytkownika na nowym urządzeniu.
  • Skróty dynamiczne nie są uwzględniane w kopii zapasowej, więc w aplikacji musisz uwzględnić logikę, która będzie je ponownie publikować, gdy użytkownik otworzy aplikację na nowym urządzeniu.
  • Przypięte skróty są automatycznie przywracane do programu uruchamiającego urządzenia, ale system nie tworzy kopii zapasowej ikon powiązanych z przypiętymi skrótami. Dlatego zapisz obrazy przypiętych skrótów w aplikacji, aby można je było szybko przywrócić na nowym urządzeniu.

Ten fragment kodu pokazuje, jak najlepiej przywrócić skróty dynamiczne aplikacji i jak sprawdzić, czy przypięte skróty aplikacji zostały zachowane:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}
Wstecz
Dodaj możliwości do skrótów
Dalej
Wdrażanie sprawdzonych metod korzystania ze skrótów