Fornecer destinos de compartilhamento direto

Figura 1 : linha do Compartilhamento direto no Sharesheet, conforme mostrado em 1

Use destinos do Compartilhamento Direto para facilitar e agilizar o compartilhamento de URLs, imagens ou outros tipos de dados com seu app por usuários de outros apps. O Compartilhamento Direto funciona apresentando contatos de apps de mensagens e redes sociais diretamente na tela de compartilhamento do Android, sem que os usuários precisem selecionar o app e procurar o contato.

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

Publicar alvos de compartilhamento direto

A linha de compartilhamento direto da Sharesheet só mostra atalhos dinâmicos fornecidos pela API Sharing Shortcuts. Siga estas etapas para publicar destinos do 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, as conversas principais poderão ser ordenadas por data de atualização, conforme 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 de atalhos por 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, informe o uso de mensagens enviadas pelo usuário especificando vinculações de recursos no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o recurso 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, independente de ele estar em cache pelos serviços do sistema. O snippet de código a seguir mostra um exemplo de como fazer isso.

    Kotlin

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

    Java

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

Melhorar a classificação dos seus destinos de compartilhamento direto

O Android Sharesheet mostra um número fixo de alvos de compartilhamento direto. Essas sugestões são ordenadas por classificação. É possível melhorar a classificação dos seus atalhos fazendo o seguinte:

  • Verifique se todos os shortcutIds são únicos e nunca são reutilizados por alvos 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 usando ShortcutManagerCompat.pushDynamicShortcut. Consulte Denunciar o uso de atalhos em apps de comunicação nesta página para mais detalhes.
  • Evite fornecer destinos de Compartilhamento Direto irrelevantes ou desatualizados, por exemplo, contatos com quem o usuário não trocou mensagens nos últimos 30 dias.
  • Para apps de SMS, evite fornecer atalhos para códigos curtos ou conversas identificadas como possível spam. É muito improvável que os usuários compartilhem essas conversas.
  • Chame setCategories() para associar o atalho aos mimeType atributos adequados. Por exemplo, em um app de SMS, se o contato não estiver ativado para RCS ou MMS, não associe o atalho correspondente a tipos MIME não textuais, como image/* e video/*.
  • Para uma determinada conversa, depois que um atalho dinâmico é enviado e o uso é informado, não mude o ID do atalho. Isso garante a retenção dos dados de uso para classificação.

Se o usuário tocar em qualquer alvo de compartilhamento direto, o app vai levá-lo a uma interface em que ele pode realizar uma ação diretamente no assunto do alvo. Não mostre ao usuário uma interface de desambiguação nem o 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 conversa com a pessoa selecionada. O teclado fica visível, e a mensagem é preenchida previamente com os dados compartilhados.

API Sharing Shortcuts

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

setCategories()
A partir do Android 10, 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 atalhos que serão usados como destinos 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 é de longa duração, ele pode ser armazenado em cache por vários serviços do sistema, mesmo depois de ter tido a publicação cancelada como atalho dinâmico.

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

setShortLabel(), setLongLabel()

Ao publicar um atalho para uma única pessoa, inclua o nome completo dela em setLongLabel() e qualquer abreviação do nome, como apelido ou primeiro nome, em setShortLabel().

Confira um exemplo de publicação de atalhos de compartilhamento no GitHub.

Oferecer imagens de atalhos

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

Os atalhos de compartilhamento podem aparecer em todas as superfícies do sistema e ser remodelados. Além disso, alguns dispositivos com Android 7, 8 ou 9 (níveis de API 25, 26, 27 e 28) podem mostrar ícones somente bitmap sem um plano de fundo, o que diminui muito 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 estabelecidas para ícones adaptáveis. A forma mais comum de conseguir 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, adicione uma cor de plano de fundo. Caso contrário, essas regiões vão aparecer em preto.

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. Agora, o Android Sharesheet e outras superfícies de sistema no Android 10 definem a forma e o tema de imagens de atalho. O método preferido para fornecer atalhos de compartilhamento, por meio de ShortcutManagerCompat, moldará automaticamente objetos ChooserTarget de compartilhamento direto de versões anteriores em círculos.

Declarar um alvo de compartilhamento

Os alvos de compartilhamento precisam ser declarados no arquivo de recurso 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 é semelhante a este:

<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 aos atalhos publicados de um app com as 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. Por ser um intent diferente, Intent.EXTRA_SHORTCUT_ID não estará disponível, e você terá que passar o ID manualmente se precisar dele.

Gerar relatórios sobre o uso de atalhos para apps de comunicação

Se você estiver desenvolvendo um app de comunicação, poderá melhorar sua classificação na folha de compartilhamento do Android informando o uso de mensagens enviadas e recebidas. Para isso, republicar o atalho de 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 ao Android 5.0 (API 21).

Relatar o uso de atalhos para mensagens enviadas

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

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

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

Kotlin

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

Informar o uso de atalhos para mensagens recebidas

Para acionar relatórios de uso quando o usuário receber uma mensagem, como um SMS, mensagem de chat, e-mail ou notificações, especifique também vinculações de recursos no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o recurso actions.intent.RECEIVE_MESSAGE.

Kotlin

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

Se a mensagem recebida for de um chat em grupo, adicione também o valor do parâmetro Audience como o tipo sender associado à capacidade.

Kotlin

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

Usar o AndroidX para oferecer atalhos de compartilhamento e ChooserTargets

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. Consulte a API Direct Share atual ChooserTargetService.

Esse serviço já está declarado na biblioteca de compatibilidade, portanto, o usuário não precisa declará-lo no manifesto do app. No entanto, o link da atividade de compartilhamento para o serviço precisa ser considerado como um provedor do seletor de alvo.

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 e se eles saem do dispositivo?

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

Qual é a história do Compartilhamento Direto?

Introduzimos o Compartilhamento direto no Android 6.0 (API de nível 23) para permitir que os apps forneçam objetos ChooserTarget por meio de um ChooserTargetService. Os resultados foram recuperados de forma reativa sob demanda, levando a um carregamento lento de alvos.

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

O Android 11 (API de nível 30) descontinuou o serviço ChooserTargetService, e a API Sharing 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 da tela de início (uso normal 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 devem ser publicados?

O número de atalhos de compartilhamento é limitado ao mesmo número de atalhos dinâmicos disponíveis em getMaxShortcutCountPerActivity(android.content.Context). É possível publicar qualquer número até esse limite, mas é importante lembrar que os atalhos de compartilhamento podem ficar visíveis ao tocar e manter pressionado o ícone do app na tela de início e na página de compartilhamento. A maioria dos iniciadores de apps com toque longo mostra um máximo de quatro ou cinco atalhos no modo retrato e oito no modo paisagem. Consulte estas perguntas frequentes para mais detalhes e orientações sobre como compartilhar atalhos.