Zarządzaj skrótami

Po utworzeniu skrótów może być konieczne zarządzanie nimi przez cały okres korzystania z 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 aplikacja nie wykonywała nieaktualnych lub brakujących działań. W przypadku skrótów, do których odwołuje się rozmowa, możesz śledzić ich użycie, aby uzyskać sygnały poprawiające ranking skrótów.

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

Działanie skrótu

Poniższe sekcje zawierają ogólne informacje o działaniu skrótów, w tym o widoczności, kolejności wyświetlania i pozycji w rankingu.

Widoczność skrótu

Skróty statyczne i dynamiczne pojawiają się w obsługiwanym programie uruchamiającym lub asystencie, gdy użytkownik wykonuje określony gest lub polecenie głosowe. W obsługiwanych programach uruchamiających gest polega na naciśnięciu i przytrzymaniu ikony programu uruchamiającego, ale w pozostałych aplikacjach uruchamiających gest może być inny. W Asystencie Google skróty można wyświetlać w Asystencie lub uruchamiać poleceniem głosowym użytkownika.

Klasa LauncherApps udostępnia interfejsy API dla aplikacji uruchamiających, które dają dostęp do skrótów.

Przypięte skróty są widoczne w programie uruchamiającym, więc zawsze są widoczne. Przypięty skrót jest usuwany z programu uruchamiającego tylko w tych sytuacjach:

• Użytkownik usuwa te treści.
• Aplikacja powiązana ze skrótem zostanie odinstalowana.
• Użytkownik może 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óry pojawia się w wierszu udostępniania bezpośredniego w arkuszu udostępniania Androida.

Kolejność wyświetlania skrótów

Gdy w programie uruchamiającym pojawią się skróty do aplikacji, muszą one być wyświetlane w następującej kolejności:

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

W przypadku każdego typu skrótu (statycznego i dynamicznego) skróty są sortowane w kolejności rosnącej rankingu według parametru ShortcutInfo.getRank. Podczas określania skrótów kontekstowych do wyświetlenia użytkownikom Asystent Google uwzględnia też pozycję skrótów.

Rankingi nie są ujemnymi, sekwencyjnymi liczbami całkowitymi. Skróty statyczne są uporządkowane od pierwszego do ostatniego w kolejności, w jakiej występują w pliku shortcuts.xml. W przypadku skrótów dynamicznych możesz aktualizować ranking istniejących skrótów, wywołując metodę 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, takich jak historia użytkownika, czas od poprzedniej wizyty, częstotliwość, wskazówka dotycząca rankingu, użycie aplikacji i priorytet rozmowy powiązany ze skrótem do udostępniania. Cele udostępniania utworzone za pomocą interfejsu Sharing Skróty API mają wyższy priorytet niż docelowe udostępnianie utworzone przez ChooserTargetService, które zostało wycofane w Androidzie 11. W Androidzie 12 i nowszych wartości docelowe udziału generowane przez wycofanych ChooserTargetService nie będą już widoczne w arkuszu udostępniania.

Większość programów uruchamiających wyświetla maksymalnie cztery skróty. W przypadku każdej zdefiniowanej kombinacji statycznych i dynamicznych skrótów program uruchamiający może wyświetlać maksymalnie dwa statyczne skróty i dwa skróty dynamiczne. Jeśli np. zdefiniujesz 4 skróty statyczne i automatycznie utworzysz trzy skróty dynamiczne, w programie uruchamiającym pojawią się pierwsze 2 skróty statyczne oraz 2 skróty dynamiczne o najwyższej pozycji w rankingu.

Zarządzanie wieloma intencjami i działaniami

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

Przypisz wiele intencji

Tworząc skrót za pomocą ShortcutInfoCompat.Builder, możesz użyć setIntents() zamiast setIntent(). Wywołując funkcję setIntents(), możesz uruchamiać w aplikacji różne działania, gdy użytkownik wybierze skrót. Pozwoli to na uruchamianie wszystkich działań w aplikacji oprócz ostatniej w tylnym stosie. Jeśli użytkownik kliknie przycisk Wstecz, zobaczy inną aktywność w aplikacji, zamiast wracać do programu uruchamiającego na urządzeniu.

Rozpoczynanie jednego działania od drugiej

Skróty statyczne nie mogą mieć niestandardowych flag intencji. Pierwsza intencja statycznego skrótu ma zawsze znaczniki Intent.FLAG_ACTIVITY_NEW_TASK i Intent.FLAG_ACTIVITY_CLEAR_TASK skonfigurowane. Oznacza to, że gdy uruchomiona jest aplikacja, wszystkie dotychczasowe działania w niej są niszczone po uruchomieniu skrótu statycznego. Jeśli nie chcesz takiego zachowania, możesz użyć aktywności na trampolinie, czyli niewidocznej aktywności, która rozpoczyna inną aktywność w Activity.onCreate(Bundle) , która wywołuje funkcję Activity.finish():

1. W pliku AndroidManifest.xml umieść atrybut android:taskAffinity=„”” w aktywności związanej z trampoliną.
2. W pliku zasobów skrótów odwołaj się do aktywności na trampolinie w zamiarze w skrótie statycznym.

Więcej informacji na temat aktywności na trampolinie znajdziesz w artykule Rozpoczynanie jednej aktywności od innej.

Ustaw flagi intencji

Skróty dynamiczne możesz publikować z dowolnym zestawem flag Intent. Najlepiej podaj parametr Intent.FLAG_ACTIVITY_CLEAR_TASK wraz z innymi flagami. W przeciwnym razie, jeśli spróbujesz uruchomić inne zadanie, gdy aplikacja jest uruchomiona, docelowa aktywność może się nie pojawić.

Więcej informacji o zadaniach i flagach intencji znajdziesz w artykule Lista zadań i stos wsteczny (w języku angielskim).

Zaktualizuj skróty

Ikona programu uruchamiającego aplikację może zawierać maksymalnie pewną liczbę statycznych i dynamicznych skrótów, która jest równa wartości zwracanej przez metodę getMaxShortcutCountPerActivity. Nie ma ograniczeń co do 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, nadal będzie on widoczny i będzie można go uruchomić. Dzięki temu aplikacja może mieć więcej skrótów niż getMaxShortcutCountPerActivity().

Przeanalizujmy ten przykład, w którym zakładamy, że wartość zwracana przez funkcję getMaxShortcutCountPerActivity() to 4:

1. Aplikacja do obsługi czatu publikuje 4 dynamiczne skróty, reprezentujące 4 najnowsze 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 opublikuje swoje dynamiczne skróty. Nowa dynamiczna lista skrótów to: c4, c5, c6 i c7.

Aplikacja musi usunąć skróty c1, c2 i c3, ponieważ nie może wyświetlić więcej niż 4 skrótów dynamicznych. Jednak skróty c1, c2 i c3 są nadal przypiętymi skrótami, do których użytkownik ma dostęp i który może je uruchamiać.

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

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

Nie ma ograniczeń co do liczby skrótów, które można przekazać do wyświetlania w aplikacjach z Asystentem, takich jak Asystent Google. Użyj metody pushDynamicShortcut() w bibliotece Jetpack ShortcutManagerCompat, aby tworzyć i aktualizować skróty do użytku w aplikacjach Asystenta. Dodaj też do aplikacji bibliotekę integracji skrótów Google, aby umożliwić wyświetlanie linków dynamicznych w Asystencie Google.

Więcej informacji o wskazówkach dotyczących skrótów do aplikacji, w tym o ich aktualizowaniu, znajdziesz w artykule Sprawdzone metody korzystania ze skrótów.

Obsługa zmian ustawień regionalnych systemu

Aplikacje muszą aktualizować dynamiczne i przypięte skróty po otrzymaniu komunikatu Intent.ACTION_LOCALE_CHANGED wskazującego na zmianę języka systemu.

Ś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 wybiera skrót o podanym identyfikatorze.
• W aplikacji użytkownik ręcznie wykonuje działanie powiązane z tym samym skrótem.

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. Przekazywanie informacji o skrótach dynamicznych za pomocą tej metody pozwala aplikacjom z Asystentem, takim jak Asystent Google, proponować użytkownikom odpowiednie skróty. Metoda pushDynamicShortcut() raportuje użycie po jej wywołaniu, dlatego nie należy wywoływać metody reportShortcutUsed() dla tych samych skrótów.

W przypadku skrótów związanych z rozmowami ważne jest śledzenie wykorzystania wiadomości wychodzących i przychodzących. Szczegółowe informacje znajdziesz w sprawdzonych metodach dotyczących osób i rozmów.

Wyłącz skróty

Twoja aplikacja i jej użytkownicy mogą przypinać skróty do programu uruchamiającego na urządzeniu, więc te przypięte skróty mogą kierować użytkowników do nieaktualnych działań w Twojej aplikacji lub już ich nie istnieją. Aby temu zapobiec, możesz wyłączyć skróty, których użytkownicy nie mają wybierać, wywołując metodę disableShortcuts. Spowoduje to usunięcie określonych skrótów z listy statycznych i dynamicznych 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 pojawia się, gdy użytkownik próbuje uruchomić dowolny wyłączony skrót.

Ograniczenie liczby żądań

Korzystając z metod setDynamicShortcuts(), addDynamicShortcuts() lub updateShortcuts(), możesz mieć możliwość wywołania tych metod tylko określoną liczbę razy w aplikacji w tle, czyli aplikacji bez aktywności ani usług na pierwszym planie. Limit liczby wywołań tych metod jest nazywany ograniczeniem liczby żądań. Ta funkcja zapobiega nadmiernemu zużywaniu zasobów urządzenia przez ShortcutManagerCompat.

Gdy ograniczenie liczby żądań jest aktywne, isRateLimitingActive() zwraca wartość „prawda”. W przypadku niektórych zdarzeń ograniczenie szybkości jest jednak resetowane, więc nawet aplikacje działające w tle mogą wywoływać metody ShortcutManager, dopóki limit nie zostanie ponownie osiągnięty. Do tych zdarzeń należą:

• Aplikacja działa na pierwszym planie.
• Zostanie zmieniony język systemu.
• Użytkownik wykonuje działanie odpowiedzi w tekście na powiadomienie.

Jeśli w trakcie programowania lub testowania zauważysz ograniczenie szybkości, możesz wybrać Opcje programisty > Zresetuj ograniczenie szybkości w usłudze shortManager w ustawieniach urządzenia albo wpisać to polecenie w adb:

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

tworzenie i przywracanie kopii zapasowej;

Możesz zezwolić użytkownikom na wykonywanie operacji tworzenia i przywracania kopii zapasowych w Twojej aplikacji podczas zmiany urządzenia. W tym celu dodaj 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 do aplikacji:

• Skróty statyczne są publikowane automatycznie, ale tylko po ponownym zainstalowaniu aplikacji na nowym urządzeniu przez użytkownika.
• Skróty dynamiczne nie mają kopii zapasowej, więc zadbaj o to, aby Twoja aplikacja była ponownie publikowana, gdy użytkownik otworzy ją na nowym urządzeniu.
• Przypięte skróty są automatycznie przywracane do programu uruchamiającego na urządzeniu, ale system nie tworzy kopii zapasowej ikon powiązanych z przypiętymi skrótami. Zapisz obrazy przypiętych skrótów w aplikacji, aby móc je łatwo przywrócić na nowym urządzeniu.

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

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}