Управление ярлыками

После создания ярлыков вам может потребоваться управлять ими на протяжении всего жизненного цикла вашего приложения. Например, вы можете захотеть оптимизировать приложение, определив, как часто пользователи выполняют определенные действия с помощью ваших ярлыков. В другом случае вы можете решить отключить закрепленный ярлык, чтобы предотвратить выполнение устаревших или отсутствующих действий. Для ярлыков, используемых в диалогах, вы можете отслеживать их использование, чтобы получать сигналы, улучшающие рейтинг ярлыков.

На этой странице описаны эти и несколько других распространенных способов управления сочетаниями клавиш.

Сокращенное поведение

В следующих разделах содержится общая информация о поведении сочетаний клавиш, включая видимость, порядок отображения и ранжирование.

видимость ярлыка

Статические и динамические ярлыки появляются в поддерживаемых лаунчерах или помощниках, когда пользователь выполняет определенный жест или голосовую команду. В поддерживаемых лаунчерах жестом является касание и удержание значка приложения, но в других лаунчерах жест может отличаться. В Google Assistant ярлыки могут отображаться внутри помощника или запускаться голосовой командой пользователя.

Класс LauncherApps предоставляет API для доступа к ярлыкам приложений-лаунчеров.

Поскольку закрепленные ярлыки отображаются в самом лаунчере, они всегда видны. Закрепленный ярлык удаляется из лаунчера только в следующих случаях:

• Пользователь удаляет его.
• Приложение, связанное с ярлыком, удалено.
• Чтобы очистить данные приложения, пользователь переходит в «Настройки» > «Приложения и уведомления» , выбирает приложение, а затем нажимает «Хранилище» > «Очистить хранилище» .

Объекты для обмена данными представляют собой подмножество динамических ярлыков, которые отображаются в строке прямого доступа к функции обмена данными в меню «Поделиться» Android.

порядок отображения ярлыков

Когда в лаунчере отображаются ярлыки приложений, они должны располагаться в следующем порядке:

1. Статические ярлыки : ярлыки, метод isDeclaredInManifest() которых возвращает true .
2. Динамические сочетания клавиш : сочетания клавиш, метод ShortcutInfo.isDynamic() которых возвращает true .

В каждом типе ярлыков — статических и динамических — ярлыки сортируются в порядке возрастания ранга согласно ShortcutInfo.getRank . Google Assistant также учитывает ранг ярлыка при определении контекстных ярлыков для отображения пользователям.

Ранги представляют собой неотрицательные последовательные целые числа. Статические сочетания клавиш ранжируются от первого к последнему в порядке их появления в файле shortcuts.xml . Для динамических сочетаний клавиш вы можете обновлять ранги существующих сочетаний клавиш при вызове updateShortcuts(Context, List) , addDynamicShortcuts(Context, List) , pushDynamicShortcut(Context, ShortcutInfoCompat) или setDynamicShortcuts(Context, List) .

Порядок отображения целей для обмена данными зависит от различных факторов, включая историю использования, давность, частоту, подсказку о ранге , использование приложения и приоритет, установленный для диалога, связанного с ярлыком для обмена данными. Цели для обмена данными, созданные с помощью API ярлыков для обмена данными, имеют приоритет над целями для обмена данными, созданными с помощью ChooserTargetService , который был объявлен устаревшим в Android 11. В Android 12 и более поздних версиях цели для обмена данными, созданные устаревшим ChooserTargetService больше не будут отображаться в меню «Поделиться».

Большинство лаунчеров отображают максимум четыре ярлыка. Для любой комбинации статических и динамических ярлыков, заданных в программе, лаунчер отображает максимум два статических и два динамических ярлыка. Например, если вы зададите четыре статических ярлыка и программно создадите три динамических ярлыка, лаунчер отобразит первые два статических ярлыка и два динамических ярлыка с самым высоким рейтингом.

Управление несколькими намерениями и действиями

Если вы хотите, чтобы ваше приложение выполняло несколько операций при активации пользователем ярлыка, вы можете настроить его на запуск последовательных действий. Этого можно добиться, назначив несколько интентов, запуская одно действие из другого или устанавливая флаги интентов, в зависимости от типа ярлыка.

Начните одно действие с другого.

Статические ярлыки не могут иметь пользовательские флаги Intent. Первый Intent статического ярлыка всегда имеет установленные флаги Intent.FLAG_ACTIVITY_NEW_TASK и Intent.FLAG_ACTIVITY_CLEAR_TASK . Это означает, что при запуске приложения все существующие активности уничтожаются при запуске статического ярлыка. Если вам не нужно такое поведение, вы можете использовать активность-трамплин — невидимую активность, которая запускает другую активность, — вызвав метод finish внутри блока launch или onCreate до того, как будет задано содержимое Compose:

1. В AndroidManifest.xml file добавьте атрибут android:taskAffinity="" в активность trampoline.

2. В файле ресурсов ярлыков укажите ссылку на активность «батут» в намерении внутри статического ярлыка.

Для получения дополнительной информации о занятиях на батуте см. раздел «Начало одного занятия после другого» .

Установить флаги намерения

Вы можете публиковать динамические ярлыки с любым набором флагов Intent . Предпочтительно указывать комбинацию Intent.FLAG_ACTIVITY_SINGLE_TOP и Intent.FLAG_ACTIVITY_CLEAR_TOP в Intent ярлыка. Это гарантирует, что если ваш ComponentActivity уже активен, он будет выведен на передний план и повторно использован без уничтожения, что позволит вашей архитектуре с одной активностью корректно обрабатывать событие ярлыка через onNewIntent() .

Чтобы узнать больше о задачах и флагах намерений, см. раздел «Задачи и стек возврата» .

Обновить ярлыки

Значок запуска каждого приложения может содержать максимум такое количество статических и динамических ярлыков, суммарное значение которого равно значению, возвращаемому функцией getMaxShortcutCountPerActivity . Количество закрепленных ярлыков, которые может создать приложение, не ограничено.

Даже если издатель удаляет динамический ярлык из списка динамических ярлыков, он всё равно остаётся видимым и доступным для запуска. Это позволяет приложению иметь больше ярлыков, чем позволяет getMaxShortcutCountPerActivity .

Рассмотрим следующий пример, в котором предполагается, что значение, возвращаемое функцией getMaxShortcutCountPerActivity равно 4 :

1. Приложение для чата публикует четыре динамических ярлыка, представляющих четыре последних разговора: c1, c2, c3 и c4.
2. Пользователь закрепляет все четыре ярлыка.
3. Позже пользователь запускает три дополнительных диалога: c5, c6 и c7. Приложение-издатель повторно публикует свои динамические сочетания клавиш. Новый список динамических сочетаний клавиш выглядит следующим образом: c4, c5, c6 и c7.

Приложение вынуждено удалить ярлыки c1, c2 и c3, поскольку не может отображать более четырех динамических ярлыков. Однако c1, c2 и c3 по-прежнему являются закрепленными ярлыками, к которым пользователь может получить доступ и которые может запускать.

Пользователь может получить доступ к семи ярлыкам, которые ведут к действиям в приложении издателя. Это связано с тем, что общее количество включает максимальное число ярлыков и три закрепленных ярлыка.

1. Приложение может использовать updateShortcuts(Context, List) для обновления любого из семи существующих сочетаний клавиш. Например, вы можете обновить этот набор сочетаний клавиш при изменении значков участников чата.
2. Методы addDynamicShortcuts(Context, List) и setDynamicShortcuts(Context, List) можно использовать для обновления существующих сочетаний клавиш с теми же идентификаторами. Однако их нельзя использовать для обновления нединамических, закрепленных сочетаний клавиш, поскольку эти два метода пытаются преобразовать заданные списки сочетаний клавиш в динамические.

Количество ярлыков, которые можно отобразить в приложениях-помощниках, таких как Google Assistant, не ограничено. Используйте метод pushDynamicShortcut библиотеки ShortcutManagerCompat Jetpack для создания и обновления ярлыков для использования в приложениях-помощниках. Кроме того, добавьте в свое приложение библиотеку интеграции Google Shortcuts , чтобы динамические ссылки могли отображаться в Google Assistant.

Чтобы узнать больше о рекомендациях по созданию ярлыков приложений, включая обновление ярлыков, см. раздел «Рекомендации по созданию ярлыков» .

Обработка изменений локали системы

Приложения должны обновлять динамические и закрепленные ярлыки при получении широковещательного сообщения Intent.ACTION_LOCALE_CHANGED , указывающего на изменение системной локали.

Отслеживание использования ярлыков

Чтобы определить ситуации, в которых появляются статические и динамические ярлыки, средство запуска анализирует историю активации ярлыков. Для статических ярлыков вы можете отслеживать, когда пользователи выполняют определенные действия в вашем приложении, вызвав метод reportShortcutUsed и передав ему идентификатор ярлыка при наступлении одного из следующих событий:

• Пользователь выбирает ярлык с заданным идентификатором.
• Внутри приложения пользователь вручную выполняет действие, соответствующее той же комбинации клавиш.

Ваше приложение отслеживает использование динамических ярлыков, вызывая метод pushDynamicShortcut и передавая ему идентификатор ярлыка при возникновении соответствующего события. Передача информации об использовании динамических ярлыков с помощью этого метода позволяет приложениям-помощникам, таким как Google Assistant, предлагать пользователям подходящие ярлыки. Поскольку метод pushDynamicShortcut сообщает об использовании при каждом вызове, не вызывайте метод reportShortcutUsed для тех же самых ярлыков.

Для быстрого доступа к функциям, связанным с общением, важно отслеживать использование исходящих и входящих сообщений. Подробнее см. рекомендации по работе с людьми и общением.

Отключить сочетания клавиш

Поскольку ваше приложение и его пользователи могут закреплять ярлыки на панели запуска устройства, возможно, что эти закрепленные ярлыки будут направлять пользователей к действиям внутри вашего приложения, которые устарели или больше не существуют. Чтобы справиться с этой ситуацией, вы можете отключить ярлыки, которые вы не хотите, чтобы пользователи выбирали, вызвав disableShortcuts , который удаляет указанные ярлыки из списка статических и динамических ярлыков и отключает закрепленные копии этих ярлыков. Вы также можете использовать перегруженную версию этого метода, которая принимает объект CharSequence в качестве пользовательского сообщения об ошибке. Это сообщение об ошибке затем появляется, когда пользователи пытаются запустить любой отключенный ярлык.

Ограничение скорости

При использовании методов setDynamicShortcuts, addDynamicShortcuts или updateShortcuts вы можете вызывать эти методы только определённое количество раз в фоновом приложении — приложении, в котором нет активных процессов или служб на переднем плане. Ограничение на количество вызовов этих методов называется ограничением скорости (rate limiting ). Эта функция предотвращает чрезмерное потребление ресурсов устройства со стороны ShortcutManagerCompat .

Когда ограничение скорости активно, isRateLimitingActive возвращает true. Однако ограничение скорости сбрасывается при определенных событиях, поэтому даже фоновые приложения могут вызывать методы ShortcutManager до тех пор, пока лимит скорости не будет достигнут снова. К таким событиям относятся следующие:

• На передний план выходит приложение.
• Изменились языковые настройки системы.
• Пользователь выполняет действие «ответить непосредственно в уведомлении».

Если во время разработки или тестирования вы столкнулись с ограничением скорости запросов, вы можете выбрать «Параметры разработчика» > «Сбросить ограничение скорости запросов ShortcutManager» в настройках устройства или ввести следующую команду в adb :

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

Резервное копирование и восстановление

Вы можете разрешить пользователям выполнять резервное копирование и восстановление вашего приложения при смене устройств, добавив атрибут android:allowBackup="true" в файл манифеста вашего приложения. Если вы поддерживаете резервное копирование и восстановление, учитывайте следующие моменты, касающиеся ярлыков приложений:

• Статические ярлыки автоматически перепубликовываются, но только после того, как пользователь переустановит ваше приложение на новом устройстве.
• Динамические ярлыки не резервируются, поэтому добавьте в приложение логику для их повторной публикации, когда пользователь открывает приложение на новом устройстве.
• Закрепленные ярлыки автоматически восстанавливаются в меню приложений устройства, но система не создает резервные копии значков, связанных с закрепленными ярлыками. Поэтому сохраняйте изображения закрепленных ярлыков в приложении, чтобы их можно было быстро восстановить на новом устройстве.

Приведенный ниже фрагмент кода показывает, как лучше всего восстановить динамические ярлыки вашего приложения и как проверить, сохранились ли закрепленные ярлыки вашего приложения:

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.
            }

        }
    }
    // ...
}