Fornecer destinos de compartilhamento direto

Figura 1 : linha de compartilhamento direto no Sharesheet, como mostrado por 1

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

ShortcutManagerCompat é uma API AndroidX que oferece atalhos de compartilhamento e é compatí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 do Sharesheet mostra apenas os atalhos dinâmicos fornecidos pelo API de atalhos de compartilhamento. Siga estas etapas para publicar os 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 maior 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.

    KotlinJava
    ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
     
    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 por pushDynamicShortcut imediatamente sempre que o usuário receber ou enviar uma mensagem para um contato. Consulte Relatar 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.

    KotlinJava
    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. Se o usuário excluir um contato, use removeLongLivedShortcut Essa é a melhor maneira de remover o atalho, mesmo que ele esteja armazenado em cache pelos serviços do sistema. O snippet de código a seguir mostra um exemplo de como fazer isso.

    KotlinJava
    val deleteShortcutId = "..."
ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
     
    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 Relatar o uso de atalhos para apps de comunicação nesta página 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 à apropriado mimeType atributos. 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 de texto, como image/* e video/*.
  • 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 de dados de uso para classificação.

Se o usuário tocar em qualquer alvo de compartilhamento direto, o app precisa levá-lo a uma interface em que ele possa 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 de texto, o toque em um alvo de compartilhamento direto leva o usuário a uma visualização de conversas com a pessoa selecionada. O teclado está 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 aprimoramentos que oferecem 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. Este campo é obrigatório para atalhos para uso como metas 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 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, em setShortLabel().

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

Oferecer 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, forneça um bitmap adaptável usando IconCompat.createWithAdaptiveBitmap().

Os bitmaps adaptáveis precisam seguir as mesmas diretrizes e dimensões estabelecidas para ícones adaptáveis. 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, é preciso incluir uma cor de fundo; caso contrário, regiões transparentes aparecem em preto.

Não ofereça imagens mascaradas para uma forma específica. Por exemplo, antes do Android 10 (nível 29 da API), 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 do sistema no Android 10 definem a forma e o tema de imagens de atalho. 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. 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 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 fazer a correspondência com os atalhos publicados de um app com suas definições de alvos de compartilhamento. As categorias podem ter qualquer valor arbitrário definido 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 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, é possível melhorar sua classificação na página de compartilhamento do Android informando o uso de mensagens de entrada e saída. Para isso, publique novamente o atalho de conversa que representa o contato pelo ShortcutManagerCompat.pushDynamicShortcut.

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

Informar o uso de atalhos para 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.

KotlinJava
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 uma conversa em grupo, também será necessário adicionar o valor do parâmetro Audience, já que o tipo recipient está associado ao recurso.

KotlinJava
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 o relatório de uso quando o usuário receber uma mensagem, como SMS, mensagem de chat, e-mail ou notificações, também é necessário especificar as vinculações de recurso no atalho usando ShortcutInfoCompat.Builder#addCapabilityBinding com o recurso actions.intent.RECEIVE_MESSAGE.

KotlinJava
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 uma conversa em grupo, também será necessário adicionar o valor do parâmetro Audience, já que o tipo sender está associado ao recurso.

KotlinJava
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 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 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 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 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 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 criptografada. 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 é a história do Compartilhamento direto?

O Compartilhamento direto foi introduzido no Android 6.0 (nível 23 da API) para permitir que os apps ofereç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 a classe ChooserTargetService direta 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 mecanismo de compartilhamento direto ChooserTargetService continuará funcionando, mas o sistema classifica os alvos fornecidos dessa forma com prioridade mais baixa do que qualquer outro alvo que use a API Sharing 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 uma pessoa deve publicar?

O número de atalhos de compartilhamento é limitado ao mesmo limite de atalhos dinâmicos disponíveis pelo getMaxShortcutCountPerActivity(android.content.Context). É possível publicar qualquer número nesse limite, mas é importante lembrar que os atalhos de compartilhamento podem ficar visíveis no toque longo do iniciador de apps e na página de compartilhamento. A maioria dos inicializadores de apps está ativada tocar e manter pressionado exibem 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 o compartilhamento de atalhos.