Укажите цели Direct Share

Рисунок 1. Строка Direct Share в Sharesheet, как показано цифрой 1.

Используйте цели Direct Share, чтобы пользователям других приложений было проще и быстрее обмениваться URL-адресами, изображениями или другими видами данных с вашим приложением. Функция Direct Share представляет контакты из приложений для обмена сообщениями и социальных сетей непосредственно в таблице Android Sharesheet, при этом пользователям не нужно выбирать приложение и затем искать контакт.

Примечание. Начиная с Android 11 (уровень API 30), вы можете предоставлять целевые объекты Direct Share только через API ярлыков общего доступа, описанный ниже на этой странице.

ShortcutManagerCompat — это API AndroidX, который предоставляет ярлыки общего доступа и обратно совместим с устаревшим API ChooserTargetService . Это предпочтительный способ публикации как Sharing Shortcuts, так и ChooserTargets . Инструкции см. в разделе «Использование AndroidX для предоставления ярлыков общего доступа» и «Цели выбора» на этой странице.

Публикация целей Direct Share

В строке Sharesheet Direct Share отображаются только динамические ярлыки, предоставляемые API ярлыков общего доступа. Выполните следующие шаги, чтобы опубликовать цели Direct Share.

1. В 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>
   

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

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

   Котлин

   ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
   

   Ява

   List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
   shortcuts.add(shortcut1);
   shortcuts.add(shortcut2);
   ...
   ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
   
   

3. Если вы разрабатываете коммуникационное приложение, сообщайте об использовании ярлыков с помощью 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);
   

4. Если пользователь удаляет контакт, используйте removeLongLivedShortcut . Это предпочтительный способ удаления ярлыка независимо от того, кэширован ли он системными службами. В следующем фрагменте кода показан пример того, как это сделать.

   Котлин

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
   

   Ява

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));
   
   

Улучшите рейтинг ваших целей Direct Share

Таблица общего доступа Android показывает фиксированное количество целей 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, который соответствует приведенному выше примеру целевой общей папки, приложение получит следующее намерение поделиться:

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 для предоставления ярлыков общего доступа и ChooserTargets.

Чтобы иметь возможность работать с библиотекой совместимости AndroidX, манифест приложения должен содержать набор служб выбора метаданных и фильтров намерений. См. текущий API ChooserTargetService Direct Share .

Эта служба уже объявлена ​​в библиотеке совместимости, поэтому пользователю не нужно объявлять службу в манифесте приложения. Однако при выборе целевого поставщика необходимо учитывать ссылку от общего доступа к услуге.

В следующем примере реализацией 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 ярлыков общего доступа. Вместо реактивного получения результатов по запросу API Sharing Shortcuts позволяет приложениям заранее публиковать цели Direct Share. Это быстро ускорило процесс получения целей Direct Share при подготовке ShareSheet. Механизм ChooserTargetService Direct Share продолжит работать, но система ранжирует цели, предоставленные таким образом, ниже, чем любые цели, использующие API ярлыков общего доступа.

В Android 11 (уровень API 30) служба ChooserTargetService устарела, а API Sharing Shortcuts — единственный способ предоставить цели Direct Share.

Чем опубликованные ярлыки для общих целей отличаются от ярлыков средства запуска (типичное использование ярлыков при длительном нажатии на значки приложений в средстве запуска)?

Любые ярлыки, опубликованные с целью «поделиться целью», также являются ярлыками средства запуска и будут отображаться в меню при длительном нажатии на значок вашего приложения. Ограничение максимального количества ярлыков на одно действие также применяется к общему количеству ярлыков, публикуемых приложением (совместно с общими целями и ярлыками устаревших средств запуска).

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

Количество ярлыков для общего доступа ограничено тем же пределом динамических ярлыков, доступных через getMaxShortcutCountPerActivity(android.content.Context) . Можно опубликовать любое количество в пределах этого лимита, но следует иметь в виду, что ярлыки общего доступа могут быть видны при длительном нажатии в панели запуска приложений и на листе общего доступа. Большинство средств запуска приложений при длительном нажатии отображают максимум четыре или пять ярлыков в портретном режиме и восемь в альбомном режиме. Дополнительные сведения и рекомендации по совместному использованию ярлыков см. в этом разделе часто задаваемых вопросов .