Fornire target di condivisione diretta

Figura 1: riga Condivisione diretta in Sharesheet, come mostrato da 1

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 poi cercare il contatto.

Nota: a partire da Android 11 (livello API 30), puoi offrire la funzionalità Condivisione diretta target solo tramite l'API Sharing Shortcuts descritta più avanti questa pagina.

ShortcutManagerCompat è un'API AndroidX che fornisce scorciatoie per la condivisione, compatibile con l'API ChooserTargetService deprecata. È il metodo preferito per pubblicare sia le scorciatoie di condivisione sia ChooserTargets. Per istruzioni, leggi l'articolo Utilizzare AndroidX per fornire scorciatoie di condivisione etargets 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. Quando l'app viene inizializzata, usa setDynamicShortcuts per ordinare le scorciatoie dinamiche per importanza.

   Un indice più basso indica più importanza. Se fai una comunicazione possono essere le conversazioni principali, ordinate per data più recente, nel momento in cui appaiono la tua app. Non pubblicare scorciatoie obsolete. una conversazione senza L'attività utente negli ultimi 30 giorni è considerata inattiva.

   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, segnala l'utilizzo dei messaggi inviati dall'utente tramite specificando le associazioni di funzionalità nella scorciatoia 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 È il metodo preferito per rimuovere la scorciatoia a prescindere dal fatto che sia memorizzata o meno nella cache dal sistema i servizi di machine learning. 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 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 abbia una lunga durata chiamando setLongLived(true)
• Segnala l'utilizzo delle scorciatoie relative alle conversazioni per i messaggi in uscita e in arrivo 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 SMS, evita di fornire scorciatoie per codici brevi o conversazioni identificati 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 SMS, se il contatto non è abilitato per RCS o MMS, non associare la scorciatoia corrispondente a tipi MIME non testuali 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. 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 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 Share 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 intenzioni 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 annullata o resa invisibile dall'app (come scorciatoia dinamica o fissata). 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.

Una scorciatoia di lunga durata può migliorarne il ranking. 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.

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, che riduce drasticamente 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 raggiungere questo obiettivo è scalare la bitmap quadrata prevista 72 x 72 dp e centra quello all'interno di una tela trasparente da 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 degli utenti per Direct Share ChooserTarget 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 di condivisione, tramite ShortcutManagerCompat, plasma automaticamente gli oggetti con condivisione diretta ChooserTarget le cerchie per te.

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 condivisione definizioni del target 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 corrispondenti e target che gestirà l'intenzione di condivisione. Il codice XML ha un aspetto simile nel seguente modo:

<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 target di condivisione può avere più categorie, che vengono usate solo per corrispondere alle scorciatoie pubblicate di un'app con le relative definizioni di target di condivisione. Le categorie possono avere qualsiasi definizione arbitraria dell'app e i relativi valori.

Nel caso in cui l'utente selezioni la scorciatoia di condivisione in Android Sharesheet che corrisponde alla quota target di esempio riportata sopra, l'app riceverà quanto segue intenzione 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 durante l'aggiunta della scorciatoia di condivisione ScorciatoiaManagerCompat. Poiché è 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 Sharesheet di Android segnalando l'utilizzo dei messaggi sia in uscita che 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 facendo clic sul pulsante "Invia" dopo aver creato un messaggio.

Per attivare i report sull'utilizzo, specifica le associazioni di funzionalità nella scorciatoia alla 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);

Se il messaggio in uscita è per una chat di gruppo, devi aggiungere anche Audience del parametro recipient è associato alla funzionalità.

Kotlin

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)

Java

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, ad esempio un SMS: messaggio di chat, email o notifiche, devi specificare anche associazioni nella scorciatoia ShortcutInfoCompat.Builder#addCapabilityBinding con la funzionalità actions.intent.RECEIVE_MESSAGE.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_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.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à.

Kotlin

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)

Java

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 un la 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 della funzionalità Direct Share?

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 ChooserTargetService Direct Condividi le API con la nuova API Share Shortcuts. 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 massimo per questo limite, ma tieni presente che le scorciatoie per la condivisione possono essere visibili in Avvio applicazioni premi a lungo e nel foglio di condivisione. La maggior parte di Avvio applicazioni su premere a lungo per visualizzare un massimo di quattro o cinque scorciatoie in modalità verticale e otto in modalità Orizzontale. Visualizza Domande frequenti per ulteriori dettagli e indicazioni sulla condivisione delle scorciatoie.