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łujesz się w konwersacjach, możesz śledzić ich użycie, aby dostarczać sygnały poprawiające ich ranking.

Na tej stronie opisujemy te i inne popularne 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 wyda polecenie głosowe. W przypadku obsługiwanych programów uruchamiających gest polega na naciśnięciu i przytrzymaniu ikony aplikacji w menu z aplikacjami, ale w innych programach uruchamiających może być inny. Dzięki Asystentowi Google skróty mogą być wyświetlane w ramach Asystenta lub uruchamiane za pomocą polecenia głosowego użytkownika.

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

Przypięte skróty są widoczne w launcherze, więc są zawsze dostępne. Przypięty skrót jest usuwany z launchera tylko w tych sytuacjach:

• Użytkownik usuwa go.
• Aplikacja powiązana ze skrótem została odinstalowana.
• Użytkownik czyści dane aplikacji, wybierając kolejno Ustawienia > Aplikacje i powiadomienia, a następnie aplikację i Pamięć wewnętrzna > Wyczyść pamięć.

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

Kolejność wyświetlania skrótów

Gdy program uruchamiający wyświetla skróty aplikacji, muszą one być ułożone w tej kolejności:

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

W ramach 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.

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

Kolejność elementów docelowych udostępniania zależy od różnych czynników, w tym od historii użytkownika, aktualności, częstotliwości, wskazówki dotyczącej rankingu, użycia aplikacji i priorytetu ustawionego w przypadku rozmowy powiązanej ze skrótem do udostępniania. Cele udostępniania utworzone za pomocą interfejsu Sharing Shortcuts API mają wyższy priorytet niż cele udostępniania utworzone za pomocą ChooserTargetService, który został wycofany w Androidzie 11. W Androidzie 12 i nowszych wersjach elementy docelowe udostępniania wygenerowane przez wycofany interfejs API ChooserTargetService nie będą już wyświetlane na 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 utworzysz programowo 3 skróty dynamiczne, program uruchamiający wyświetli 2 pierwsze skróty statyczne i 2 skróty dynamiczne o najwyższych pozycjach.

Zarządzanie wieloma intencjami i aktywnościami

Jeśli chcesz, aby po aktywowaniu skrótu przez użytkownika aplikacja wykonywała kilka operacji, możesz skonfigurować ją tak, aby wywoływała kolejne działania. 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 poziomu innej

Skróty statyczne nie mogą mieć flag niestandardowych intencji. Pierwsza intencja statycznego skrótu 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 działania są niszczone po uruchomieniu statycznego skrótu. Jeśli nie chcesz, aby tak się działo, możesz użyć aktywności trampoliny – niewidocznej aktywności, która uruchamia inną aktywność – wywołując funkcję finish w bloku uruchamiania lub onCreate przed ustawieniem treści Compose:

1. W AndroidManifest.xml file uwzględnij przypisanie atrybutuandroid:taskAffinity="" w aktywności na trampolinie.

2. W pliku zasobów skrótów odwołaj się do aktywności trampoliny w intencji w ramach skrótu statycznego.

Więcej informacji o aktywnościach na trampolinie znajdziesz w artykule Rozpoczynanie jednej aktywności z poziomu innej.

Ustawianie flag intencji

Możesz publikować skróty dynamiczne z dowolnym zestawem flag Intent. Najlepiej podaj kombinację filtrów Intent.FLAG_ACTIVITY_SINGLE_TOP i Intent.FLAG_ACTIVITY_CLEAR_TOP w intencji skrótu. Dzięki temu, jeśli ComponentActivity jest już aktywny, zostanie przeniesiony na pierwszy plan i ponownie użyty bez niszczenia, co pozwoli architekturze z jedną aktywnością płynnie obsługiwać zdarzenie skrótu za pomocą 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ć maksymalnie liczbę skrótów statycznych i dynamicznych łącznie, która jest równa wartości zwracanej przez getMaxShortcutCountPerActivity. Aplikacja może utworzyć nieograniczoną liczbę przypiętych skrótów.

Gdy dynamiczny skrót jest przypięty, nawet jeśli wydawca usunie go jako dynamiczny skrót, 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 założono, że wartość zwracana przez funkcję getMaxShortcutCountPerActivity to 4:

1. Aplikacja do czatowania publikuje 4 dynamiczne skróty reprezentujące 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 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 c1, c2 i c3 to nadal przypięte skróty, do których użytkownik może mieć dostęp i które może uruchamiać.

Użytkownik może wtedy uzyskać dostęp do 7 skrótów prowadzących do aktywności w aplikacji wydawcy. Wynika to z tego, że łączna liczba obejmuje maksymalną liczbę skrótów i 3 przypięte skróty.

1. Aplikacja może używać updateShortcuts(Context, List) do aktualizowania dowolnego z 7 obecnych 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 za pomocą tych samych identyfikatorów. Nie możesz ich jednak używać do aktualizowania nieprzypiętych skrótów, ponieważ obie te 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świetlania w aplikacjach asystenta, takich jak Asystent Google. Użyj metody pushDynamicShortcut biblioteki ShortcutManagerCompat Jetpack, aby tworzyć i aktualizować skróty do użycia w aplikacjach asystenta. Dodaj też do aplikacji bibliotekę integracji skrótów Google, aby dynamiczne linki mogły się wyświetlać w Asystencie Google.

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

Obsługa zmian ustawień regionalnych systemu

Aplikacje muszą aktualizować skróty dynamiczne i przypięte, gdy otrzymają transmisję Intent.ACTION_LOCALE_CHANGED wskazującą zmianę ustawień regionalnych systemu.

Śledzenie użycia skrótów

Aby określić, w jakich sytuacjach pojawiają się skróty statyczne i dynamiczne, program uruchamiający sprawdza historię aktywacji skrótów. W przypadku statycznych skrótów 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 wybiera skrót o podanym identyfikatorze.
• W aplikacji użytkownik ręcznie wykonuje 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. Wysyłanie dynamicznych skrótów za pomocą tej metody umożliwia aplikacjom asystenta, takim jak Asystent Google, sugerowanie użytkownikom odpowiednich skrótów. Metoda pushDynamicShortcut zgłasza użycie po wywołaniu, więc 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 w przypadku wiadomości wychodzących i przychodzących. Szczegółowe informacje znajdziesz w sprawdzonych metodach dotyczących osób i rozmów.

Wyłączanie skrótów

Aplikacja i jej użytkownicy mogą przypinać skróty do programu uruchamiającego na urządzeniu, dlatego te przypięte skróty mogą kierować użytkowników do działań w aplikacji, które są nieaktualne lub już nie istnieją. Aby temu zapobiec, 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 ze statycznej i dynamicznej listy skrótów 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 wywoływać je 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ślający, ile razy można wywołać te metody, nazywa się ograniczaniem liczby wywołań. Ta funkcja zapobiega nadmiernemu wykorzystywaniu zasobów urządzenia przez ShortcutManagerCompat.

Gdy ograniczenie liczby żądań jest aktywne, metoda isRateLimitingActive zwraca wartość true. Ograniczenie liczby wywołań 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. Do tych zdarzeń należą:

• Aplikacja przechodzi na pierwszy plan.
• Zmienia się język systemu.
• Użytkownik wykonuje działanie odpowiedzi w tekście w powiadomieniu.

Jeśli podczas programowania lub testowania napotkasz ograniczenie liczby żądań, możesz wybrać Opcje programisty > Zresetuj ograniczenie liczby żądań Menedżera skrótów w ustawieniach urządzenia lub wpisać w adb to polecenie:

adb shell cmd shortcut reset-throttling [ --user your-user-id ]

tworzenie i przywracanie kopii zapasowej;

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

• Skróty statyczne są publikowane ponownie automatycznie, ale dopiero po ponownym zainstalowaniu aplikacji przez użytkownika na nowym urządzeniu.
• Skróty dynamiczne nie są objęte kopią zapasową, więc w aplikacji musisz umieścić logikę, która umożliwi ponowne opublikowanie skrótów, gdy użytkownik otworzy aplikację na nowym urządzeniu.
• Przypięte skróty są automatycznie przywracane do programu uruchamiającego na urządzeniu, ale system nie tworzy kopii zapasowych 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ć dynamiczne skróty aplikacji i 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.
            }

        }
    }
    // ...
}