Fornire target di condivisione diretta

Utilizza i target di condivisione diretta per consentire agli utenti di altre app di condividere più facilmente e velocemente URL, immagini o altri tipi di dati con la tua app. La condivisione diretta funziona presentando i contatti delle app di messaggistica e social direttamente nella scheda di condivisione di Android, senza che gli utenti debbano selezionare l'app e cercare il contatto.

ShortcutManagerCompat è un'API AndroidX che fornisce scorciatoie per la condivisione ed è compatibile con le versioni precedenti dell'API ChooserTargetService. Si tratta del metodo preferito per pubblicare sia le scorciatoie di condivisione sia ChooserTargets. Per le istruzioni, consulta Utilizzare AndroidX per fornire sia le scorciatoie di condivisione sia ChooserTargets in questa pagina.

Pubblicare i target di condivisione diretta

La riga Condivisione diretta della scheda di condivisione mostra solo le scorciatoie dinamiche fornite dall'API Sharing Shortcuts. Completa i seguenti passaggi per pubblicare i target di 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. All'inizializzazione dell'app, utilizza setDynamicShortcuts per ordinare le scorciatoie dinamiche in base all'importanza.

   Un indice più basso indica una maggiore importanza. Se stai creando un'app di comunicazione, possono essere le conversazioni principali ordinate in base all'ordine di apparizione nell'app. Non pubblicare scorciatoie non aggiornate: una conversazione senza attività utente negli ultimi 30 giorni è considerata non aggiornata.

   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 delle scorciatoie tramite pushDynamicShortcut immediatamente ogni volta che l'utente riceve o invia un messaggio a un contatto. Per ulteriori informazioni, consulta la sezione Segnalare l'utilizzo delle scorciatoie per le app di comunicazione in questa pagina. Ad esempio, registra l'utilizzo dei messaggi inviati dall'utente specificando le associazioni delle 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, usa removeLongLivedShortcut. Questo è il metodo migliore per rimuovere la scorciatoia, indipendentemente dal fatto che sia memorizzata nella cache dai servizi di sistema. Il seguente snippet di codice 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 target di condivisione diretta

La scheda Condivisione di Android mostra un numero fisso di destinazioni della condivisione diretta. Questi suggerimenti sono ordinati in base al ranking. Puoi potenzialmente migliorare il ranking delle tue scorciatoie procedendo nel seguente modo:

• Assicurati che tutti i valori shortcutIds siano univoci e che 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 entrata ripubblicando le scorciatoie corrispondenti tramite ShortcutManagerCompat.pushDynamicShortcut. Per informazioni dettagliate, consulta Segnalare l'utilizzo delle scorciatoie per le app di comunicazione in questa pagina.
• Evita di fornire target di condivisione diretta irrilevanti o obsoleti, ad esempio i contatti con cui l'utente non ha inviato messaggi negli ultimi 30 giorni.
• Per le app di messaggistica, evita di fornire scorciatoie per codici brevi o conversazioni identificate come potenziali spam. È molto improbabile che gli utenti condividano contenuti con queste conversazioni.
• Chiama setCategories() per associare la scorciatoia agli mimeType attributi appropriati. Ad esempio, per un'app di SMS, se il contatto non è compatibile con RCS o MMS, non associ la scorciatoia corrispondente a tipi MIME non di testo come image/* e video/*.
• Per una determinata conversazione, una volta inviata una scorciatoia dinamica e registrato l'utilizzo, non modificare l'ID scorciatoia. In questo modo, viene garantita la conservazione dei dati sull'utilizzo per il ranking.

Se l'utente tocca un target di condivisione diretta, la tua app deve indirizzarlo a un'interfaccia utente in cui può eseguire un'azione direttamente sull'oggetto del target. Non presentare all'utente un'interfaccia utente di disambiguazione e non inserirlo in un'interfaccia utente non correlata al target toccato. Ad esempio, in un'app di messaggistica, toccare un target di condivisione diretta indirizza l'utente a una visualizzazione della conversazione con la persona selezionata. La tastiera è visibile e il messaggio è precompilato con i dati condivisi.

API Sharing Shortcuts

A partire da Android 10 (livello API 29), ShortcutInfo.Builder ha aggiunto metodi e miglioramenti che forniscono informazioni aggiuntive sulla destinazione della 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 destinate a essere utilizzate come target di condivisione.

setLongLived()

Specifica se una scorciatoia è valida o meno quando è stata ritirata o nascosta dall'app (come scorciatoia dinamica o bloccata). Se una scorciatoia è di lunga durata, può essere memorizzata nella cache da vari servizi di sistema anche dopo essere stata ritirata come scorciatoia dinamica.

Se mantieni una scorciatoia attiva a lungo, il suo ranking può migliorare. Per maggiori dettagli, consulta Ottenere il ranking migliore.

setShortLabel(), setLongLabel()

Quando pubblichi una scorciatoia per una persona, includi il nome completo in setLongLabel() e un nome breve, ad esempio un nickname o un nome, in setShortLabel().

Dai un'occhiata a un esempio di pubblicazione di scorciatoie per la condivisione su GitHub.

Fornire immagini di scorciatoie

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

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

Assicurati che i bitmap adattivi rispettino le stesse linee guida e dimensioni impostate per le icone adative. Il modo più comune per farlo è ridimensionare la bitmap quadrata prevista a 72 x 72 dp e centrarla in una tela trasparente di 108 x 108 dp. Se l'icona include regioni trasparenti, devi includere un colore di sfondo; in caso contrario, le regioni trasparenti verranno visualizzate in nero.

Non fornire immagini mascherate in una forma specifica. Ad esempio, prima di Android 10 (livello API 29), era comune fornire avatar utente per la condivisione direttaChooserTarget mascherati in un cerchio. La scheda Condivisione di Android e altre piattaforme di sistema in Android 10 ora modellano e personalizzano le immagini delle scorciatoie. Il metodo preferito per fornire scorciatoie per la condivisione, tramite ShortcutManagerCompat, modifica automaticamente gli oggetti di condivisione diretta ChooserTarget di compatibilità con le versioni precedenti in cerchi.

Dichiarare una quota target

Le destinazioni di condivisione devono essere dichiarate nel file di risorse dell'app, in modo simile alle definizioni di scorciatoie statiche. Aggiungi le definizioni di destinazione della condivisione all'interno dell'elemento radice <shortcuts> nel file della risorsa, insieme ad altre definizioni di scorciatoie statiche. Ogni elemento <share-targets> contiene informazioni sul tipo di dati condivisi, sulle categorie corrispondenti e sulla classe di destinazione che gestirà l'intenzione di condivisione. Il codice XML ha il seguente aspetto:

<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 dati in una destinazione 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 associare le scorciatoie pubblicate di un'app alle relative definizioni di destinazione di condivisione. Le categorie possono avere qualsiasi valore arbitrario definito dall'app.

Se l'utente seleziona la scorciatoia per la condivisione nella scheda di condivisione di Android che corrisponde all'esempio di condivisione di destinazione riportato sopra, l'app riceverà il seguente intento 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 del programma di avvio, l'app riceve l'intent creato quando è stata aggiunta la scorciatoia di condivisione a ShortcutManagerCompat. Poiché si tratta di un'intenzione diversa, Intent.EXTRA_SHORTCUT_ID non sarà disponibile e, se ne hai bisogno, dovrai passare l'ID manualmente.

Segnalare l'utilizzo delle scorciatoie per le app di comunicazione

Se stai sviluppando un'app di comunicazione, puoi migliorare il tuo ranking nella scheda di condivisione di Android registrando l'utilizzo sia per i messaggi in uscita sia per quelli in entrata. Per farlo, ripubblica la scorciatoia della conversazione che rappresenta il contatto tramite ShortcutManagerCompat.pushDynamicShortcut.

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

Segnalare l'utilizzo delle scorciatoie per i messaggi in uscita

La generazione di report sull'utilizzo dei messaggi inviati dall'utente è funzionalmente simile al fare clic sul pulsante "Invia" dopo aver creato un messaggio.

Per attivare i report sull'utilizzo, specifica le associazioni delle 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 è per una chat di gruppo, devi aggiungere anche 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);

Segnalare l'utilizzo delle scorciatoie 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 anche 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 aggiungere anche 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);

Utilizza AndroidX per fornire sia le scorciatoie di condivisione sia ChooserTargets

Per poter utilizzare la libreria di compatibilità AndroidX, il file manifest dell'app deve contenere i metadati chooser-target-service e intent-filters. Consulta l'attuale API ChooserTargetService Direct Share.

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

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

Come vengono archiviati i dati di utilizzo delle scorciatoie e se vengono trasferiti al di fuori del dispositivo?

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

Qual è la storia di Condivisione diretta?

Abbiamo introdotto la funzionalità Condivisione diretta in Android 6.0 (livello API 23) per consentire alle app di fornire oggetti ChooserTarget tramite un ChooserTargetService. I risultati venivano recuperati in modo reattivo su richiesta, con un tempo di caricamento lento per i target.

In Android 10 (livello API 29), abbiamo sostituito le ChooserTargetService API Direct Share con la nuova API Shortcuts for Sharing. Anziché recuperare i risultati in modo reattivo e su richiesta, l'API Shortcuts per la condivisione consente alle app di pubblicare in anticipo i target di condivisione diretta. In questo modo, è stato possibile velocizzare notevolmente il processo di recupero dei destinatari della condivisione diretta durante la preparazione della scheda Condividi. Il meccanismo di ChooserTargetServicecondivisione diretta continuerà a funzionare, ma il sistema assegna un ranking inferiore ai target forniti in questo modo rispetto a qualsiasi target che utilizza l'API Shortcuts per la condivisione.

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

In che modo le scorciatoie pubblicate per i target di condivisione sono diverse dalle scorciatoie del programma di avvio (l'utilizzo tipico delle scorciatoie quando si preme a lungo sulle icone delle app nel programma di avvio)?

Le scorciatoie pubblicate per lo scopo "target di condivisione" sono anche scorciatoie del programma di avvio e verranno visualizzate nel menu quando viene eseguita una pressione prolungata sull'icona dell'app. Il limite massimo di scorciatoie per attività si applica anche al numero totale di scorciatoie pubblicate da un'app (target di condivisione e scorciatoie del programma di avvio legacy combinati).

Quali sono le indicazioni sul numero di scorciatoie per la condivisione da pubblicare?

Il numero di scorciatoie per la condivisione è limitato allo stesso limite di scorciatoie dinamiche disponibili tramite getMaxShortcutCountPerActivity(android.content.Context). È possibile pubblicare qualsiasi numero fino a questo limite, ma bisogna tenere presente che le scorciatoie per la condivisione possono essere visibili nel menu a discesa dell'app e nel riquadro di condivisione. La maggior parte dei lanciatori di app con pressione prolungata mostra un massimo di quattro o cinque scorciatoie in modalità Ritratto e otto in modalità Orizzontale. Consulta queste Domande frequenti per ulteriori dettagli e indicazioni sulla condivisione delle scorciatoie.