Inviare dati ad altre app

Android utilizza gli intent e i relativi extra per consentire agli utenti di condividere rapidamente le informazioni utilizzando le loro app preferite.

Android offre agli utenti due modi per condividere i dati tra le app:

• Android Sharesheet è progettato principalmente per inviare contenuti al di fuori dell'app e/o direttamente a un altro utente. Ad esempio, per condividere un URL con un amico.
• Il resolver di intent di Android è più adatto per passare i dati alla fase successiva di un'attività ben definita. Ad esempio, per aprire un PDF dalla tua app e consentire agli utenti di scegliere il visualizzatore preferito.

Quando crei un intent, devi specificare l'azione che vuoi che esegua. Android utilizza l'azione ACTION_SEND per inviare dati da un'attività all'altra, anche tra i limiti dei processi. Devi specificare i dati e il relativo tipo. Il sistema identifica automaticamente le attività compatibili che possono ricevere i dati e le mostra all'utente. Nel caso del resolver di intent, se una sola attività può gestire l'intent, questa viene avviata immediatamente.

Perché utilizzare l'Android Sharesheet

Ti consigliamo vivamente di utilizzare Android Sharesheet per garantire la coerenza per gli utenti tra le app. Non mostrare l'elenco dei target di condivisione della tua app né creare varianti personalizzate del foglio di condivisione.

Il foglio di condivisione di Android consente agli utenti di condividere le informazioni con la persona giusta, con suggerimenti di app pertinenti, il tutto con un solo tocco. Il foglio di condivisione può suggerire target non disponibili per le soluzioni personalizzate e utilizza una classificazione coerente. Questo perché lo Sharesheet può tenere conto delle informazioni sull'attività dell'app e dell'attività utente disponibili solo per il sistema.

Android Sharesheet offre anche molte funzionalità utili per gli sviluppatori. Ad esempio, puoi:

• Scoprire quando e dove gli utenti completano una condivisione
• Aggiungere un ChooserTarget personalizzato e target di app
• Fornire anteprime di contenuti di testo RTF, a partire da Android 10 (livello API 29)
• Escludere i target che corrispondono a nomi di componenti specifici

Utilizzare l'Android Sharesheet

Per tutti i tipi di condivisione, crea un intent e imposta la relativa azione su Intent.ACTION_SEND. Per visualizzare l'Android Sharesheet, chiama Intent.createChooser(), passandogli l'oggetto Intent. Restituisce una versione del tuo intent che mostra sempre l'Android Sharesheet.

Inviare contenuti di testo

L'utilizzo più semplice e comune di Android Sharesheet è l'invio di contenuti di testo da un'Activity all'altra. Ad esempio, la maggior parte dei browser può condividere l'URL della pagina attualmente visualizzata come testo con un'altra app. Questa funzionalità è utile per condividere un articolo o un sito web con gli amici tramite email o social network. Ecco un esempio di come fare:

fun shareText(context: Context) {
    val sendIntent: Intent = Intent().apply {
        action = ACTION_SEND
        putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
        type = "text/plain"
    }

    val shareIntent = Intent.createChooser(sendIntent, null)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Facoltativamente, puoi aggiungere extra per includere ulteriori informazioni, come i destinatari delle email (EXTRA_EMAIL, EXTRA_CC, EXTRA_BCC), l'oggetto dell'email (EXTRA_SUBJECT) e così via.

Nota: alcune app di posta elettronica, come Gmail, prevedono un String[] per gli extra come EXTRA_EMAIL e EXTRA_CC. Utilizza putExtra(String, String[]) per aggiungerli all'intent.

Inviare contenuti binari

Condividi i dati binari utilizzando l'azione ACTION_SEND. Imposta il tipo MIME appropriato e inserisci un URI ai dati nell'extra EXTRA_STREAM, come mostrato nell'esempio seguente. Questa operazione viene comunemente utilizzata per condividere un'immagine, ma può essere utilizzata per condividere qualsiasi tipo di contenuto binario.

fun shareBinaryContent(context: Context) {
    val shareIntent: Intent = Intent().apply {
        action = ACTION_SEND
        // Example: content://com.google.android.apps.photos.contentprovider/...
        val imageUri: Uri =
            Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1")
        putExtra(Intent.EXTRA_STREAM, imageUri)
        type = "image/jpeg"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}
SharesheetSnippets.kt

L'applicazione ricevente deve avere l'autorizzazione per accedere ai dati a cui fa riferimento l'Uri. Esistono due modi consigliati per farlo:

• Archivia i dati nel tuo ContentProvider, assicurandoti che le altre app abbiano l'autorizzazione corretta per accedere al tuo provider. Il meccanismo preferito per fornire l'accesso è l'utilizzo delle autorizzazioni per URI, che sono temporanee e concedono l'accesso solo all'applicazione ricevente. Un modo per creare un ContentProvider di questo tipo è utilizzare la classe helper FileProvider.
• Utilizza il MediaStore di sistema. Il MediaStore è principalmente per i tipi MIME video, audio e immagine. Tuttavia, a partire da Android 3.0 (livello API 11), può anche archiviare tipi non multimediali. Per ulteriori informazioni, consulta MediaStore.Files. I file possono essere inseriti nel MediaStore utilizzando scanFile(), dopodiché viene passato un Uri in stile content:// adatto alla condivisione al callback onScanCompleted() fornito. Tieni presente che, una volta aggiunto al MediaStore di sistema, il contenuto è accessibile a qualsiasi app sul dispositivo.

Utilizzare il tipo MIME corretto

Fornisci il tipo MIME più specifico disponibile per i dati che stai inviando. Ad esempio, utilizza text/plain quando condividi testo normale. Ecco alcuni tipi MIME comuni quando invii dati in Android:

I ricevitori registrano	I mittenti inviano
text/*	text/plain text/rtf text/html text/json
`image/*`	image/jpg image/png image/gif
video/*	video/mp4 video/3gp
Estensioni file supportate	application/pdf

Attenzione: anche se puoi utilizzare un tipo MIME */*, ti sconsigliamo vivamente di farlo perché la maggior parte delle app riceventi non è in grado di ricevere alcun tipo di contenuto. Idealmente, la tua app deve corrispondere alle attività che possono gestire flussi di dati generici.

Per ulteriori informazioni sui tipi MIME, consulta il registro ufficiale IANA dei tipi di media MIME.

L'Android Sharesheet potrebbe mostrare un'anteprima dei contenuti, a seconda del tipo MIME fornito. Alcune funzionalità di anteprima sono disponibili solo per tipi specifici.

Condividere più contenuti

Per condividere più contenuti, utilizza l'azione ACTION_SEND_MULTIPLE insieme a un elenco di URI che rimandano ai contenuti. Il tipo MIME varia a seconda del mix di contenuti che stai condividendo. Ad esempio, se condividi tre immagini JPEG, utilizzi il tipo "image/jpg". Per un mix di tipi di immagine, utilizza "image/*" per trovare un'attività che gestisce qualsiasi tipo di immagine. Sebbene sia possibile condividere un mix di tipi, ti sconsigliamo vivamente di farlo perché il destinatario non sa cosa deve essere inviato. Se è necessario inviare più tipi, utilizza "*/*". L'applicazione ricevente deve analizzare ed elaborare i dati. Ecco un esempio:

fun shareMultiple(context: Context) {
    val imageUris: ArrayList<Uri> = arrayListOf(
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1"),
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/2")
    )

    val shareIntent = Intent().apply {
        action = Intent.ACTION_SEND_MULTIPLE
        putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris)
        type = "image/*"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}
SharesheetSnippets.kt

Assicurati che gli oggetti Uri forniti rimandino a dati a cui un'applicazione ricevente può accedere.

Aggiungere contenuti avanzati alle anteprime di testo

A partire da Android 10 (livello API 29), Android Sharesheet mostra un'anteprima del testo condiviso. In alcuni casi, il testo condiviso può essere difficile da comprendere. Prendi in considerazione la condivisione di un URL complicato come https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. Un'anteprima più ricca può rassicurare gli utenti su ciò che viene condiviso.

Se stai visualizzando l'anteprima del testo, puoi impostare un titolo, un'immagine miniatura o entrambi. Aggiungi una descrizione a Intent.EXTRA_TITLE prima di chiamare Intent.createChooser() e aggiungi una miniatura pertinente utilizzando ClipData.

Nota: l'URI contenuto immagine viene fornito da un FileProvider, in genere da un <cache-path>. Per ulteriori informazioni, consulta Condividere file. Assicurati di concedere al foglio di condivisione le autorizzazioni corrette per leggere qualsiasi immagine che vuoi utilizzare come miniatura. Per ulteriori informazioni, consulta Intent.FLAG_GRANT_READ_URI_PERMISSION.

Ecco un esempio:

fun richContentToTextPreviewShares(context: Context) {
    val share = Intent.createChooser(
        Intent().apply {
            action = ACTION_SEND
            putExtra(Intent.EXTRA_TEXT, "https://developer.android.com/training/sharing/")

            // (Optional) Here you're setting the title of the content
            putExtra(Intent.EXTRA_TITLE, "Introducing content previews")

            // (Optional) Here you're passing a content URI to an image to be displayed
            data =
                Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/A123456789")
            flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
        },
        null
    )
    context.startActivity(share)
}
SharesheetSnippets.kt

L'anteprima ha un aspetto simile al seguente:

Aggiungere azioni personalizzate al foglio di condivisione

Screenshot delle azioni personalizzate nell'Android Sharesheet.

Su Android 14 (livello API 34) e versioni successive, le app possono aggiungere azioni personalizzate all'Android Sharesheet. Le azioni personalizzate vengono visualizzate come piccole icone di azione nella parte superiore di Android Sharesheet e le app possono specificare qualsiasi Intent come azione richiamata quando si fa clic sull'icona.

Per aggiungere azioni personalizzate all'Android Sharesheet, crea prima un ChooserAction con ChooserAction.Builder. Puoi specificare un PendingIntent come azione richiamata quando si fa clic sull'icona. Crea un array contenente tutte le azioni personalizzate e specificalo come EXTRA_CHOOSER_CUSTOM_ACTIONS dell'Intent di condivisione.

fun sharesheetCustomActions(context: Context, previewText: String) {
    val sendIntent = Intent(ACTION_SEND)
        .setType("text/plain")
        .putExtra(Intent.EXTRA_TEXT, previewText)
    val shareIntent = Intent.createChooser(sendIntent, null)
    val customActions = arrayOf(
        ChooserAction.Builder(
            Icon.createWithResource(context, R.drawable.ic_logo),
            "Custom",
            PendingIntent.getBroadcast(
                context,
                1,
                Intent(Intent.ACTION_VIEW),
                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
            )
        ).build()
    )
    shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Aggiungere target personalizzati

L'Android Sharesheet ti consente di specificare fino a due ChooserTarget oggetti che vengono visualizzati prima delle scorciatoie di condivisione e dei target di scelta caricati da ChooserTargetServices. Puoi anche specificare fino a due intent che rimandano ad attività elencate prima dei suggerimenti di app:

Aggiungi Intent.EXTRA_CHOOSER_TARGETS e Intent.EXTRA_INITIAL_INTENTS all'intent di condivisione dopo aver chiamato Intent.createChooser():

val share = Intent.createChooser(shareIntent, null).apply {
    putExtra(
        Intent.EXTRA_CHOOSER_TARGETS,
        arrayOf(chooserTargetJessica, chooserTargetSpyros)
    )
    putExtra(
        Intent.EXTRA_INITIAL_INTENTS,
        arrayOf(intentTargetNearbyShare, intentTargetMaps)
    )
}
SharesheetSnippets.kt

Utilizza questa funzionalità con cautela. Ogni Intent e ChooserTarget personalizzato che aggiungi riduce il numero di suggerimenti del sistema. In genere, ti sconsigliamo di aggiungere target personalizzati. Un esempio comune e appropriato di aggiunta di Intent.EXTRA_INITIAL_INTENTS è fornire azioni aggiuntive che gli utenti possono intraprendere sui contenuti condivisi. Ad esempio, un utente condivide immagini e Intent.EXTRA_INITIAL_INTENTS viene utilizzato per consentirgli di inviare un link. Un esempio comune e appropriato di aggiunta di Intent.EXTRA_CHOOSER_TARGETS è mostrare persone o dispositivi pertinenti forniti dalla tua app.

Escludere target specifici per componente

Puoi escludere target specifici fornendo Intent.EXTRA_EXCLUDE_COMPONENTS. Esegui questa operazione solo per rimuovere i target su cui hai il controllo. Un caso d'uso comune è nascondere i target di condivisione della tua app quando gli utenti condividono contenuti dall'interno dell'app, poiché è probabile che vogliano condividere contenuti al di fuori dell'app.

Aggiungi Intent.EXTRA_EXCLUDE_COMPONENTS all'intent dopo aver chiamato Intent.createChooser():

fun excludeSpecificTargets(context: Context) {
    val share = Intent.createChooser(Intent(ACTION_SEND), null).apply {
        // Only use for components you have control over
        val excludedComponentNames =
            arrayOf(ComponentName("com.example.android", "ExampleClass"))
        putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames)
    }
    context.startActivity(share)
}
SharesheetSnippets.kt

Ottenere informazioni sulla condivisione

Può essere utile sapere quando gli utenti condividono contenuti e quale target selezionano. L'Android Sharesheet ti consente di ottenere queste informazioni fornendo il ComponentName dei target selezionati dagli utenti utilizzando un IntentSender.

Innanzitutto, crea un PendingIntent per un BroadcastReceiver e fornisci il relativo IntentSender in Intent.createChooser():

fun infoAboutSharing(context: Context, requestCode: Int) {
    var share = Intent(ACTION_SEND)
    // ...
    val pi = PendingIntent.getBroadcast(
        context, requestCode,
        Intent(context, ShareBroadcastReceiver::class.java),
        PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
    )
    share = Intent.createChooser(share, null, pi.intentSender)
    context.startActivity(share)
}
SharesheetSnippets.kt

Ricevi il callback in MyBroadcastReceiver e cerca in Intent.EXTRA_CHOOSER_RESULT:

override fun onReceive(context: Context?, intent: Intent) {
    val TAG = ShareBroadcastReceiver::class.simpleName
    val chooserResult: ChooserResult? = IntentCompat.getParcelableExtra(
        intent,
        Intent.EXTRA_CHOOSER_RESULT,
        ChooserResult::class.java,
    )
    chooserResult?.let {
        Log.i(TAG,
            "Share callback: isShortcut: ${it.isShortcut}, type: ${typeToString(it.type)}, componentName: ${it.selectedComponent}",
        )
    } ?: Log.i(TAG, "chooserResult is null")
}
ShareBroadcastReceiver.kt

Per ulteriori informazioni, consulta l'esempio di condivisione della piattaforma:

Aggiungere azioni personalizzate al foglio di condivisione

Su Android 14 (livello API 34) e versioni successive, le app possono aggiungere azioni personalizzate all'Android Sharesheet. Crea un ChooserAction con ChooserAction.Builder. Puoi specificare un PendingIntent come azione richiamata quando si fa clic sull'icona. Crea un array contenente tutte le azioni personalizzate e specificalo come EXTRA_CHOOSER_CUSTOM_ACTIONS dell'Intent di condivisione.

fun customActions(context: Context, text: String) {
    val sendIntent = Intent(ACTION_SEND)
        .setType("text/plain")
        .putExtra(Intent.EXTRA_TEXT, text)
    val shareIntent = Intent.createChooser(sendIntent, null)
    val customActions = arrayOf(
        ChooserAction.Builder(
            Icon.createWithResource(context, R.drawable.ic_logo),
            "Custom",
            PendingIntent.getBroadcast(
                context,
                1,
                Intent(Intent.ACTION_VIEW),
                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
            )
        ).build()
    )
    shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Utilizzare il resolver di intent di Android

Screenshot del resolver di intent ACTION_SEND.

Il resolver di intent di Android è più adatto per l'invio di dati a un'altra app nell'ambito di un flusso di attività ben definito.

Per utilizzare il resolver di intent di Android, crea un intent e aggiungi gli extra come faresti per chiamare Android Sharesheet. Tuttavia, non chiamare Intent.createChooser().

Se sono presenti più applicazioni installate con filtri che corrispondono a ACTION_SEND e al tipo MIME, il sistema visualizza una finestra di dialogo di disambiguazione denominata resolver di intent che consente all'utente di scegliere un target di condivisione. Se una singola applicazione corrisponde, viene eseguita.

Ecco un esempio di come utilizzare il resolver di intent di Android per inviare testo:

fun intentResolver(context: Context) {
    val sendIntent: Intent = Intent().apply {
        action = ACTION_SEND
        putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
        type = "text/plain"
    }
    context.startActivity(sendIntent)
}
SharesheetSnippets.kt

Scopri di più

Per ulteriori informazioni sull'invio di dati, consulta Intent e filtri di intent.