Use destinos de compartilhamento direto para facilitar e agilizar o compartilhamento de URLs, imagens e outros tipos de dados com seu app. O compartilhamento direto apresenta contatos de apps de mensagens e redes sociais diretamente no Android Sharesheet, sem que os usuários precisem selecionar o app e procurar 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 instruções,
consulte Usar o AndroidX para fornecer atalhos de compartilhamento eChooserTargets
nesta página.
Publicar alvos de compartilhamento direto
A linha "Compartilhamento direto" do Sharesheet mostra apenas os atalhos dinâmicos fornecidos pela API Share Shortcuts. Siga as etapas abaixo para publicar alvos de compartilhamento direto.
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>
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 poderão ser as principais conversas, ordenadas por tempo para retorno 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);
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, informe o uso de mensagens enviadas pelo usuário especificando vinculações de recursos no atalho usandoShortcutInfoCompat.Builder#addCapabilityBinding
com o recursoactions.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 o usuário excluir um contato, use
removeLongLivedShortcut
. Essa é a maneira preferencial de remover o atalho, independente de ele estar armazenado em cache ou não 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));
Melhorar 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:
- Verifique se todas as
shortcutIds
são exclusivas e nunca reutilizadas para destinos diferentes. - Verifique se o atalho tem uma 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
pelo
ShortcutManagerCompat.pushDynamicShortcut
. Consulte a seção Informar o uso de atalhos para apps de comunicação nesta página para saber mais. - Evite fornecer destinos de compartilhamento direto irrelevantes ou desatualizados. Por exemplo, contatos 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 spams. É muito improvável que os usuários compartilhem essas conversas.
- Chame
setCategories()
para associar o atalho aosmimeType
atributos apropriados. Por exemplo, para um app de SMS, se o contato não estiver ativado para RCS ou MMS, você não associará o atalho correspondente a tipos MIME sem texto, comoimage/*
evideo/*
. - 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, seu app precisará levá-lo a uma interface onde ele possa realizar uma ação diretamente sobre o assunto do alvo. Não apresente ao usuário uma interface de desambiguação e não 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 conversa com a pessoa selecionada. O teclado fica visível, e a mensagem é preenchida com os dados compartilhados.
API Sharing Shortcuts
No Android 10 (nível 29 da API) e versões mais recentes,
ShortcutInfo.Builder
adicionou métodos e melhorias
que oferecem 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 destino de compartilhamento para mais detalhes. Esse campo é obrigatório para atalhos que devem ser usados como alvos de compartilhamento.
setLongLived()
Especifica se um atalho é válido ou não quando o app tem a publicação cancelada ou o torna 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 cancelado 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 o nome curto, como apelido ou primeiro nome, emsetShortLabel()
.
Veja um exemplo de publicação de atalhos de compartilhamento no GitHub (em inglês).
Fornecer imagens de atalhos
Para criar um atalho de compartilhamento, você precisa adicionar uma imagem pelo setIcon()
.
Os atalhos de compartilhamento podem aparecer em todas as superfícies do sistema e ser remodelados.
Além disso, alguns dispositivos com as versões 7, 8 ou 9 do Android (níveis 25,
26, 27 e 28 da API) podem mostrar ícones apenas em bitmap sem um plano de fundo, o que
diminui drasticamente o contraste. Para garantir que seu 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 72x72 dp e centralizá-lo em uma tela transparente de 108x108 dp. Se o ícone incluir regiões transparentes, será necessário incluir uma cor de plano de fundo. Caso contrário, as regiões transparentes aparecerão 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 ChooserTarget
s de compartilhamento direto
mascarados em um círculo. O Android Sharesheet e outras
plataformas de sistema no Android 10 agora definem a forma e o tema de imagens de atalho.
O método preferido para fornecer atalhos de compartilhamento, por meio de
ShortcutManagerCompat
,
molda automaticamente objetos ChooserTarget
de compartilhamento direto de versões anteriores em
círculos para você.
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 definições de alvos
de compartilhamento dentro do elemento raiz <shortcuts>
no arquivo de recursos,
junto a 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 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 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 estará disponível,
e você terá que 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 informando o uso de mensagens enviadas e recebidas.
Para fazer isso, publique novamente o atalho da conversa que representa o contato usando
ShortcutManagerCompat.pushDynamicShortcut
.
As vinculações de recursos e uso de atalhos são compatíveis com versões anteriores do Android 5.0 (API 21).
Informar o uso de atalhos de mensagens enviadas
A funcionalidade de relatórios de mensagens enviadas pelo usuário é semelhante a clicar no botão "enviar" depois de criar uma mensagem.
Para acionar os relatórios de uso, especifique as 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, também será preciso adicionar 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);
Relatar uso de atalhos para mensagens recebidas
Para acionar os relatórios de uso quando o usuário recebe uma mensagem, como um SMS, uma mensagem de chat, um e-mail ou notificações, também é necessário especificar 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, você também vai precisar adicionar o valor do parâmetro Audience
,
porque o tipo sender
está associado ao recurso.
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 PickrTargets
Para trabalhar com a biblioteca de compatibilidade do AndroidX, o manifesto do app
precisa conter o conjunto de metadados de serviço seletor de destino e de filtros de intent. Confira a API ChooserTargetService
Direct Share atual.
Esse serviço já está declarado na biblioteca de compatibilidade, então 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 de destino do seletor.
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 dos atalhos são armazenados e 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. As informações em atalhos, como o ícone, a intent e os 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 Compartilhamento direto no Android 6.0 (nível 23 da API) para permitir que os apps
forneçam objetos ChooserTarget
usando um ChooserTargetService
. Os resultados foram
recuperados de forma reativa sob demanda, levando a um 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
reativamente sob demanda, a API Share 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 classifica os alvos fornecidos
dessa forma com menor do que qualquer alvo que use a API Share Shortcuts.
O Android 11 (nível 30 da API) descontinuou o serviço ChooserTargetService
, e
a API Share Shortcuts é a única maneira de fornecer destinos de compartilhamento direto.
Qual é a diferença entre os atalhos publicados para alvos de compartilhamento e os atalhos da tela de início, que é o uso normal de atalhos ao tocar e manter pressionado os ícones de apps 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 uma pessoa deve publicar?
O número de atalhos de compartilhamento é restrito ao mesmo limite de atalhos
dinâmicos disponíveis via
getMaxShortcutCountPerActivity(android.content.Context)
. É possível publicar qualquer
número dentro desse limite, mas é preciso lembrar 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
ao tocar e manter pressionado exibe no máximo quatro ou cinco atalhos no modo retrato e
oito no modo paisagem. Consulte as
Perguntas frequentes
para saber mais detalhes e orientações sobre o compartilhamento de atalhos.