![](https://developer.android.google.cn/static/training/sharing/direct-share-targets.png?authuser=19&hl=pt)
Use alvos de compartilhamento direto para facilitar e agilizar o processo para os usuários de outros apps para compartilhar URLs, imagens ou outros tipos de dados com seu app. O compartilhamento direto funciona apresentando contatos de aplicativos sociais e de mensagens diretamente no Android Sharesheet, sem que os usuários precisem selecionar o app e pesquisar o contato.
ShortcutManagerCompat
é uma API AndroidX que oferece atalhos de compartilhamento, de versões anteriores
compatível com a API ChooserTargetService
descontinuada Esta é a configuração
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 do Sharesheet mostra apenas os atalhos dinâmicos fornecidos pelo API de atalhos de compartilhamento. Conclua as etapas a seguir para publicar o compartilhamento direto de destino.
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ê está fazendo uma comunicação do aplicativo, elas podem ser as principais conversas ordenadas por tempo para retorno, à medida que aparecem seu app. Não publique atalhos que estão desatualizados. uma conversa a 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 de atalhos por
pushDynamicShortcut
imediatamente sempre que o usuário recebe ou envia uma mensagem para um contato. Consulte Informar uso do atalho para de comunicação do Google Cloud nesta página para mais informações. Por exemplo, relatar o uso de mensagens enviadas pelo usuário por especificar vinculações de recursos no atalho usandoShortcutInfoCompat.Builder#addCapabilityBinding
com o capabilityactions.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
Esta é a configuração de remover o atalho, mesmo que ele não esteja armazenado em cache pelo sistema serviços. 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. Esses as sugestões são ordenadas por classificação. É possível melhorar a classificação do seu 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)
- Informar o uso de atalhos para atalhos relacionados a conversas
para mensagens enviadas e recebidas, republicando os atalhos correspondentes
usando o
ShortcutManagerCompat.pushDynamicShortcut
. Consulte Informar o uso de atalhos para apps de comunicação. para mais detalhes. - Evite definir segmentações de compartilhamento direto irrelevantes ou desatualizadas, por exemplo, contatos para os quais o usuário não enviou mensagens nos últimos 30 dias.
- Para apps de SMS, evite fornecer atalhos para códigos curtos ou conversas identificados como possíveis spams. É muito improvável que os usuários compartilhem com essas conversas.
- Chame
setCategories()
para associar o atalho à apropriadomimeType
atributos. Por exemplo: para um app de SMS, se o contato não for compatível com RCS ou MMS, você não associar o atalho correspondente a tipos MIME não textuais, comoimage/*
evideo/*
. - Para uma determinada conversa, quando um atalho dinâmico for enviado e o uso for 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 precisará levá-lo para uma interface em que eles podem realizar uma ação diretamente no assunto do alvo. Não apresentar 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 compartilhamento direto target leva o usuário a uma visualização de conversas com a pessoa selecionada. A o teclado fica visível e a mensagem é preenchida automaticamente 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 informações adicionais sobre o alvo de compartilhamento:
setCategories()
- A partir do Android 10, as categorias também são usadas para filtrar atalhos que pode lidar com intents ou ações de compartilhamento. Consulte Declarar um compartilhamento target para mais detalhes. Este campo é obrigatório para atalhos para uso como metas de compartilhamento.
setLongLived()
Especifica se um atalho é válido ou não quando a publicação dele é cancelada ou tornado invisível pelo aplicativo (como um atalho dinâmico ou fixado). Se um atalho tem longa duração, pode ser armazenado em cache por vários serviços do sistema, mesmo após teve a publicação cancelada como um atalho dinâmico.
Fazer com que um atalho seja de longa duração pode melhorar a classificação dele. Consulte Tenha o melhor classificação para mais detalhes.
setShortLabel()
,setLongLabel()
Ao publicar um atalho para uma pessoa, inclua nome em
setLongLabel()
e qualquer nome curto, como um apelido ou um nome, emsetShortLabel()
.
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 que executam o Android 7, 8 ou 9 (nível 25 da API,
26, 27 e 28) podem mostrar ícones somente de bitmap sem plano de fundo, o que
diminui drasticamente o contraste. Para garantir que o atalho tenha a aparência pretendida:
fornecer 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 centralize-o em uma tela transparente de 108 x 108 dp. Se o ícone inclua regiões transparentes, será preciso incluir uma cor de fundo; caso contrário, e regiões transparentes aparecem em preto.
Não ofereça imagens mascaradas para uma forma específica. Por exemplo, antes de
No Android 10 (nível 29 da API), era comum oferecer avatares de usuários para compartilhamento direto
ChooserTarget
s que foram mascarados na forma de um círculo. O Android Sharesheet e outros
as superfícies do sistema no Android 10 agora moldam e têm imagens de atalhos de tema.
O método preferido para oferecer atalhos de compartilhamento, por meio de
ShortcutManagerCompat
,
moldar automaticamente objetos ChooserTarget
de compartilhamento direto de retrocompatibilidade para
círculos para você.
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. Adicionar cota
definições de destino no elemento raiz <shortcuts>
no arquivo de recurso
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 o
classe de destino que processará a intent de compartilhamento. O código XML parece algo como
assim:
<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 suas definições de alvos de compartilhamento. As categorias podem ter qualquer configuração arbitrária definida pelo app e a distribuição dos valores dos dados.
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ê terá que passar o ID manualmente se precisar dele.
Informar o uso de atalhos para apps de comunicação
Se estiver desenvolvendo um aplicativo de comunicação, é possível melhorar sua classificação na
Android Sharesheet, informando o uso de mensagens enviadas e recebidas.
Para isso, publique novamente o atalho da conversa que representa o contato por meio de
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
Os relatórios de uso de mensagens enviadas pelo usuário são funcionalmente semelhantes a clicando no botão "Enviar" após criar uma mensagem.
Para acionar relatórios de uso, especifique vinculações de recursos no atalho
até 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);
Se a mensagem enviada for para um grupo de chat, adicione também o Audience
.
como o valor do parâmetro recipient
tipo está associado à capacidade.
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 as mensagens recebidas
Para acionar o relatório de uso quando o usuário recebe uma mensagem como um SMS,
mensagem de chat, e-mail ou notificações, será necessário especificar também o recurso
vinculações por meio de atalhos
ShortcutInfoCompat.Builder#addCapabilityBinding
com
o capability 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, também será preciso adicionar o Audience
.
como o tipo sender
está 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 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 filtros de intent. Consulte
a API ChooserTargetService
Direct Share atual.
Esse serviço já está declarado na biblioteca de compatibilidade, então o usuário não precisa declarar o serviço no manifesto do app. No entanto, o link da a atividade de compartilhamento no serviço deve ser considerada como um alvo seletor de nuvem.
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 um em uma partição de disco criptografado. Informações em atalhos, como ícone, intent e nomes de pessoas e recursos sejam acessíveis apenas pelos serviços do sistema, e 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
fornecer objetos ChooserTarget
usando um ChooserTargetService
. Os resultados foram
recuperados de forma reativa sob demanda, o que leva a um tempo de carregamento lento dos alvos.
No Android 10 (nível 29 da API), substituímos a classe direta ChooserTargetService
Compartilhe APIs com a nova API de atalhos de compartilhamento. Em vez de recuperar resultados
de modo reativo sob demanda, a API de atalhos de compartilhamento permite que os apps publiquem
as metas com antecedência. Isso acelerou o processo de recuperação do compartilhamento direto
ao preparar o ShareSheet. O compartilhamento direto de ChooserTargetService
continua funcionando, mas o sistema classifica os alvos fornecidos
dessa forma, mais baixa do que qualquer outro destino que use a API Shared Shortcuts.
O Android 11 (nível 30 da API) descontinuou o serviço ChooserTargetService
.
A API Share Shortcuts é a única maneira de fornecer alvos de compartilhamento direto.
Qual é a diferença entre os atalhos publicados para alvos de compartilhamento e o acesso rápido atalhos (o uso típico de atalhos ao tocar em ícones de apps e mantê-los pressionados) acesso rápido)?
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 está restrito ao mesmo limite de atalhos
atalhos disponíveis por meio de
getMaxShortcutCountPerActivity(android.content.Context)
É possível publicar
número até esse limite, mas lembre-se de que os atalhos de compartilhamento podem ficar
no Acesso rápido aos apps, toque e mantenha pressionado e na página de compartilhamento. A maioria dos inicializadores de apps está ativada
tocar e manter pressionado exibem um máximo de quatro ou cinco atalhos no modo retrato e
oito no modo paisagem. Ver isto
Perguntas frequentes
para mais detalhes e orientações sobre atalhos de compartilhamento.