Zarządzaj skrótami

Po utworzeniu skrótów może być konieczne zarządzanie nimi przez cały okres użytkowania 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, które poprawiają pozycję skrótu w rankingu.

Na tej stronie opisano te i kilka innych typowych sposobów zarządzania skrótami.

Działanie skrótu

Poniższe sekcje zawierają ogólne informacje o zachowaniu skrótów, w tym o widoczności, kolejności wyświetlania i rangach.

Widoczność skrótu

Ważne: wszystkie informacje o skrótach są przechowywane w zaszyfrowanym magazynie danych logowania, więc aplikacja nie ma dostępu do skrótów użytkownika, dopóki nie odblokuje on urządzenia.

Skróty statyczne i dynamiczne pojawiają się w obsługiwanym launcherze lub asystencie, gdy użytkownik wykona określony gest lub wyda polecenie głosowe. W obsługiwanych programach uruchamiających gestem jest naciśnięcie i przytrzymanie ikony programu uruchamiającego aplikację, ale w innych programach uruchamiających gest może być inny. W Asystencie 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ą aplikacjom z menu z aplikacjami dostęp do skrótów.

Przypięte skróty pojawiają się w samym menu z aplikacjami, więc są zawsze widoczne. Przypięty skrót jest usuwany z programu uruchamiającego tylko w tych sytuacjach:

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

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

Rysunek 1. Arkusz udostępniania w Androidzie. Odbiorcy udostępniania bezpośredniego pojawiają się w pierwszym wierszu, a następnie wyświetlane są aplikacje z rankingu 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 true.
2. Skróty dynamiczne: skróty, których metoda ShortcutInfo.isDynamic() zwraca true.

W ramach każdego typu skrótu (statycznego i dynamicznego) skróty są sortowane według rosnącej rangi zgodnie z ShortcutInfo.getRank. Asystent Google bierze też pod uwagę pozycję skrótu, gdy określa, które skróty kontekstowe wyświetlić użytkownikom.

Pozycje są nieujemnymi, kolejnymi liczbami całkowitymi. 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 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, takich jak historia użytkownika, czas od poprzedniej wizyty, częstotliwość, wskazówka dotycząca pozycji, korzystanie z aplikacji i priorytet ustawiony w rozmowie powiązanej ze skrótem 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 docelowe miejsca udostępniania wygenerowane przez wycofaną metodę 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 skróty 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 najwyżej oceniane skróty dynamiczne.

Uwaga: pozycje są dostosowywane automatycznie, dzięki czemu są unikalne dla każdego typu skrótu – statycznego lub dynamicznego. Jeśli na przykład istnieją 3 skróty dynamiczne o rangach 0, 1 i 2, dodanie kolejnego skrótu dynamicznego o randze 1 oznacza prośbę o umieszczenie tego skrótu na drugiej pozycji. W odpowiedzi pozycje skrótów, które wcześniej miały pozycje 1 i 2, zmienią się odpowiednio na 2 i 3.

Zarządzanie wieloma zamiarami 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 działania. Możesz to zrobić, przypisując wiele intencji, uruchamiając jedną aktywność z poziomu 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ć 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 jej dotychczasowe aktywności są niszczone po uruchomieniu skrótu statycznego. 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 metodę finish w bloku uruchamiania lub onCreate przed ustawieniem treści Compose:

1. W pliku AndroidManifest.xml file uwzględnij przypisanie atrybutu android:taskAffinity="" w aktywności trampoliny.

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

Więcej informacji o aktywnościach typu trampolina znajdziesz w artykule Uruchamianie jednej aktywności z poziomu innej.

Ustawianie flag intencji

Skróty dynamiczne możesz publikować z dowolnym zestawem flag Intent. Najlepiej podaj kombinację Intent.FLAG_ACTIVITY_SINGLE_TOP i Intent.FLAG_ACTIVITY_CLEAR_TOP w intencji skrótu. Dzięki temu, jeśli ComponentActivity jest już aktywna, zostanie przeniesiona na pierwszy plan i użyta ponownie bez niszczenia, co pozwoli architekturze z jedną aktywnością na płynną obsługę zdarzenia 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 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 skrótów niż getMaxShortcutCountPerActivity.

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

1. Aplikacja do obsługi czatu 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óty dynamiczne. Jednak c1, c2 i c3 są nadal przypiętymi skrótami, do których użytkownik ma dostęp i które może uruchomić.

Użytkownik może wtedy uzyskać dostęp do łącznie 7 skrótów, które prowadzą 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 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ż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 limitu liczby skrótów, które można przesłać do wyświetlenia w aplikacjach asystujących, takich jak Asystent Google. Aby tworzyć i aktualizować skróty do użycia w aplikacjach asystujących, użyj metody pushDynamicShortcut 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 do aplikacji, w tym o aktualizowaniu skrótów, znajdziesz w artykule Sprawdzone metody dotyczące skrótów.

Obsługa zmian języka systemu

Aplikacje muszą aktualizować skróty dynamiczne i przypięte, gdy otrzymają komunikat Intent.ACTION_LOCALE_CHANGED wskazujący na zmianę języka 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 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 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. Przekazywanie informacji o użyciu skrótu dynamicznego za pomocą tej metody umożliwia aplikacjom asystującym, takim jak Asystent Google, sugerowanie użytkownikom odpowiednich skrótów. Metoda pushDynamicShortcut raportuje użycie po wywołaniu, dlatego 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 wiadomości przychodzących. Szczegółowe informacje znajdziesz w sprawdzonych metodach dotyczących osób i rozmów.

Uwaga: biblioteka integracji skrótów Google jest wymagana, aby linki dynamiczne przekazywane przez aplikację mogły wyświetlać się na platformach Google, takich jak Asystent Google. Dodając tę bibliotekę do aplikacji, umożliwiasz Asystentowi pobieranie linków dynamicznych i sugerowanie ich użytkownikom w aplikacji Asystent.

Wyłącz skróty

Aplikacja i jej użytkownicy mogą przypinać skróty do programu uruchamiającego na urządzeniu, więc 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 zarządzać tą sytuacją, możesz wyłączyć skróty, których użytkownicy nie powinni wybierać, wywołując metodę disableShortcuts, która usuwa określone skróty z listy skrótów statycznych i dynamicznych oraz wyłącza przypięte kopie 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 pojawi się, gdy użytkownicy spróbują uruchomić wyłączony skrót.

Uwaga: jeśli podczas aktualizowania aplikacji usuniesz niektóre z jej skrótów statycznych, system automatycznie je wyłączy.

Ograniczanie liczby żądań

W przypadku metod setDynamicShortcuts, addDynamicShortcuts i updateShortcuts możesz mieć możliwość wywołania ich tylko określoną liczbę razy w aplikacji działającej w tle, czyli aplikacji bez aktywności lub usług na pierwszym planie. Ograniczenie liczby wywołań tych metod to ograniczanie liczby żądań. Ta funkcja zapobiega nadmiernemu wykorzystywaniu zasobów urządzenia przez ShortcutManagerCompat.

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

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

Jeśli podczas tworzenia lub testowania aplikacji napotkasz ograniczenie liczby żądań, możesz wybrać Opcje programisty > Resetuj ograniczenie liczby żądań ShortcutManager 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;

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

• Skróty statyczne są ponownie publikowane automatycznie, ale dopiero po ponownym zainstalowaniu aplikacji przez użytkownika na nowym urządzeniu.
• Kopie zapasowe skrótów dynamicznych nie są tworzone, więc uwzględnij w aplikacji logikę, która pozwoli ponownie je opublikować, gdy użytkownik otworzy aplikację na nowym urządzeniu.
• Przypięte skróty są automatycznie przywracane w menu z aplikacjami na urządzeniu, ale system nie tworzy kopii zapasowych ikon powiązanych z przypiętymi skrótami. Dlatego zapisuj obrazy przypiętych skrótów w aplikacji, aby można było je szybko przywrócić na nowym urządzeniu.

Poniższy 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.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt