Fornire target di condivisione diretta

Utilizza le destinazioni di condivisione diretta per consentire agli utenti di altre app di condividere URL, immagini o altri tipi di dati con la tua app in modo più semplice e veloce. La condivisione diretta funziona presentando i contatti delle app di messaggistica e social direttamente nel foglio di condivisione di Android, senza che gli utenti debbano selezionare l'app e poi cercare il contatto.

ShortcutManagerCompat è un'API AndroidX che fornisce scorciatoie di condivisione ed è retrocompatibile con l'API ChooserTargetService obsoleta. Questo è il modo preferito per pubblicare sia le scorciatoie per la condivisione che ChooserTargets. Per istruzioni, vedi Utilizzare AndroidX per fornire sia scorciatoie di condivisione cheChooserTargets in questa pagina.

Pubblicare i target di condivisione diretta

La riga Condivisione diretta del foglio di condivisione mostra solo le scorciatoie dinamiche fornite dall'API Sharing Shortcuts. Completa i seguenti passaggi per pubblicare le destinazioni di Direct Share.

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. Quando l'app viene inizializzata, utilizza setDynamicShortcuts per ordinare le scorciatoie dinamiche in base all'importanza.

   Un indice più basso indica una maggiore importanza. Se crei un'app di comunicazione, possono essere le conversazioni principali ordinate in base alla data più recente, così come appaiono nella tua app. Non pubblicare scorciatoie obsolete; una conversazione senza attività dell'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 delle scorciatoie tramite pushDynamicShortcut immediatamente ogni volta che l'utente riceve o invia un messaggio a un contatto. Per saperne di più, consulta Utilizzo delle scorciatoie per le app di comunicazione in questa pagina. Ad esempio, segnala l'utilizzo per i messaggi inviati dall'utente specificando i binding 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, utilizza removeLongLivedShortcut. Questo è il modo preferito 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

Android Sharesheet mostra un numero fisso di destinazioni di 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 gli 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 entrata ripubblicando le scorciatoie corrispondenti tramite ShortcutManagerCompat.pushDynamicShortcut. Per informazioni dettagliate, consulta Utilizzo delle scorciatoie dei report per le app di comunicazione in questa pagina.
• Evita di fornire target di condivisione diretta irrilevanti o obsoleti, ad esempio contatti con cui l'utente non ha scambiato messaggi negli ultimi 30 giorni.
• Per le app di messaggistica, evita di fornire scorciatoie per codici brevi o conversazioni identificate come potenziale spam. È molto improbabile che gli utenti condividano contenuti in queste conversazioni.
• Chiama il numero setCategories() per associare la scorciatoia agli mimeType attributi appropriati. Ad esempio, per un'app di messaggistica, se il contatto non è abilitato per RCS o MMS, non assoceresti la scorciatoia corrispondente a tipi MIME non di testo come image/* e video/*.
• Per una determinata conversazione, una volta eseguito il push di una scorciatoia dinamica e segnalato l'utilizzo, non modificare l'ID scorciatoia. Ciò garantisce la conservazione dei dati di utilizzo per il ranking.

Se l'utente tocca una qualsiasi destinazione di Condivisione diretta, la tua app deve indirizzarlo a un'interfaccia utente in cui può eseguire un'azione direttamente sull'oggetto della destinazione. Non mostrare all'utente una UI di disambiguazione e non inserirlo in una UI non correlata alla destinazione toccata. Ad esempio, in un'app di messaggistica, toccando una destinazione di Condivisione diretta, l'utente viene indirizzato 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 ulteriori informazioni sulla destinazione 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, vedi Dichiarare un intent di condivisione. Questo campo è obbligatorio per le scorciatoie destinate a essere utilizzate come target di condivisione.

setLongLived()

Specifica se una scorciatoia è valida quando è stata annullata la pubblicazione o resa invisibile 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 la sua annullamento della pubblicazione come scorciatoia dinamica.

Se un comando rapido è di lunga durata, il suo ranking può migliorare. Per maggiori dettagli, consulta Ottieni il miglior ranking.

setShortLabel(), setLongLabel()

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

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

Fornisci immagini delle scorciatoie

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

Le scorciatoie di condivisione possono essere visualizzate su tutte le piattaforme del sistema e potrebbero essere ridimensionate. 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 rispettino le stesse linee guida e dimensioni impostate per le icone adattive. Il modo più comune per farlo è scalare la bitmap quadrata prevista a 72x72 dp e centrarla all'interno di un canvas trasparente di 108x108 dp. Se l'icona include regioni trasparenti, devi includere un colore di sfondo; in caso contrario, le regioni trasparenti vengono 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 le scorciatoie di condivisione diretta ChooserTargetmascherate in un cerchio. La scheda Condividi di Android e altre interfacce di sistema in Android 10 ora modellano e tematizzano le immagini delle scorciatoie. Il metodo preferito per fornire scorciatoie di condivisione, tramite ShortcutManagerCompat, modella automaticamente gli oggetti di condivisione diretta ChooserTarget per la compatibilità con le versioni precedenti in cerchie.

Dichiarare un intent di condivisione

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 intent di condivisione all'interno dell'elemento radice <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 di corrispondenza e sulla classe di destinazione 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 di dati in una destinazione di condivisione è simile alla specifica dei dati in un filtro per intent. Ogni target di condivisione può avere più categorie, che vengono utilizzate solo per abbinare le scorciatoie pubblicate di un'app alle definizioni del target di condivisione. Le categorie possono avere valori definiti dall'app arbitrari.

Se l'utente seleziona la scorciatoia di condivisione nel foglio di condivisione di Android che corrisponde alla condivisione di destinazione di esempio riportata sopra, l'app riceverà 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 quando è stata aggiunta la scorciatoia di condivisione a ShortcutManagerCompat. Poiché si tratta di un intent diverso, Intent.EXTRA_SHORTCUT_ID non sarà disponibile e dovrai passare l'ID manualmente, se necessario.

Report sull'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 segnalando l'utilizzo per i messaggi in uscita e in entrata. Per farlo, ripubblica la scorciatoia della conversazione che rappresenta il contatto tramite ShortcutManagerCompat.pushDynamicShortcut.

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

Report sull'utilizzo delle scorciatoie per i messaggi in uscita

Il report sull'utilizzo per i messaggi inviati dall'utente è funzionalmente simile a fare clic sul pulsante "Invia" dopo aver creato un messaggio.

Per attivare la generazione di report sull'utilizzo, specifica i binding 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 come 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);

Report sull'utilizzo delle scorciatoie per i messaggi in arrivo

Per attivare la generazione di report sull'utilizzo quando l'utente riceve un messaggio come un SMS, un messaggio di chat, un'email o delle notifiche, devi specificare anche i binding delle 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 scorciatoie di condivisione sia ChooserTarget

Per poter utilizzare la libreria di compatibilità AndroidX, il manifest dell'app deve contenere il servizio di destinazione del selettore di metadati e i filtri per intent impostati. Consulta l'API Direct Share ChooserTargetService attuale.

Questo servizio è già dichiarato nella libreria di compatibilità, pertanto l'utente non deve dichiararlo nel 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à 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 di condivisione

Come vengono memorizzati i dati di utilizzo delle scorciatoie e vengono lasciati sul 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 cronologia di Direct Share?

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 su richiesta, il che ha comportato un tempo di caricamento lento per i target.

In Android 10 (livello API 29), abbiamo sostituito le API Direct Share con la nuova API Sharing Shortcuts.ChooserTargetService Anziché recuperare i risultati in modo reattivo su richiesta, l'API Sharing Shortcuts consente alle app di pubblicare in anticipo le destinazioni di Direct Share. In questo modo, il processo di recupero delle destinazioni di Direct Share durante la preparazione del foglio di condivisione è stato notevolmente velocizzato. Il meccanismo di ChooserTargetServiceCondivisione diretta continuerà a funzionare, ma il sistema classifica i target forniti in questo modo in una posizione inferiore rispetto a qualsiasi target che utilizza l'API Sharing Shortcuts.

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

In che modo le scorciatoie pubblicate per le destinazioni di condivisione differiscono dalle scorciatoie di avvio (l'utilizzo tipico delle scorciatoie quando si preme a lungo sulle icone delle app nell'avvio)?

Qualsiasi scorciatoia pubblicata per uno scopo di "destinazione di condivisione" è anche una scorciatoia di avvio e verrà visualizzata nel menu quando tieni premuta l'icona dell'app. Il limite massimo del conteggio delle scorciatoie per attività si applica anche al numero totale di scorciatoie pubblicate da un'app (combinazione di target di condivisione e scorciatoie del launcher legacy).

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

Il numero di scorciatoie di condivisione è limitato allo stesso limite delle scorciatoie dinamiche disponibili tramite getMaxShortcutCountPerActivity(android.content.Context). È possibile pubblicare qualsiasi numero fino a quel limite, ma è necessario tenere presente che le scorciatoie di condivisione possono essere visibili nella pressione prolungata di Avvio app e nel foglio di condivisione. La maggior parte dei launcher di app mostra un massimo di quattro o cinque scorciatoie in modalità verticale e otto in modalità orizzontale. Consulta queste domande frequenti per maggiori dettagli e indicazioni sulla condivisione delle scorciatoie.