Используйте целевые объекты Direct Share, чтобы пользователи других приложений могли проще и быстрее делиться URL-адресами, изображениями и другими данными с вашим приложением. Direct Share представляет контакты из приложений обмена сообщениями и социальных сетей непосредственно в Android Sharesheet, избавляя пользователей от необходимости выбирать приложение и искать контакт.
ShortcutManagerCompat — это API AndroidX, предоставляющий функции быстрого доступа и обратно совместимый с устаревшим API ChooserTargetService . Это предпочтительный способ публикации как Shortcuts, так и ChooserTargets . Инструкции см. в разделе «Использование AndroidX для предоставления как Shortcuts, так и ChooserTargets» на этой странице.
Публикация целей Direct Share
В строке Sharesheet Direct Share отображаются только динамические ярлыки, предоставляемые API Sharing Shortcuts. Чтобы опубликовать цели Direct Share, выполните следующие действия.
В 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, ..))
Ява
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)
Ява
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))
Ява
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Повышайте рейтинги ваших целевых платформ Direct Share
В Android Sharesheet отображается фиксированное количество целей Direct Share. Эти предложения отсортированы по рангу. Вы можете улучшить рейтинг своих ярлыков, выполнив следующие действия:
- Убедитесь, что все
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().
Посмотрите пример публикации Sharing Shortcuts на GitHub .
Предоставить изображения для быстрого доступа
Чтобы создать ярлык для общего доступа, вам необходимо добавить изображение с помощью setIcon() .
Ярлыки общего доступа могут отображаться на разных системных поверхностях и могут менять форму. Кроме того, на некоторых устройствах под управлением Android версий 7, 8 или 9 (уровни API 25, 26, 27 и 28) могут отображаться только растровые значки без фона, что значительно снижает контрастность. Чтобы ярлык выглядел так, как задумано, создайте адаптивное растровое изображение с помощью IconCompat.createWithAdaptiveBitmap() .
Убедитесь, что адаптивные растровые изображения соответствуют тем же правилам и размерам, что и адаптивные значки . Наиболее распространённый способ добиться этого — масштабировать квадратное растровое изображение до размера 72x72 dp и разместить его по центру прозрачного холста размером 108x108 dp. Если ваш значок содержит прозрачные области, необходимо задать цвет фона; в противном случае прозрачные области будут отображаться чёрным цветом.
Не предоставляйте изображения, замаскированные под определённую форму. Например, до Android 10 (уровень API 29) было принято предоставлять аватары пользователей для объектов Direct Share ChooserTarget , замаскированные под круг. Android Sharesheet и другие системные элементы в Android 10 теперь формируют и задают темы для изображений ярлыков. Предпочтительный метод предоставления ярлыков общего доступа через 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 Sharesheet ярлык «Поделиться», соответствующий примеру 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>
Если пользователь открывает цель общего доступа из ярлыков панели запуска, приложение получит намерение, созданное при добавлении ярлыка общего доступа в ShortcutManagerCompat . Поскольку это другое намерение, Intent.EXTRA_SHORTCUT_ID будет недоступен, и при необходимости вам придётся передать идентификатор вручную.
Сообщить об использовании быстрых клавиш для приложений связи
Если вы разрабатываете приложение для общения, вы можете улучшить свой рейтинг в Android Sharesheet, сообщая об использовании как исходящих, так и входящих сообщений. Для этого повторно опубликуйте ярлык чата, представляющий контакт, с помощью 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)
Ява
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)
Ява
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)
Ява
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)
Ява
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 для предоставления как Sharing Shortcuts, так и ChooserTargets
Для работы с библиотекой совместимости AndroidX манифест приложения должен содержать набор метаданных chooser-target-service и intent-filters. См. текущую версию ChooserTargetService Direct Share API.
Эта служба уже объявлена в библиотеке совместимости, поэтому пользователю не нужно объявлять её в манифесте приложения. Однако ссылка из активности общего доступа на службу должна учитываться при выборе поставщика цели.
В следующем примере реализация 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?
Мы внедрили функцию Direct Share в Android 6.0 (API уровня 23), чтобы приложения могли предоставлять объекты ChooserTarget через ChooserTargetService . Результаты извлекались реактивно по запросу, что приводило к медленной загрузке целевых объектов.
В Android 10 (уровень API 29) мы заменили API ChooserTargetService Direct Share на новый API Sharing Shortcuts. Вместо получения результатов по запросу, API Sharing Shortcuts позволяет приложениям заранее публиковать цели Direct Share. Это значительно ускорило процесс получения целей Direct Share при подготовке ShareSheet. Механизм ChooserTargetService Direct Share продолжит работать, но система будет ранжировать цели, предоставленные таким образом, ниже любых целей, использующих API Sharing Shortcuts.
В Android 11 (уровень API 30) служба ChooserTargetService прекращена, и API Sharing Shortcuts является единственным способом предоставления целей Direct Share.
Чем опубликованные ярлыки для объектов общего доступа отличаются от ярлыков панели запуска (типичное использование ярлыков при длительном нажатии на значки приложений в панели запуска)?
Любые ярлыки, опубликованные с целью «поделиться», также являются ярлыками панели запуска и отображаются в меню при длительном нажатии на значок вашего приложения. Максимальное количество ярлыков для одного действия также распространяется на общее количество ярлыков, публикуемых приложением (как для целей общего доступа, так и для устаревших ярлыков панели запуска).
Каковы рекомендации по количеству ссылок для совместного использования, которые следует публиковать?
Количество ярлыков для общего доступа ограничено тем же лимитом, что и динамические ярлыки, доступные через getMaxShortcutCountPerActivity(android.content.Context) . Можно опубликовать любое количество в пределах этого лимита, но следует учитывать, что ярлыки для общего доступа могут отображаться в панели запуска приложений при долгом нажатии и на панели общего доступа. Большинство панелей запуска приложений при долгом нажатии отображают максимум четыре или пять ярлыков в портретном режиме и восемь в ландшафтном. Подробнее и рекомендации по использованию ярлыков для общего доступа см. в этом разделе часто задаваемых вопросов .