Используйте цели Direct Share, чтобы пользователям других приложений было проще и быстрее обмениваться URL-адресами, изображениями или другими типами данных с вашим приложением. Direct Share работает, представляя контакты из приложений обмена сообщениями и социальных приложений непосредственно на Android Sharesheet, без необходимости для пользователей выбирать приложение, а затем искать контакт.
ShortcutManagerCompat — это API AndroidX, который предоставляет Sharing Shortcuts и который обратно совместим с устаревшим ChooserTargetService API. Это предпочтительный способ публикации Sharing Shortcuts и ChooserTargets . Инструкции см. в разделе Использование AndroidX для предоставления Sharing Shortcuts и ChooserTargets на этой странице.
Опубликовать прямую ссылку Поделиться целями
Строка 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 s, замаскированные под круг. 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 манифест приложения должен содержать набор meta-data choicer-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>
FAQ по совместному использованию сочетаний клавиш
Как хранятся данные об использовании ярлыков и покидают ли они устройство?
Ярлыки хранятся полностью на устройстве в системном каталоге данных в зашифрованном разделе диска. Информация в ярлыках, такая как значок, намерение, имена людей и ресурсов, доступна только системным службам и тому же приложению, которое публикует ярлыки.
Какова история Direct Share?
Мы представили Direct Share в Android 6.0 (уровень API 23), чтобы позволить приложениям предоставлять объекты ChooserTarget через ChooserTargetService . Результаты извлекались реактивно по требованию, что приводило к медленной загрузке целей.
В Android 10 (уровень API 29) мы заменили ChooserTargetService Direct Share API на новый Sharing Shortcuts API. Вместо того, чтобы получать результаты реактивно по требованию, Sharing Shortcuts API позволяет приложениям публиковать цели Direct Share заранее. Это быстро ускорило процесс получения целей Direct Share при подготовке ShareSheet. Механизм ChooserTargetService Direct Share продолжит работать, но система ранжирует цели, предоставленные таким образом, ниже, чем любые цели, использующие Sharing Shortcuts API.
В Android 11 (уровень API 30) служба ChooserTargetService устарела, и API Sharing Shortcuts является единственным способом предоставления целей Direct Share.
Чем опубликованные ярлыки для объектов общего доступа отличаются от ярлыков панели запуска (типичное использование ярлыков при длительном нажатии на значки приложений в панели запуска)?
Любые ярлыки, опубликованные для цели "share target", также являются ярлыками запуска и будут отображаться в меню при длительном нажатии на значок вашего приложения. Максимальный лимит количества ярлыков на активность также применяется к общему количеству ярлыков, которые публикует приложение (цели общего доступа и устаревшие ярлыки запуска вместе взятые).
Каковы рекомендации по количеству ссылок на обмен, которые следует публиковать?
Количество ярлыков для обмена ограничено тем же лимитом динамических ярлыков, которые доступны через getMaxShortcutCountPerActivity(android.content.Context) . Можно опубликовать любое количество в пределах этого лимита, но следует помнить, что ярлыки для обмена могут быть видны в панели запуска приложений при длительном нажатии и на листе общего доступа. Большинство панелей запуска приложений при длительном нажатии отображают максимум четыре или пять ярлыков в портретном режиме и восемь в ландшафтном режиме. Более подробную информацию и руководство по обмену ярлыками см. в этом разделе часто задаваемых вопросов .