Fornecer destinos de compartilhamento direto

Use os alvos de compartilhamento direto para que usuários de outros apps compartilhem URLs, imagens ou outros tipos de dados com seu app de forma mais fácil e rápida. Ele apresenta contatos de apps de mensagens e sociais diretamente no Android Sharesheet, sem que os usuários precisem selecionar o app e pesquisar o contato.

ShortcutManagerCompat é uma API do AndroidX que oferece atalhos de compartilhamento e é compatível com versões anteriores da API ChooserTargetService descontinuada. Essa é a maneira preferencial de publicar atalhos de compartilhamento e ChooserTargets. Para conferir instruções, consulte Usar o AndroidX para fornecer atalhos de compartilhamento eChooserTargets nesta página.

Publicar alvos de compartilhamento direto

A linha de compartilhamento direto do Sharesheet mostra apenas atalhos dinâmicos fornecidos pela APISharing Shortcuts. Conclua as etapas a seguir para publicar destinos de compartilhamento direto.

1. No arquivo de recurso XML do app, declare elementos 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. Quando o app for inicializado, use setDynamicShortcuts para ordenar os atalhos dinâmicos por importância.

   Um índice menor indica mais importância. Se você estiver criando um app de comunicação, elas podem ser as principais conversas ordenadas por tempo para retorno à medida que aparecem no app. Não publique atalhos desatualizados. Uma conversa sem atividade do usuário nos últimos 30 dias é considerada desatualizada.

   Kotlin

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

   Java

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

3. Se você estiver desenvolvendo um app de comunicação, informe o uso do atalho pelo pushDynamicShortcut imediatamente sempre que o usuário receber ou enviar uma mensagem para um contato. Consulte Informar o uso de atalhos para apps de comunicação nesta página para mais informações. Por exemplo, para relatar o uso de mensagens enviadas pelo usuário, especifique vinculações de recursos no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o capability actions.intent.SEND_MESSAGE.

   Kotlin

   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);
   

4. Se o usuário excluir um contato, use removeLongLivedShortcut. Essa é a maneira preferencial de remover o atalho, independentemente de ele estar armazenado em cache pelos serviços do sistema. O snippet de código abaixo mostra um exemplo de como fazer isso.

   Kotlin

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

   Java

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

Melhore a classificação dos seus alvos de compartilhamento direto

O Android Sharesheet mostra um número fixo de alvos de compartilhamento direto. Essas sugestões são classificadas por classificação. Você pode melhorar a classificação dos seus atalhos fazendo o seguinte:

• Garanta que todos os shortcutIds sejam exclusivos e nunca sejam reutilizados para destinos diferentes.
• Verifique se o atalho é de longa duração chamando setLongLived(true).
• Para atalhos relacionados a conversas, informe o uso de atalhos para mensagens enviadas e recebidas, republicando os atalhos correspondentes com ShortcutManagerCompat.pushDynamicShortcut. Consulte Informar o uso de atalhos para apps de comunicação nesta página para mais detalhes.
• Evite fornecer destinos de compartilhamento direto irrelevantes ou desatualizados, por exemplo, contatos com que o usuário não enviou mensagens nos últimos 30 dias.
• Em apps de SMS, evite fornecer atalhos para códigos curtos ou conversas identificadas como possíveis spam. É improvável que os usuários compartilhem com essas conversas.
• Chame setCategories() para associar o atalho aos atributos mimeType adequados. Por exemplo, para um app de SMS, se o contato não estiver ativado para RCS ou MMS, você não associaria o atalho correspondente a tipos MIME sem texto, como image/* e video/*.
• Para uma determinada conversa, depois que um atalho dinâmico for enviado e o uso for informado, não mude o ID do atalho. Isso garante a retenção de dados de uso para classificação.

Se o usuário tocar em qualquer alvo de compartilhamento direto, o app precisará levá-lo para uma interface em que possa realizar uma ação diretamente no objeto do alvo. Não apresente ao usuário uma interface de desambiguação nem a coloque em uma interface não relacionada ao alvo tocado. Por exemplo, em um app de mensagens, tocar em um alvo de compartilhamento direto leva o usuário a uma visualização de conversas com a pessoa selecionada. O teclado fica visível, e a mensagem é preenchida automaticamente com os dados compartilhados.

API Sharing Shortcuts

No Android 10 (nível 29 da API) e versões mais recentes, o ShortcutInfo.Builder adicionou métodos e melhorias que fornecem mais informações sobre o alvo de compartilhamento:

setCategories()

No Android 10 e versões mais recentes, as categorias também são usadas para filtrar atalhos que podem processar intents ou ações de compartilhamento. Consulte Declarar um alvo de compartilhamento para mais detalhes. Esse campo é obrigatório para que os atalhos sejam usados como alvos de compartilhamento.

setLongLived()

Especifica se um atalho é válido ou não quando o app cancelou a publicação dele ou o tornou invisível (como um atalho dinâmico ou fixado). Se um atalho for de longa duração, ele poderá ser armazenado em cache por vários serviços do sistema, mesmo depois de ter sido a publicação como um atalho dinâmico.

Fazer com que um atalho seja de longa duração pode melhorar a classificação dele. Consulte Como conseguir a melhor classificação para mais detalhes.

setShortLabel(), setLongLabel()

Ao publicar um atalho para uma pessoa específica, inclua o nome completo dela em setLongLabel() e qualquer nome curto, como apelido ou nome, em setShortLabel().

Confira um exemplo de publicação de atalhos de compartilhamento no GitHub (link em inglês).

Fornecer imagens de atalhos

Para criar um atalho de compartilhamento, é necessário adicionar uma imagem pelo setIcon().

Os atalhos de compartilhamento podem aparecer nas superfícies do sistema e ser remodelados. Além disso, alguns dispositivos com o Android 7, 8 ou 9 (níveis 25, 26, 27 e 28 da API) podem mostrar ícones exclusivos para bitmap sem plano de fundo, o que diminui drasticamente o contraste. Para garantir que o atalho tenha a aparência pretendida, forneça um bitmap adaptável usando IconCompat.createWithAdaptiveBitmap().

Verifique se os bitmaps adaptáveis seguem as mesmas diretrizes e dimensões definidas para ícones adaptativos. A maneira mais comum de fazer isso é dimensionar o bitmap quadrado pretendido para 72 x 72 dp e centralizá-lo em uma tela transparente de 108 x 108 dp. Se o ícone incluir regiões transparentes, inclua uma cor de plano de fundo. Caso contrário, as regiões transparentes aparecerão pretas.

Não ofereça imagens mascaradas para uma forma específica. Por exemplo, antes do Android 10 (API de nível 29), era comum oferecer avatares de usuário para ChooserTargets de compartilhamento direto mascarados na forma de um círculo. O Android Sharesheet e outras plataformas do sistema no Android 10 agora moldam e definem o tema de imagens de atalho. O método preferido para oferecer atalhos de compartilhamento, por meio de ShortcutManagerCompat, modela automaticamente objetos ChooserTarget de compartilhamento direto de versões anteriores para círculos.

Declarar um alvo de compartilhamento

Os alvos de compartilhamento precisam ser declarados no arquivo de recursos do app, da mesma forma que as definições de atalhos estáticos. Adicione as definições de alvos de compartilhamento dentro do elemento raiz <shortcuts> no arquivo de recursos, junto com outras definições de atalhos estáticos. Cada elemento <share-targets> contém informações sobre o tipo de dados compartilhados, as categorias correspondentes e a classe de destino que vai processar a intent de compartilhamento. O código XML tem esta aparência:

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

O elemento de dados em um alvo de compartilhamento é semelhante à especificação de dados em um filtro de intents. Cada alvo de compartilhamento pode ter várias categorias, que são usadas apenas para corresponder os atalhos publicados de um app às respectivas definições de alvo de compartilhamento. As categorias podem ter valores arbitrários definidos pelo app.

Caso o usuário selecione o atalho de compartilhamento no Android ShareSheet que corresponda ao exemplo de alvo de compartilhamento acima, o app receberá a seguinte intent de compartilhamento.

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>

Se o usuário abrir o alvo de compartilhamento a partir dos atalhos da tela de início, o app receberá a intent criada durante o acréscimo do atalho de compartilhamento a ShortcutManagerCompat. Como é uma intent diferente, Intent.EXTRA_SHORTCUT_ID não vai estar disponível, e você vai precisar transmitir o ID manualmente se precisar dele.

Informar o uso de atalhos para apps de comunicação

Se você estiver desenvolvendo um app de comunicação, poderá melhorar sua classificação no Android Sharesheet, relatando o uso de mensagens enviadas e recebidas. Para fazer isso, publique novamente o atalho da conversa que representa o contato usando ShortcutManagerCompat.pushDynamicShortcut.

O uso de atalhos e as vinculações de recursos são compatíveis com versões anteriores do Android 5.0 (API 21).

Informar o uso de atalhos nas mensagens enviadas

A geração de relatórios de uso de mensagens enviadas pelo usuário é funcionalmente semelhante a clicar no botão "Enviar" depois de criar uma mensagem.

Para acionar relatórios de uso, especifique vinculações de recursos no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o capability 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);

Se a mensagem enviada for para um chat em grupo, também será necessário adicionar o valor do parâmetro Audience, já que o tipo recipient está associado ao recurso.

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);

Informar o uso de atalhos para as mensagens recebidas

Para acionar relatórios de uso quando o usuário recebe uma mensagem como SMS, mensagem de chat, e-mail ou notificações, especifique vinculações de recurso no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o recurso 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);

Se a mensagem recebida for de um chat em grupo, também será necessário adicionar o valor do parâmetro Audience, já que o tipo sender está associado ao recurso.

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);

Usar o AndroidX para oferecer atalhos de compartilhamento eChooserTargets

Para trabalhar com a biblioteca de compatibilidade do AndroidX, o manifesto do app precisa conter o conjunto de metadados de serviço seletor de alvo e de filtros de intent. Confira a API Direct Share atual ChooserTargetService.

Esse serviço já está declarado na biblioteca de compatibilidade. Portanto, o usuário não precisa declarar o serviço no manifesto do app. No entanto, o link da atividade de compartilhamento para o serviço precisa ser considerado como um provedor de escolha de destino.

No exemplo a seguir, a implementação de ChooserTargetService é androidx.core.content.pm.ChooserTargetServiceCompat, que já está definido no 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>

Perguntas frequentes sobre atalhos de compartilhamento

Como os dados de uso de atalhos são armazenados? Eles saem do dispositivo?

Os atalhos são armazenados inteiramente no dispositivo, no diretório de dados do sistema, em uma partição de disco criptografada. Informações em atalhos, como ícone, intent e nomes de pessoas e recursos, podem ser acessadas apenas pelos serviços do sistema e pelo mesmo app que publica os atalhos.

Qual é o histórico do compartilhamento direto?

Lançamos o Direct Share no Android 6.0 (nível 23 da API) para permitir que os apps forneçam objetos ChooserTarget usando um ChooserTargetService. Os resultados eram recuperados de forma reativa sob demanda, levando a um tempo de carregamento lento dos destinos.

No Android 10 (nível 29 da API), substituímos as APIs de compartilhamento direto ChooserTargetService pela nova API Share Shortcuts. Em vez de recuperar os resultados de forma reativa sob demanda, a API Shared Shortcuts permite que os apps publiquem alvos de compartilhamento direto com antecedência. Isso acelerou rapidamente o processo de recuperação de destinos de compartilhamento direto durante a preparação do ShareSheet. O mecanismo de compartilhamento direto ChooserTargetService vai continuar funcionando, mas o sistema vai classificar os alvos fornecidos dessa forma mais abaixo do que qualquer outro alvo que use a API de atalhos de compartilhamento.

O Android 11 (nível 30 da API) suspendeu o uso do serviço ChooserTargetService, e a APISharing Shortcuts é a única maneira de fornecer alvos de compartilhamento direto.

Qual é a diferença entre os atalhos publicados para alvos de compartilhamento e os atalhos na tela de início (o uso típico de atalhos ao tocar em ícones de apps e mantê-los pressionados na tela de início)?

Todos os atalhos publicados com a função de "alvo de compartilhamento" também são atalhos da tela de início e serão exibidos no menu quando o ícone do app for tocado e mantido pressionado. O limite máximo de atalhos por atividade também se aplica ao número total de atalhos que um app publica (alvos de compartilhamento e atalhos da tela de início herdados combinados).

Qual é a orientação sobre o número de atalhos de compartilhamento que se deve publicar?

O número de atalhos de compartilhamento é restrito ao mesmo limite de atalhos dinâmicos disponíveis pela getMaxShortcutCountPerActivity(android.content.Context). É possível publicar qualquer número nesse limite, mas lembre-se de que os atalhos de compartilhamento podem ficar visíveis ao tocar e manter pressionado o Acesso rápido aos apps e na página de compartilhamento. A maioria das telas de início de apps ao tocar e manter pressionado mostra no máximo quatro ou cinco atalhos no modo retrato e oito no modo paisagem. Consulte as Perguntas frequentes para mais detalhes e orientações sobre atalhos de compartilhamento.