Используйте целевые объекты Direct Share, чтобы упростить и ускорить обмен URL-адресами, изображениями или другими данными между приложениями и вашим приложением. Direct Share работает следующим образом: контакты из мессенджеров и социальных сетей отображаются непосредственно в меню «Поделиться» Android, без необходимости выбора приложения и последующего поиска контакта.
ShortcutManagerCompat — это API AndroidX, предоставляющий возможность совместного использования ярлыков и обратно совместимый с устаревшим API ChooserTargetService . Это предпочтительный способ публикации как ярлыков для совместного использования, так и ChooserTargets . Инструкции см. в разделе «Использование AndroidX для предоставления как ярлыков для совместного использования, так и объектов ChooserTarget» на этой странице.
Публикация, прямые ссылки, целевые показатели
В строке «Прямой доступ к таблице общего доступа» отображаются только динамические ярлыки, предоставляемые API ярлыков общего доступа. Выполните следующие шаги, чтобы опубликовать целевые объекты прямого доступа.
В XML-файле ресурсов вашего приложения объявите элементы
share-target.<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>При инициализации приложения используйте
setDynamicShortcuts, чтобы упорядочить динамические сочетания клавиш по степени важности.Более низкий индекс указывает на большую важность. Если вы разрабатываете приложение для общения, то можете использовать самые популярные беседы, отсортированные по давности появления в приложении. Не публикуйте устаревшие ярлыки; беседа, в которой не было активности пользователей за последние 30 дней, считается устаревшей.
Котлин
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
Если вы разрабатываете приложение для общения, сообщайте об использовании ярлыков через
pushDynamicShortcutкаждый раз, когда пользователь получает или отправляет сообщение контакту. Дополнительную информацию см. в разделе «Сообщение об использовании ярлыков для приложений общения» на этой странице. Например, сообщайте об использовании для сообщений, отправленных пользователем, указав привязки возможностей в ярлыке черезShortcutInfoCompat.Builder#addCapabilityBindingс возможностьюactions.intent.SEND_MESSAGE.Котлин
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Если пользователь удаляет контакт, используйте
removeLongLivedShortcut. Это предпочтительный способ удаления ярлыка независимо от того, кэшируется ли он системными службами. Следующий фрагмент кода демонстрирует пример того, как это сделать.Котлин
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Улучшите рейтинг ваших целевых аудиторий Direct Share.
В меню «Поделиться» в Android отображается фиксированное количество объектов для прямой отправки. Эти предложения отсортированы по порядку. Вы можете улучшить рейтинг своих ярлыков, выполнив следующие действия:
- Убедитесь, что все
shortcutIdsуникальны и никогда не используются повторно для разных целей. - Чтобы ярлык действовал долго, вызовите метод
setLongLived(true). - Для отображения сочетаний клавиш, связанных с общением, сообщите об использовании сочетаний клавиш для исходящих и входящих сообщений, повторно опубликовав соответствующие сочетания клавиш через
ShortcutManagerCompat.pushDynamicShortcut. Подробности см. в разделе «Сообщение об использовании сочетаний клавиш для коммуникационных приложений» на этой странице. - Избегайте указания неактуальных или устаревших целевых контактов для Direct Share — например, контактов, с которыми пользователь не отправлял сообщения в течение последних 30 дней.
- В приложениях для SMS-сообщений следует избегать предоставления ярлыков для коротких кодов или переписок, которые могут быть расценены как спам. Пользователи вряд ли будут делиться такой информацией в подобных переписках.
- Вызовите
setCategories(), чтобы связать ярлык с соответствующими атрибутамиmimeType. Например, для приложения SMS, если контакт не поддерживает RCS или MMS, вы не будете связывать соответствующий ярлык с нетекстовыми MIME-типами, такими какimage/*иvideo/*. - После того, как в рамках конкретного диалога был активирован динамический ярлык и зафиксировано его использование, идентификатор ярлыка не следует изменять. Это гарантирует сохранение данных об использовании для ранжирования.
Если пользователь нажимает на любой объект Direct Share, ваше приложение должно перенаправить его на пользовательский интерфейс, где он сможет выполнить действие непосредственно над темой этого объекта. Не показывайте пользователю интерфейс для уточнения информации и не размещайте его в интерфейсе, не связанном с выбранным объектом. Например, в мессенджере нажатие на объект Direct Share переводит пользователя в диалог с выбранным человеком. Клавиатура отображается, а сообщение предварительно заполняется данными для обмена.
API для обмена ярлыками
Начиная с Android 10 (уровень API 29), ShortcutInfo.Builder были добавлены методы и улучшения, предоставляющие дополнительную информацию о целевом объекте для совместного доступа:
-
setCategories() - Начиная с Android 10, категории также используются для фильтрации ярлыков, которые могут обрабатывать намерения или действия по обмену данными. Подробнее см. в разделе «Объявление цели обмена данными» . Это поле обязательно для ярлыков, предназначенных для использования в качестве целей обмена данными.
-
setLongLived() Указывает, является ли ярлык действительным после того, как он был удален из сети или сделан невидимым приложением (как динамический или закрепленный ярлык). Если ярлык существует длительное время, он может кэшироваться различными системными службами даже после того, как он был удален из сети как динамический ярлык.
Использование долгосрочного решения может улучшить рейтинг. Подробнее см. раздел «Как добиться наилучшего рейтинга» .
-
setShortLabel(),setLongLabel() При публикации ярлыка для конкретного человека, пожалуйста, укажите его полное имя в
setLongLabel()и любые сокращенные имена, такие как прозвище или имя, вsetShortLabel().
Посмотрите пример публикации ярлыков для обмена данными на GitHub .
Предоставьте изображения для быстрого доступа.
Чтобы создать ярлык для общего доступа, вам нужно добавить изображение с помощью setIcon() .
Ярлыки для обмена данными могут отображаться на разных поверхностях системы и изменять свой внешний вид. Кроме того, на некоторых устройствах под управлением Android версий 7, 8 или 9 (уровни API 25, 26, 27 и 28) могут отображаться только растровые значки без фона, что значительно снижает контрастность. Чтобы ваш ярлык выглядел должным образом, предоставьте адаптивное растровое изображение, используя IconCompat.createWithAdaptiveBitmap() .
Убедитесь, что адаптивные растровые изображения соответствуют тем же рекомендациям и размерам, что и адаптивные значки . Наиболее распространенный способ сделать это — масштабировать нужное квадратное растровое изображение до 72x72 пикселей и центрировать его на прозрачном холсте размером 108x108 пикселей. Если ваш значок содержит прозрачные области, необходимо указать цвет фона; в противном случае прозрачные области будут отображаться черным цветом.
Не следует предоставлять изображения, замаскированные под определенную форму. Например, до Android 10 (уровень API 29) было распространено предоставление аватаров пользователей для объектов Direct Share ChooserTarget , замаскированных под круг. В Android 10 панель общего доступа Android Sharesheet и другие системные элементы теперь формируют и меняют тематику изображений ярлыков. Предпочтительный способ предоставления ярлыков общего доступа — использование ShortcutManagerCompat , который автоматически преобразует объекты Direct Share ChooserTarget в круги.
Объявить целевую цену акций
Цели для обмена данными должны быть объявлены в файле ресурсов приложения, аналогично статическим определениям ярлыков . Добавьте определения целей для обмена данными внутрь корневого элемента <shortcuts> в файле ресурсов вместе с другими статическими определениями ярлыков. Каждый элемент <share-targets> содержит информацию о типе данных для обмена данными, соответствующих категориях и целевом классе, который будет обрабатывать намерение обмена данными. XML-код выглядит примерно так:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
Элемент данных в целевом объекте для обмена данными аналогичен спецификации данных в фильтре намерений . Каждый целевой объект для обмена данными может иметь несколько категорий, которые используются только для сопоставления опубликованных ярлыков приложения с определениями его целевого объекта для обмена данными. Категории могут содержать любые произвольные значения, определенные приложением.
Если пользователь выберет в окне «Поделиться» в Android ярлык «Поделиться», соответствующий приведенному выше примеру target-share, приложение получит следующее намерение поделиться:
Action: Intent.ACTION_SEND ComponentName: {com.example.android.sharingshortcuts / com.example.android.sharingshortcuts.SendMessageActivity} Data: Uri to the shared content EXTRA_SHORTCUT_ID: <ID of the selected shortcut>
Если пользователь открывает объект общего доступа из ярлыков запуска, приложение получит Intent, созданный при добавлении ярлыка общего доступа в ShortcutManagerCompat . Поскольку это другой Intent, Intent.EXTRA_SHORTCUT_ID будет недоступен, и вам придется передать ID вручную, если он вам понадобится.
Сообщить об использовании сочетаний клавиш для коммуникационных приложений
Если вы разрабатываете приложение для общения, вы можете улучшить его рейтинг в таблице общего доступа Android, отслеживая использование как исходящих, так и входящих сообщений. Для этого повторно опубликуйте ярлык диалога, представляющий контакт, с помощью ShortcutManagerCompat.pushDynamicShortcut .
Использование ярлыков и привязка функций обратно совместимы с Android 5.0 (API 21).
Сообщить об использовании сочетаний клавиш для исходящих сообщений
Функционально отчет об использовании сообщений, отправленных пользователем, аналогичен нажатию кнопки «Отправить» после создания сообщения.
Для запуска отчетов об использовании укажите привязки возможностей в ярлыке с помощью ShortcutInfoCompat.Builder#addCapabilityBinding , указав возможность actions.intent.SEND_MESSAGE .
Котлин
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Если исходящее сообщение предназначено для группового чата, необходимо также добавить значение параметра Audience , поскольку тип recipient связан с данной функцией.
Котлин
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Сообщайте об использовании сочетаний клавиш для входящих сообщений.
Чтобы запускать отчет об использовании при получении пользователем сообщения, такого как SMS, сообщение в чате, электронное письмо или уведомление, необходимо дополнительно указать привязки возможностей в ярлыке с помощью ShortcutInfoCompat.Builder#addCapabilityBinding с возможностью actions.intent.RECEIVE_MESSAGE .
Котлин
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Если входящее сообщение поступает из группового чата, необходимо также добавить значение параметра Audience , поскольку тип sender связан с данной функцией.
Котлин
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
Используйте AndroidX для предоставления как ярлыков для обмена данными, так и целевых объектов для выбора.
Для корректной работы с библиотекой совместимости AndroidX манифест приложения должен содержать метаданные chooser-target-service и intent-filters. См. текущий API прямого обмена ChooserTargetService .
Этот сервис уже объявлен в библиотеке совместимости, поэтому пользователю не нужно объявлять его в манифесте приложения. Однако связь между действием обмена и сервисом должна учитываться как целевой поставщик выбора.
В следующем примере реализация ChooserTargetService — это androidx.core.content.pm.ChooserTargetServiceCompat , которая уже определена в AndroidX:
<activity android:name=".SendMessageActivity" android:label="@string/app_name" android:theme="@style/SharingShortcutsDialogTheme"> <!-- This activity can respond to Intents of type SEND --> <intent-filter> <action android:name="android.intent.action.SEND" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="text/plain" /> </intent-filter> <!-- Only needed if you import the sharetarget AndroidX library that provides backwards compatibility with the old DirectShare API. The activity that receives the Sharing Shortcut intent needs to be taken into account with this chooser target provider. --> <meta-data android:name="android.service.chooser.chooser_target_service" android:value="androidx.sharetarget.ChooserTargetServiceCompat" /> </activity>
Часто задаваемые вопросы о сочетаниях клавиш для совместного доступа
Как хранятся данные об использовании ярлыков и покидают ли они устройство?
Ярлыки хранятся исключительно на устройстве в системном каталоге данных в зашифрованном разделе диска. Информация в ярлыках, такая как значок, назначение действия, имена пользователей и ресурсов, доступна только системным службам и тому же приложению, которое публикует ярлыки.
Какова история компании Direct Share?
В Android 6.0 (уровень API 23) мы внедрили функцию Direct Share, позволяющую приложениям предоставлять объекты ChooserTarget через ChooserTargetService . Результаты извлекались реактивно по запросу, что приводило к медленной загрузке целевых объектов.
В Android 10 (уровень API 29) мы заменили API прямого обмена ChooserTargetService новым API ярлыков обмена. Вместо реактивного получения результатов по запросу, API ярлыков обмена позволил приложениям заранее публиковать целевые объекты прямого обмена. Это значительно ускорило процесс получения целевых объектов прямого обмена при подготовке ShareSheet. Механизм прямого обмена ChooserTargetService продолжит работать, но система будет ранжировать целевые объекты, предоставленные таким образом, ниже, чем любые целевые объекты, использующие API ярлыков обмена.
В Android 11 (уровень API 30) служба ChooserTargetService была признана устаревшей, и API Sharing Shortcuts является единственным способом предоставления целей для прямого обмена.
Чем отличаются опубликованные сочетания клавиш для обмена данными от сочетаний клавиш в лаунчере (типичное использование сочетаний клавиш при длительном нажатии на значки приложений в лаунчере)?
Любые ярлыки, опубликованные для целей «совместного использования», также являются ярлыками запуска и будут отображаться в меню при длительном нажатии на значок вашего приложения. Ограничение на максимальное количество ярлыков для одного действия также распространяется на общее количество ярлыков, публикуемых приложением (ярлыки для целей совместного использования и устаревшие ярлыки запуска вместе взятые).
Каковы рекомендации относительно количества ярлыков для обмена файлами, которые следует публиковать?
Количество ярлыков для обмена ограничено тем же лимитом, что и динамические ярлыки, доступные через getMaxShortcutCountPerActivity(android.content.Context) . Можно установить любое количество ярлыков в пределах этого лимита, но следует помнить, что ярлыки для обмена могут отображаться при длительном нажатии на панель запуска приложений и в меню «Поделиться». В большинстве панелей запуска приложений при длительном нажатии отображается максимум четыре или пять ярлыков в портретном режиме и восемь в альбомном режиме. Более подробную информацию и рекомендации по использованию ярлыков для обмена см. в этом разделе часто задаваемых вопросов .