Fornire target di condivisione diretta

Utilizza i target 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 in Sharesheet di Android, senza che gli utenti debbano selezionare l'app e poi cercare il contatto.

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

Pubblicare i target di condivisione diretta

La riga di condivisione diretta di Sharesheet 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 della tua 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 inferiore indica una maggiore importanza. Se stai creando un'app di comunicazione, puoi visualizzare le conversazioni principali ordinate in base alla data di ricezione, così come appaiono 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 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, segnala l'utilizzo dei messaggi inviati dall'utente specificando i binding delle funzionalità nella scorciatoia tramite ShortcutInfoCompat.Builder#addCapabilityBinding con la actions.intent.SEND_MESSAGE funzionalità.

   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 target di condivisione diretta. Questi suggerimenti sono ordinati in base al ranking. Puoi potenzialmente migliorare il ranking delle tue scorciatoie nei seguenti modi:

• Assicurati che tutti gli shortcutIds siano univoci e non vengano mai riutilizzati per target diversi.
• Assicurati che la scorciatoia sia a 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 maggiori dettagli, consulta la sezione 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 per SMS, evita di fornire scorciatoie per i codici brevi o le conversazioni identificate come potenziale spam. È molto improbabile che gli utenti condividano queste conversazioni.
• Chiama setCategories() per associare la scorciatoia agli attributi mimeType appropriati. 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 di testo, come image/* e video/*.
• Per una determinata conversazione, una volta che una scorciatoia dinamica viene inviata e l'utilizzo viene segnalato, non modificare l'ID della scorciatoia. In questo modo, i dati di utilizzo vengono conservati per il ranking.

Se l'utente tocca un target di condivisione diretta, la tua app deve portarlo 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, toccando un target di condivisione diretta l'utente viene portato a una visualizzazione per conversazione con la persona selezionata. La tastiera è visibile e il messaggio viene 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. Per maggiori dettagli, consulta la sezione 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 annullata la pubblicazione o resa invisibile dall'app (come scorciatoia dinamica o aggiunta alla schermata Home). Se una scorciatoia è a lunga durata, può essere memorizzata nella cache da vari servizi di sistema anche dopo che la pubblicazione è stata annullata come scorciatoia dinamica.

Rendere una scorciatoia a lunga durata può migliorarne il ranking. Per maggiori dettagli, consulta la sezione Ottenere il miglior ranking.

setShortLabel(), setLongLabel()

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

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

Fornire 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 di 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 venga visualizzata come 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 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 con una forma specifica. Ad esempio, prima di Android 10 (livello API 29), era comune fornire avatar utente per i target di scelta di condivisione diretta ChooserTarget mascherati con un cerchio. Android Sharesheet e altre piattaforme di sistema in Android 10 ora modellano e applicano temi alle immagini delle scorciatoie. Il metodo preferito per fornire le scorciatoie di condivisione, tramite ShortcutManagerCompat, modella automaticamente gli oggetti di condivisione diretta per la retrocompatibilità ChooserTarget in cerchi.

Dichiarare un target di condivisione

I target di condivisione devono essere dichiarati nel file di risorse dell'app, in modo simile alle definizioni delle scorciatoie statiche. Aggiungi le definizioni dei target di condivisione all'interno dell'elemento root <shortcuts> nel file di risorse, insieme ad altre definizioni di scorciatoie statiche. Ogni <share-targets> elemento contiene informazioni sul tipo di dati condivisi, sulle categorie corrispondenti e sulla classe target che gestirà l'intent di condivisione. Il codice XML è 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 dati in un target 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 relative definizioni dei target di condivisione. Le categorie possono avere valori arbitrari definiti dall'app.

Se l'utente seleziona la scorciatoia per la condivisione in Android Sharesheet che corrisponde al target di condivisione di esempio riportato 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 il target di condivisione dalle scorciatoie di avvio, l'app riceverà l'intent creato quando la scorciatoia per la condivisione è stata aggiunta a ShortcutManagerCompat. Poiché si tratta di un intent diverso, Intent.EXTRA_SHORTCUT_ID non sarà disponibile e dovrai passare l'ID manualmente se ne hai bisogno.

Segnalare l'utilizzo delle scorciatoie per le app di comunicazione

Se stai sviluppando un'app di comunicazione, puoi migliorare il tuo ranking in Android Sharesheet segnalando 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 i binding delle funzionalità sono retrocompatibili con Android 5.0 (API 21).

Segnalare l'utilizzo delle scorciatoie per i messaggi in uscita

La segnalazione dell'utilizzo dei messaggi inviati dall'utente è funzionalmente simile al clic sul pulsante "Invia" dopo aver creato un messaggio.

Per attivare la segnalazione dell'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 anche aggiungere il Audience valore del parametro perché il recipient tipo è 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 entrata

Per attivare la segnalazione dell'utilizzo quando l'utente riceve un messaggio, ad esempio un SMS, un messaggio di chat, un'email o una notifica, devi anche specificare 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 anche aggiungere il Audience valore parametro perché il sender tipo è 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);

Utilizzare AndroidX per fornire sia le scorciatoie di condivisione sia i target di scelta

Per poter utilizzare la libreria di compatibilità AndroidX, il manifest dell'app deve contenere i metadati chooser-target-service e i filtri per intent impostati. Consulta l'API di condivisione diretta ChooserTargetService corrente.

Questo servizio è già dichiarato nella libreria di compatibilità, quindi l'utente non deve dichiararlo nel manifest dell'app. Tuttavia, il link dall'attività di condivisione al servizio deve essere considerato come un fornitore di target di scelta.

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 archiviati i dati di utilizzo delle scorciatoie e se lasciano il 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 l'icona, l'intent e i nomi di persone e risorse, sono accessibili solo dai servizi di sistema e dalla stessa app che pubblica le scorciatoie.

Qual è la cronologia della condivisione diretta?

Abbiamo introdotto la condivisione diretta in Android 6.0 (livello API 23) per consentire alle app di fornire ChooserTarget oggetti 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 di condivisione diretta ChooserTargetService con la nuova API Sharing Shortcuts. Anziché recuperare i risultati in modo reattivo su richiesta, l'API Sharing Shortcuts consente alle app di pubblicare in anticipo i target di condivisione diretta. 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 in modo 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 i target di condivisione diretta.

In che modo le scorciatoie pubblicate per i target di condivisione sono diverse 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 "target di condivisione" è anche una scorciatoia di avvio e verrà visualizzata nel menu quando si preme a lungo sull'icona dell'app. Il limite massimo del numero di scorciatoie per attività si applica anche al numero totale di scorciatoie pubblicate da un'app (target di condivisione e scorciatoie di avvio legacy combinate).

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

Il numero di scorciatoie di condivisione è vincolato allo stesso limite di scorciatoie dinamiche disponibili tramite getMaxShortcutCountPerActivity(android.content.Context). È possibile pubblicare un numero qualsiasi fino a questo limite, ma tieni presente che le scorciatoie di condivisione possono essere visibili nella pressione prolungata dell'avvio app e in Sharesheet. La maggior parte degli avvii app con pressione prolungata visualizza un massimo di quattro o cinque scorciatoie in modalità verticale e otto in modalità orizzontale. Per maggiori dettagli e indicazioni sulle scorciatoie di condivisione, consulta queste domande frequenti.