Fornire target di condivisione diretta

Utilizza i target di Direct Share 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. Direct Share funziona 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 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 che i target di scelta in questa pagina.

Pubblica target della condivisione diretta

La riga Condivisione diretta di Sharesheet mostra solo le scorciatoie dinamiche fornite dall'API Shared 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. Quando l'app viene inizializzata, usa 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 conversazioni principali ordinate per data più recente nell'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, vedi Segnalare l'utilizzo di scorciatoie per le app di comunicazione in questa pagina. Ad esempio, segnala l'utilizzo dei messaggi inviati dall'utente specificando le 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 o meno 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 i ranking dei target della condivisione diretta

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

• Assicurati che tutti i shortcutIds siano univoci e non vengano mai riutilizzati per target diversi.
• Assicurati che la scorciatoia abbia una 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, vedi Segnalare l'utilizzo delle scorciatoie per le app di comunicazione in questa pagina.
• Evita di fornire target non pertinenti o inattivi per la condivisione diretta, ad esempio contatti a cui l'utente non ha inviato messaggi negli ultimi 30 giorni.
• Per le app SMS, evita di fornire scorciatoie per codici brevi o 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 SMS, se il contatto non è abilitato per RCS o MMS, non dovresti associare 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 della scorciatoia. Ciò garantisce 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 può eseguire un'azione direttamente sull'oggetto del target. Non presentare all'utente un'interfaccia utente di disambiguazione e non inserirla in una UI non correlata al target toccato. Ad esempio, in un'app di messaggistica, toccando una destinazione della 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 Share Shortcuts

A partire da Android 10 (livello API 29), ShortcutInfo.Builder ha aggiunto metodi e miglioramenti che forniscono ulteriori informazioni 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 informazioni dettagliate, consulta Dichiarare un target di condivisione. Questo campo è obbligatorio per le scorciatoie che devono essere utilizzate come destinazioni di condivisione.

setLongLived()

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

Una scorciatoia di lunga durata può migliorarne il ranking. Per informazioni dettagliate, consulta Ottenere il ranking migliore.

setShortLabel(), setLongLabel()

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

Guarda 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 per la 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 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 raggiungere questo obiettivo è scalare la bitmap quadrata desiderata a 72 x 72 dp e centrarla all'interno di un canvas trasparente di 108 x 108 dp. Se l'icona include aree trasparenti, devi includere un colore di sfondo; in caso contrario, le regioni 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 degli utenti per la condivisione diretta ChooserTarget mascherati da un cerchio. Android Sharesheet e altre piattaforme di sistema in Android 10 ora sono immagini di scorciatoie per forma e tema. Il metodo preferito per fornire scorciatoie di condivisione, tramite ShortcutManagerCompat, modella automaticamente gli oggetti ChooserTarget a condivisione diretta in modo da trasformarli in cerchi.

Dichiara un target per la condivisione

Le destinazioni di condivisione devono essere dichiarate nel file di risorse dell'app, come per le definizioni delle scorciatoie statiche. Aggiungi definizioni della destinazione 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'intenzione 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 dei dati in un target di condivisione è simile alla specifica dei dati in un filtro per intent. Ogni destinazione della condivisione può avere più categorie, che vengono utilizzate solo per associare le scorciatoie pubblicate di un'app alle relative definizioni della destinazione di condivisione. Le categorie possono avere qualsiasi valore arbitrario definito dall'app.

Se l'utente seleziona la scorciatoia di condivisione in Sharesheet di Android che corrisponde all'esempio di condivisione target di cui 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 della condivisione dalle scorciatoie Avvio app, l'app riceverà l'intent creato al momento dell'aggiunta della scorciatoia di condivisione a ShortcutManagerCompat. Poiché si tratta di un intent diverso, Intent.EXTRA_SHORTCUT_ID non sarà disponibile e dovrai passare manualmente l'ID 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 segnalando l'utilizzo sia per i messaggi in uscita che per quelli in arrivo. 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).

Segnala l'utilizzo delle scorciatoie per i messaggi in uscita

L'utilizzo dei report per i messaggi inviati dall'utente è simile a fare 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 è 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);

Segnala l'utilizzo delle scorciatoie per i messaggi in arrivo

Per attivare i report sull'utilizzo quando l'utente riceve un messaggio come SMS, messaggio di chat, 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 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 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 di destinazione e i filtri per intent. Visualizza l'attuale API ChooserTargetService Direct Share.

Questo servizio è già dichiarato nella libreria di compatibilità, quindi l'utente non deve dichiarare il servizio nel manifest dell'app. Tuttavia, il link dall'attività di condivisione al servizio deve essere considerato come provider di destinazione del selettore.

Nell'esempio seguente, l'implementazione di ChooserTargetService è androidx.core.content.pm.ChooserTargetServiceCompat, 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 memorizzati i dati sull'utilizzo delle scorciatoie e quando lasciano il dispositivo?

Le scorciatoie vengono archiviate interamente sul dispositivo, nella directory dei dati di sistema in una partizione del disco criptata. Le informazioni contenute 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 funzionalità Direct Share?

Abbiamo introdotto Direct Share 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, il che ha causato un tempo di caricamento lento per gli obiettivi.

In Android 10 (livello API 29), abbiamo sostituito le ChooserTargetService API Direct Share con la nuova API Sharing Shortcuts. Anziché recuperare i risultati in modo reattivo on demand, l'API Share Shortcuts consente alle app di pubblicare in anticipo i target della 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 che vengono forniti in questo modo più in basso rispetto a qualsiasi target che utilizza l'API Share Shortcuts.

Android 11 (livello API 30) ha ritirato il servizio ChooserTargetService e l'APISharing Shortcuts è l'unico modo per fornire i target della 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 con lo scopo di "condividere un target" è anch'essa una scorciatoia in Avvio applicazioni e verrà visualizzata nel menu quando premi a lungo l'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 Avvio applicazioni precedenti combinati).

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). Si può pubblicare qualsiasi numero entro tale limite, ma occorre tenere presente che le scorciatoie di condivisione possono essere visibili in Avvio applicazioni pressione prolungata e nel foglio di condivisione. La maggior parte delle app Avvio app alla pressione prolungata 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.