Fornire target di condivisione diretta

Utilizza i target della condivisione diretta per rendere più semplice e veloce per gli utenti di altre app per condividere URL, immagini o altri tipi di dati con la tua app. Opere di Direct Share presentando i contatti dalle 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 scorciatoie per la condivisione, compatibile con l'API ChooserTargetService deprecata. 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.

Pubblica target della condivisione diretta

La riga Condivisione diretta di Sharesheet mostra solo le scorciatoie dinamiche fornite API Share Shortcuts. Completa i seguenti passaggi per pubblicare la funzionalità Direct Share target.

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 più importanza. Se stai creando un'app di comunicazione, possono essere le conversazioni principali ordinate in base all'ordine di apparizione nella tua 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. Vedi Segnalare l'utilizzo delle scorciatoie per app di comunicazione in questa pagina per ulteriori informazioni. 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 della procedura.

   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 target della condivisione diretta. Questi suggerimenti sono ordinati per ranking. Puoi potenzialmente migliorare il ranking del tuo procedendo nel seguente modo:

• Assicurati che tutti i shortcutIds siano univoci e non vengano mai riutilizzati per target diversi.
• Assicurati che la scorciatoia sia permanente 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. Vedi Segnalare l'utilizzo di scorciatoie per le app di comunicazione su questa app. pagina per informazioni dettagliate.
• 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 di messaggistica, evita di fornire scorciatoie per codici brevi o conversazioni identificate come potenziali spam. È molto improbabile che gli utenti condividano conversazioni.
• Chiama setCategories() per associare la scorciatoia al appropriato mimeType attributi. 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 data conversazione, una volta eseguito il push di una scorciatoia dinamica e l'utilizzo viene segnalato, non modificare l'ID della scorciatoia. In questo modo, viene garantita la conservazione dei dati sull'utilizzo per il ranking.

Se l'utente tocca un target della condivisione diretta, l'app deve indirizzarlo a una UI in cui possono eseguire un'azione direttamente sull'oggetto del target. Non presentare all'utente una UI di disambiguazione e non collocarla in una UI non correlata obiettivo toccato. Ad esempio, in un'app di messaggistica, toccare una condivisione diretta target porta l'utente a una visualizzazione per conversazione con la persona selezionata. La sia visibile e il messaggio sia 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 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. Vedi Dichiarare una condivisione target per maggiori dettagli. Questo campo è obbligatorio per le scorciatoie da utilizzare 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 dura a lungo, può essere memorizzata nella cache da vari servizi di sistema anche dopo la pubblicazione è stata annullata come scorciatoia dinamica.

Se mantieni una scorciatoia attiva per un lungo periodo di tempo, il suo ranking può migliorare. Vedi Il meglio per maggiori dettagli.

setShortLabel(), setLongLabel()

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

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

Fornire immagini di scorciatoie

Per creare una scorciatoia di 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, fornire 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 è ridimensionare la bitmap quadrata prevista a 72 x 72 dp e centrarla in una tela trasparente di 108 x 108 dp. Se la tua icona include aree trasparenti, devi includere un colore di sfondo; altrimenti le aree trasparenti appaiono nere.

Non fornire immagini mascherate in base a 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. Android Sharesheet e altri piattaforme di sistema in Android 10 ora sono immagini con scorciatoie per forma e tema. 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, come per le definizioni delle scorciatoie statiche. Aggiungi le definizioni di target di 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 target 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 definizione arbitraria dell'app e i relativi valori.

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é è 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 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.

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

Segnalare l'utilizzo delle scorciatoie per i messaggi in uscita

L'utilizzo dei report per i messaggi inviati dall'utente è simile a facendo 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 anche aggiungere Audience come valore del parametro 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 scorciatoie per la condivisione e target di selezione

Per poter funzionare con la libreria di compatibilità con AndroidX, il file manifest dell'app deve contenere il servizio di scelta dei metadati e i filtri per intent. Consulta l'attuale API ChooserTargetService Direct Share.

Questo servizio è già dichiarato nella libreria di compatibilità, quindi l'utente lo non è necessario dichiarare il servizio nel file manifest dell'app. Tuttavia, il link da l'attività di condivisione con il servizio deve essere presa in considerazione come target del selettore o il provider di servizi di terze parti.

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

Come vengono memorizzati i dati sull'utilizzo delle scorciatoie e quando lasciano il dispositivo?

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

Qual è la storia di Condivisione diretta?

Abbiamo introdotto la funzionalità Direct Share in Android 6.0 (livello API 23) per consentire alle app di fornisce ChooserTarget oggetti tramite un ChooserTargetService. I risultati erano recuperate in modo reattivo on demand, con conseguente rallentamento del tempo di caricamento dei target.

In Android 10 (livello API 29), abbiamo sostituito le ChooserTargetService API Direct Share con la nuova API Shortcuts for Sharing. Invece di recuperare i risultati in modo reattivo on demand, l'API Share Shortcuts consente alle app di pubblicare Direct Share obiettivi in anticipo. Questo ha accelerato rapidamente il processo di recupero della condivisione diretta durante la preparazione di ShareSheet. La quota diretta di ChooserTargetService continuerà a funzionare, ma il sistema classifica gli obiettivi forniti in questo modo inferiore rispetto a qualsiasi target che utilizzi l'API Sharing Shortcuts.

Android 11 (livello API 30) ha ritirato il servizio ChooserTargetService. L'API Share Shortcuts è l'unico modo per fornire destinazioni della Condivisione diretta.

Differenze delle scorciatoie pubblicate per i target di condivisione da Avvio app scorciatoie (l'utilizzo tipico delle scorciatoie quando si preme a lungo sulle icone delle app Avvio app)?

Qualsiasi scorciatoia pubblicata per una "condivisione di destinazione" è anche un'applicazione e verrà mostrata nel menu quando premi a lungo l'icona dell'app. La il limite massimo di scorciatoie per attività si applica anche al numero totale di comandi scorciatoie pubblicate da un'app (condivisione di target e scorciatoie precedenti in Avvio applicazioni combinati).

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

Il numero di scorciatoie di condivisione è vincolato allo stesso limite delle scorciatoie dinamiche scorciatoie 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 di Avvio applicazioni su tieni premuto a lungo 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.