Fornire target di condivisione diretta

Utilizza i target della condivisione diretta per consentire agli utenti di altre app di condividere in modo più semplice e veloce URL, immagini o altri tipi di dati con la tua app. La funzionalità Direct Share funziona presentando i contatti di app di messaggistica e social direttamente su Android Sharesheet, senza che gli utenti debbano selezionare l'app e cercare il contatto.

ShortcutManagerCompat è un'API AndroidX che fornisce le scorciatoie di condivisione ed è compatibile con le versioni precedenti dell'API ChooserTargetService deprecata. Questo è il modo migliore per pubblicare sia le scorciatoie di condivisione sia ChooserTargets. Per le istruzioni, vedi Utilizzare AndroidX per fornire sia le scorciatoie di condivisione sia iChooserDestinazioni in questa pagina.

Pubblica target di condivisione diretta

La riga Condivisione diretta di Sharesheet mostra solo le scorciatoie dinamiche fornite dall'API Sharing Shortcuts. Completa i seguenti passaggi per pubblicare i target della condivisione diretta.

1. Nel file di risorse XML dell'app, dichiara gli elementi 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. Durante l'inizializzazione dell'app, utilizza setDynamicShortcuts per ordinare le scorciatoie dinamiche in base all'importanza.

   Un indice più basso indica maggiore importanza. Se stai creando un'app di comunicazione, queste possono essere conversazioni principali ordinate per recency quando vengono visualizzate nella tua app. Non pubblicare scorciatoie obsolete; una conversazione senza attività utente negli ultimi 30 giorni è considerata obsoleta.

   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 stai sviluppando un'app di comunicazione, segnala l'utilizzo della scorciatoia tramite pushDynamicShortcut immediatamente ogni volta che l'utente riceve o invia un messaggio a un contatto. Per ulteriori informazioni, consulta Segnalare l'utilizzo delle scorciatoie per le app di comunicazione in questa pagina. Ad esempio, segnala l'utilizzo dei messaggi inviati dall'utente specificando associazioni di funzionalità nella scorciatoia tramite ShortcutInfoCompat.Builder#addCapabilityBinding con la funzionalità 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 l'utente elimina un contatto, utilizza removeLongLivedShortcut. Questo è il modo migliore per rimuovere la scorciatoia a prescindere dal fatto che sia memorizzata nella cache dai servizi di sistema. Lo snippet di codice riportato di seguito mostra un esempio di come eseguire questa operazione.

   Kotlin

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

   Java

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

Migliorare il ranking dei tuoi target di condivisione diretta

Il foglio di condivisione Android mostra un numero fisso di target della condivisione diretta. Questi suggerimenti sono ordinati per ranking. Puoi potenzialmente migliorare il ranking delle scorciatoie procedendo nel seguente modo:

• Assicurati che tutti i valori shortcutIds siano univoci e non vengano mai riutilizzati per target diversi.
• Assicurati che la scorciatoia sia di lunga durata chiamando setLongLived(true).
• Per le scorciatoie relative alle conversazioni, segnala l'utilizzo delle scorciatoie per i messaggi in uscita e in arrivo ripubblicando le scorciatoie corrispondenti tramite ShortcutManagerCompat.pushDynamicShortcut. Per maggiori dettagli, consulta Segnalare l'utilizzo delle scorciatoie per le app di comunicazione in questa pagina.
• Evita di fornire target di condivisione diretta non pertinenti o inattivi, ad esempio contatti a cui l'utente non ha inviato messaggi negli ultimi 30 giorni.
• Per le app per SMS, evita di fornire scorciatoie per codici brevi o conversazioni identificate come potenziale spam. È molto improbabile che gli utenti condividano con queste conversazioni.
• Richiama setCategories() per associare la scorciatoia agli attributi mimeTypeappropriati. Ad esempio, per un'app per SMS, se il contatto non è abilitato per RCS o MMS, non associare la scorciatoia corrispondente ai tipi MIME non testuali come image/* e video/*.
• Non modificare l'ID della scorciatoia per una determinata conversazione, dopo il push di una scorciatoia dinamica e dopo che ne viene segnalato l'utilizzo. Ciò garantisce la conservazione dei dati sull'utilizzo per il ranking.

Se l'utente tocca un target di condivisione diretta, l'app deve reindirizzarlo a un'interfaccia utente in cui può eseguire un'azione direttamente sull'oggetto target. Non presentare all'utente un'interfaccia utente di disambiguazione e non collocarlo in una UI non correlata al target toccato. Ad esempio, in un'app di messaggistica, quando si tocca un target di condivisione diretta, l'utente viene indirizzato a una visualizzazione per conversazione con la persona selezionata. La tastiera è visibile e il messaggio è precompilato con i dati condivisi.

API Sharing Scorciatoias

A partire da Android 10 (livello API 29), ShortcutInfo.Builder ha aggiunto metodi e miglioramenti che forniscono informazioni aggiuntive sul target di condivisione:

setCategories()

A partire da Android 10, le categorie vengono utilizzate anche per filtrare le scorciatoie che possono gestire intent o azioni di condivisione. Per maggiori dettagli, consulta Dichiarare un target di condivisione. Questo campo è obbligatorio per le scorciatoie da utilizzare come destinazioni delle condivisioni.

setLongLived()

Consente di specificare se una scorciatoia è valida quando non è stata pubblicata o è stata resa invisibile dall'app (come scorciatoia dinamica o bloccata). Se una scorciatoia ha una lunga durata, può essere memorizzata nella cache da vari servizi di sistema anche dopo che è stata annullata la pubblicazione come scorciatoia dinamica.

Rendere una scorciatoia di lunga durata può migliorarne il ranking. Per ulteriori dettagli, consulta la sezione Ottenere il ranking migliore.

setShortLabel(), setLongLabel()

Quando pubblichi una scorciatoia per una singola persona, includi il suo nome completo in setLongLabel() e qualsiasi nome breve, come un nickname o un nome, in setShortLabel().

Guarda un esempio di pubblicazione di scorciatoie di condivisione su GitHub.

Fornisci immagini rapide

Per creare una scorciatoia per la condivisione, devi aggiungere un'immagine tramite setIcon().

Le scorciatoie di condivisione possono essere visualizzate su tutte le piattaforme del sistema e potrebbero essere rimodellate. Inoltre, alcuni dispositivi con Android 7, 8 o 9 (livelli API 25, 26, 27 e 28) potrebbero visualizzare icone solo bitmap senza sfondo, il che riduce drasticamente il contrasto. Per assicurarti che la scorciatoia abbia l'aspetto previsto, fornisci una bitmap adattiva utilizzando IconCompat.createWithAdaptiveBitmap().

Assicurati che le bitmap adattive seguano le stesse linee guida e dimensioni impostate per le icone adattive. Il modo più comune per farlo è scalare la bitmap quadrata prevista a 72 x 72 dp e centrarla all'interno di un canvas trasparente di 108 x 108 dp. Se l'icona include regioni trasparenti, devi includere un colore di sfondo, altrimenti le regioni trasparenti vengono visualizzate in nero.

Non fornire immagini mascherate su una forma specifica. Ad esempio, prima di Android 10 (livello API 29), era comune fornire avatar degli utenti per la condivisione diretta ChooserTarget mascherati in un cerchio. Android Sharesheet e altre piattaforme di sistema in Android 10 ora utilizzano le immagini rapide di forma e tema. Il metodo preferito per fornire le scorciatoie di condivisione, tramite ShortcutManagerCompat, modella automaticamente gli oggetti ChooserTarget di condivisione diretta in backcompat nei cerchi.

Dichiara un target di condivisione

Le destinazioni di condivisione devono essere dichiarate nel file di risorse dell'app, come per le definizioni delle scorciatoie statiche. Aggiungi definizioni di destinazioni di condivisione all'interno dell'elemento principale <shortcuts> nel file di risorse, insieme ad altre definizioni di scorciatoie statiche. Ogni elemento <share-targets> contiene informazioni sul tipo di dati condivisi, sulle categorie corrispondenti e sulla classe target che gestirà l'intent di condivisione. Il codice XML ha un aspetto simile al seguente:

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

L'elemento dei dati in un target di condivisione è simile alla specifica dei dati in un filtro per intent. Ogni destinazione di condivisione può avere più categorie, che vengono utilizzate solo per abbinare le scorciatoie pubblicate di un'app con le relative definizioni della destinazione. Le categorie possono avere qualsiasi valore arbitrale definito dall'app.

Se l'utente seleziona nel foglio di condivisione Android la scorciatoia per la condivisione che corrisponde all'esempio di condivisione target precedente, l'app otterrà il seguente intent di condivisione:

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 l'utente apre la destinazione di condivisione dalle scorciatoie dell'Avvio app, l'app riceverà l'intent creato durante l'aggiunta della scorciatoia di condivisione a ScorciatoiaManagerCompat. Poiché si tratta di un intent diverso, Intent.EXTRA_SHORTCUT_ID non sarà disponibile e dovrai passare l'ID manualmente se necessario.

Segnala l'utilizzo delle scorciatoie per le app di comunicazione

Se stai sviluppando un'app per la comunicazione, puoi migliorare il ranking nel foglio di condivisione di Android segnalando l'utilizzo sia per i messaggi in uscita che per quelli in arrivo. Per farlo, ripubblica la scorciatoia alla conversazione che rappresenta il contatto tramite ShortcutManagerCompat.pushDynamicShortcut.

L'utilizzo delle scorciatoie e le associazioni di funzionalità sono compatibili con le versioni precedenti ad Android 5.0 (API 21).

Segnala l'utilizzo della scorciatoia per i messaggi in uscita

La funzionalità dei report per i messaggi inviati dall'utente è simile al clic sul pulsante "Invia" dopo aver creato un messaggio.

Per attivare i report sull'utilizzo, specifica le associazioni di funzionalità nella scorciatoia tramite ShortcutInfoCompat.Builder#addCapabilityBinding con la funzionalità 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 il messaggio in uscita riguarda una chat di gruppo, devi anche aggiungere il valore del parametro Audience poiché il tipo recipient è associato alla funzionalità.

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

Segnala l'utilizzo della scorciatoia per i messaggi in arrivo

Per attivare i report sull'utilizzo quando l'utente riceve un messaggio, ad esempio un SMS, un messaggio di chat, un'email o notifiche, devi specificare inoltre le associazioni di funzionalità nella scorciatoia tramite ShortcutInfoCompat.Builder#addCapabilityBinding con la funzionalità 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 il messaggio in arrivo proviene da una chat di gruppo, devi anche aggiungere il valore del parametro Audience poiché il tipo sender è associato alla funzionalità.

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

Usa AndroidX per fornire sia scorciatoie per la condivisione sia ChooserTarget

Affinché possa funzionare con la libreria di compatibilità AndroidX, il manifest dell'app deve contenere il set di filtri per i metadati e la libreria per la scelta dei metadati. Consulta l'API ChooserTargetService Direct Share corrente.

Questo servizio è già dichiarato nella libreria di compatibilità, quindi l'utente non deve dichiararlo nel file manifest dell'app. Tuttavia, il collegamento dall'attività di condivisione al servizio deve essere preso in considerazione come fornitore di destinazione del selettore.

Nell'esempio seguente, l'implementazione di ChooserTargetService è androidx.core.content.pm.ChooserTargetServiceCompat, che è già definita in 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>

Domande frequenti sulle scorciatoie per la condivisione

Come vengono archiviati i dati sull'utilizzo delle scorciatoie e vengono rimossi dal dispositivo?

Le scorciatoie vengono archiviate interamente sul dispositivo nella directory dei dati di sistema in una partizione del disco criptata. Le informazioni nelle scorciatoie, come icona, intent e nomi di persone e risorse, sono accessibili solo dai servizi di sistema e dalla stessa app che pubblica le scorciatoie.

Qual è la storia della condivisione diretta?

Abbiamo introdotto la condivisione diretta in Android 6.0 (livello API 23) per consentire alle app di fornire oggetti ChooserTarget tramite un ChooserTargetService. I risultati sono stati recuperati in modo reattivo on demand, con un conseguente rallentamento del tempo di caricamento dei target.

In Android 10 (livello API 29), abbiamo sostituito le API Direct Share di ChooserTargetService con la nuova API Sharing Scorciatoias. Invece di recuperare i risultati reattivamente on demand, l'API Sharing Scorciatoias consente alle app di pubblicare target a condivisione diretta in anticipo. Questo ha accelerato rapidamente il processo di recupero dei target di condivisione diretta durante la preparazione di ShareSheet. Il meccanismo di condivisione diretta ChooserTargetService continuerà a funzionare, ma il sistema classifica i target forniti in questo modo più in basso rispetto a qualsiasi target che utilizzi l'API Sharing Shortcuts.

Android 11 (livello API 30) ha ritirato il servizio ChooserTargetService e l'API Sharing Scorciatoias è l'unico modo per fornire target di condivisione diretta.

Quali sono le differenze tra le scorciatoie pubblicate per i target di condivisione e le scorciatoie in Avvio applicazioni (l'utilizzo tipico delle scorciatoie quando si preme a lungo sulle icone delle app in Avvio app)?

Qualsiasi scorciatoia pubblicata a scopo di "condivisione target" è anch'essa una scorciatoia in Avvio applicazioni e verrà mostrata nel menu quando si preme a lungo l'icona dell'app. Il limite massimo di scorciatoie per attività viene applicato anche al numero totale di scorciatoie pubblicate da un'app (combinazioni di target di condivisione e scorciatoie di Avvio app precedenti).

Quali sono le indicazioni sul numero di scorciatoie di condivisione che è necessario pubblicare?

Il numero delle scorciatoie di condivisione è vincolato allo stesso limite delle scorciatoie dinamiche disponibili tramite getMaxShortcutCountPerActivity(android.content.Context). Puoi pubblicare qualsiasi numero per raggiungere questo limite, ma tieni presente che le scorciatoie di condivisione possono essere visibili in Avvio applicazioni tenendo premuto a lungo e nel foglio di condivisione. La maggior parte delle app Avvio app con pressione lunga mostra un massimo di quattro o cinque scorciatoie in modalità verticale e otto in modalità Orizzontale. Consulta queste Domande frequenti per ulteriori dettagli e indicazioni sulla condivisione delle scorciatoie.