Casi d'uso e best practice per lo spazio di archiviazione di Android

Per offrire agli utenti un maggiore controllo sui propri file e limitare il disordine, Android 10 ha introdotto un nuovo paradigma di archiviazione per le app chiamato archiviazione mirata. L'archiviazione mirata modifica il modo in cui le app archiviano e accedono ai file nell'unità di archiviazione esterna di un dispositivo. Per aiutarti a eseguire la migrazione della tua app in modo che supporti l'archiviazione mirata, segui le best practice per i casi d'uso dello spazio di archiviazione comuni descritti in questa guida. I casi d'uso sono organizzati in due categorie: gestione dei file multimediali e gestione dei file non multimediali.

In molti casi, l'app crea file a cui altre app non devono o non dovrebbero accedere. Il sistema fornisce posizioni di archiviazione specifiche per le app per gestire questi file.

Per scoprire di più su come archiviare i file e accedervi su Android, consulta le guide alla formazione sullo spazio di archiviazione.

Gestisci i file multimediali

Questa sezione descrive alcuni dei casi d'uso comuni per la gestione dei file multimediali (file video, immagine e audio) e spiega l'approccio generale che la tua app può utilizzare. La tabella seguente riassume ciascuno di questi casi d'uso e rimanda alle sezioni che contengono ulteriori dettagli.

Caso d'uso Riepilogo
Mostra tutti i file immagine o video Utilizza lo stesso approccio per tutte le versioni di Android.
Mostra immagini o video di una cartella specifica Utilizza lo stesso approccio per tutte le versioni di Android.
Accedi ai dati sulla posizione dalle foto Utilizza un approccio se la tua app utilizza l'archiviazione mirata. Utilizza un approccio diverso se la tua app disattiva l'archiviazione mirata.
Definisci la posizione di archiviazione per i nuovi download Utilizza un approccio se la tua app utilizza l'archiviazione mirata. Utilizza un approccio diverso se la tua app disattiva l'archiviazione mirata.
Esporta i file multimediali degli utenti su un dispositivo Utilizza lo stesso approccio per tutte le versioni di Android.
Modifica o elimina più file multimediali in un'unica operazione Utilizza un approccio per Android 11. Per Android 10, disattiva l'archiviazione mirata e utilizza l'approccio per Android 9 e versioni precedenti.
Importa una singola immagine già esistente Utilizza lo stesso approccio per tutte le versioni di Android.
Acquisisci una singola immagine Utilizza lo stesso approccio per tutte le versioni di Android.
Condividi file multimediali con altre app Utilizza lo stesso approccio per tutte le versioni di Android.
Condividi file multimediali con un'app specifica Utilizza lo stesso approccio per tutte le versioni di Android.
Accedi ai file da codice o librerie che utilizzano percorsi file diretti Utilizza un approccio per Android 11. Per Android 10, disattiva l'archiviazione mirata e utilizza l'approccio per Android 9 e versioni precedenti.

Mostra file di immagini o video da più cartelle

Esegui una query su una raccolta multimediale utilizzando l'API query(). Per filtrare o ordinare i file multimediali, modifica i parametri projection, selection, selectionArgs e sortOrder.

Mostrare immagini o video di una cartella specifica

Utilizza questo approccio:

  1. Seguendo le best practice descritte in Richiedi autorizzazioni app, richiedi l'autorizzazione READ_EXTERNAL_STORAGE.
  2. Recupera i file multimediali in base al valore di MediaColumns.DATA, che contiene il percorso assoluto del file system dell'elemento multimediale sul disco.

Nota: Quando accedi a un file multimediale esistente, puoi utilizzare il valore delDATA colonna nella tua logica. Questo perché questo valore ha un percorso file valido. Tuttavia, non dare per scontato che il file sia sempre disponibile. Preparati a gestire eventuali errori di I/O basati su file che potrebbero verificarsi.

Per creare o aggiornare un file multimediale, invece, non utilizzare la colonna DATA. Utilizza invece le colonne DISPLAY_NAME e RELATIVE_PATH.

Accedere ai dati sulla posizione dalle foto

Se la tua app utilizza l'archiviazione mirata, segui i passaggi descritti nella sezione Dati sulla posizione nelle fotografie della guida all'archiviazione dei contenuti multimediali.

Definisci la posizione di archiviazione per i nuovi download

Se la tua app utilizza l'archiviazione mirata, tieni presente la posizione in cui scegli di archiviare i file multimediali che scarichi.

Se altre app richiedono l'accesso ai file, valuta la possibilità di utilizzare raccolte di contenuti multimediali ben definite per i download o le raccolte di documenti.

Su Android 11 e versioni successive, i file all'interno della directory esterna specifica per l'app non sono accessibili ad altre app, anche se utilizzi DownloadManager per recuperare questi file.

Esporta i file multimediali dell'utente su un dispositivo

Definisci una località predefinita appropriata per archiviare i file multimediali degli utenti:

Modifica o elimina più file multimediali in un'unica operazione

Incorpora la logica in base alle versioni di Android su cui viene eseguita la tua app.

Esecuzione su Android 11

Utilizza questo approccio:

  1. Crea un pending intent per la richiesta di scrittura o eliminazione della tua app utilizzando MediaStore.createWriteRequest() o MediaStore.createTrashRequest() e poi chiedi all'utente l'autorizzazione per modificare un insieme di file richiamando l'intent.

  2. Valuta la risposta dell'utente:

    • Se l'autorizzazione è stata concessa, procedi con l'operazione di modifica o eliminazione.
    • Se l'autorizzazione non è stata concessa, spiega all'utente perché la funzionalità della tua app ne ha bisogno.

Scopri di più su come gestire gruppi di file multimediali utilizzando questi metodi disponibili su Android 11 e versioni successive.

È in esecuzione su Android 10

Se la tua app ha come target Android 10 (livello API 29), disattiva l'archiviazione mirata e continua a utilizzare l'approccio per Android 9 e versioni precedenti per eseguire questa operazione.

Usa Android 9 o versioni precedenti

Utilizza questo approccio:

  1. Seguendo le best practice descritte in Richiedi autorizzazioni app, richiedi l'autorizzazione WRITE_EXTERNAL_STORAGE.
  2. Utilizza l'API MediaStore per modificare o eliminare i file multimediali.

Importa una singola immagine già esistente

Quando vuoi importare una singola immagine già esistente (ad esempio, da utilizzare come foto per il profilo di un utente), la tua app può utilizzare la propria UI per l'operazione o il picker di sistema.

Presenta la tua interfaccia utente

Utilizza questo approccio:

  1. Seguendo le best practice descritte in Richiedi autorizzazioni app, richiedi l'autorizzazione READ_EXTERNAL_STORAGE.
  2. Utilizza l'API query() per eseguire query su una raccolta multimediale.
  3. Visualizza i risultati nella UI personalizzata della tua app.

Utilizza il picker di sistema

Utilizza l'intent ACTION_GET_CONTENT, che chiede all'utente di scegliere un'immagine da importare.

Se vuoi filtrare i tipi di immagini che il picker di sistema presenta all'utente tra cui scegliere, puoi utilizzare setType() o EXTRA_MIME_TYPES.

Acquisisci una singola immagine

Quando vuoi acquisire una singola immagine da utilizzare nella tua app (ad esempio, da utilizzare come foto per il profilo di un utente), utilizza l'intent ACTION_IMAGE_CAPTURE per chiedere all'utente di scattare una foto utilizzando la fotocamera del dispositivo. Il sistema memorizza la foto acquisita nella tabella MediaStore.Images.

Condividi file multimediali con altre app

Utilizza il metodo insert() per aggiungere record direttamente in MediaStore. Per saperne di più, consulta la sezione Aggiungi un elemento della guida allo spazio di archiviazione multimediale.

Condividi file multimediali con un'app specifica

Utilizza il componente Android FileProvider, come descritto nella guida Configurazione della condivisione file.

Accedere ai file da codice o librerie che utilizzano percorsi file diretti

Incorpora la logica in base alle versioni di Android su cui viene eseguita la tua app.

Esecuzione su Android 11

Utilizza questo approccio:

  1. Seguendo le best practice descritte in Richiedi autorizzazioni app, richiedi l'autorizzazione READ_EXTERNAL_STORAGE.
  2. Accedere ai file utilizzando i percorsi file diretti.

Per saperne di più, consulta la sezione su come aprire i file multimediali utilizzando i percorsi file diretti.

È in esecuzione su Android 10

Se la tua app ha come target Android 10 (livello API 29), disattiva l'archiviazione mirata e continua a utilizzare l'approccio per Android 9 e versioni precedenti per eseguire questa operazione.

Usa Android 9 o versioni precedenti

Utilizza questo approccio:

  1. Seguendo le best practice descritte in Richiedi autorizzazioni app, richiedi l'autorizzazione WRITE_EXTERNAL_STORAGE.
  2. Accedere ai file utilizzando i percorsi file diretti.

Gestisci i file non multimediali

Questa sezione descrive alcuni dei casi d'uso comuni per la gestione di file non multimediali e spiega l'approccio generale che la tua app può utilizzare. La tabella seguente riassume ciascuno di questi casi d'uso e rimanda alle sezioni che contengono ulteriori dettagli.

Caso d'uso Riepilogo
Apri un file di documento Utilizza lo stesso approccio per tutte le versioni di Android.
Scrittura su file in volumi di archiviazione secondari Utilizza un approccio per Android 11. Utilizza un approccio diverso per le versioni precedenti di Android.
Esegui la migrazione dei file esistenti da una posizione di archiviazione precedente Esegui la migrazione dei file all'archiviazione mirata, se possibile. Disattiva l'archiviazione mirata per Android 10, se necessario.
Condividi contenuti con altre app Utilizza lo stesso approccio per tutte le versioni di Android.
Memorizza nella cache i file non multimediali Utilizza lo stesso approccio per tutte le versioni di Android.
Esporta file non multimediali su un dispositivo Utilizza un approccio se la tua app utilizza l'archiviazione mirata. Utilizza un approccio diverso se la tua app disattiva l'archiviazione mirata.

Apri un file di documento

Utilizza l'intent ACTION_OPEN_DOCUMENT per chiedere all'utente di scegliere un file da aprire utilizzando il picker di sistema. Se vuoi filtrare i tipi di file che il picker di sistema presenterà all'utente tra cui scegliere, puoi utilizzare setType() o EXTRA_MIME_TYPES.

Ad esempio, puoi trovare tutti i file PDF, ODT e TXT utilizzando il seguente codice:

Kotlin

startActivityForResult(
        Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
            addCategory(Intent.CATEGORY_OPENABLE)
            type = "*/*"
            putExtra(Intent.EXTRA_MIME_TYPES, arrayOf(
                    "application/pdf", // .pdf
                    "application/vnd.oasis.opendocument.text", // .odt
                    "text/plain" // .txt
            ))
        },
        REQUEST_CODE
      )

Java

Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
        intent.addCategory(Intent.CATEGORY_OPENABLE);
        intent.setType("*/*");
        intent.putExtra(Intent.EXTRA_MIME_TYPES, new String[] {
                "application/pdf", // .pdf
                "application/vnd.oasis.opendocument.text", // .odt
                "text/plain" // .txt
        });
        startActivityForResult(intent, REQUEST_CODE);

Scrittura di file su volumi di archiviazione secondari

I volumi di archiviazione secondari includono le schede SD. Puoi accedere alle informazioni su un determinato volume di archiviazione utilizzando la classe StorageVolume.

Incorpora la logica in base alla versione di Android su cui viene eseguita la tua app.

Esecuzione su Android 11

Utilizza questo approccio:

  1. Utilizza il modello di archiviazione mirata.
  2. Target Android 10 (livello API 29) o versioni precedenti.
  3. Dichiara l'autorizzazione WRITE_EXTERNAL_STORAGE.
  4. Esegui uno dei seguenti tipi di accesso:
    • Accesso ai file tramite l'API MediaStore.
    • Accesso diretto al percorso dei file utilizzando API come File o fopen().

Esecuzione su versioni precedenti

Utilizza lo Storage Access Framework, che consente agli utenti di selezionare la posizione su un volume di spazio di archiviazione secondario in cui la tua app può scrivere il file.

Esegui la migrazione dei file esistenti da una posizione di archiviazione precedente

Una directory è considerata una posizione di archiviazione precedente se non è una directory specifica dell'app o una directory condivisa pubblica. Se la tua app crea o utilizza file in una posizione di archiviazione precedente, ti consigliamo di eseguire la migrazione dei file dell'app in posizioni accessibili con l'archiviazione mirata e di apportare le modifiche necessarie all'app per utilizzare i file nell'archiviazione mirata.

Mantieni l'accesso alla posizione di archiviazione legacy per la migrazione dei dati

La tua app deve mantenere l'accesso alla posizione di archiviazione precedente per eseguire la migrazione di tutti i file dell'app in posizioni accessibili con l'archiviazione mirata. L'approccio da utilizzare dipende dal livello API target della tua app.

Se la tua app ha come target Android 11

  1. Imposta il flag preserveLegacyExternalStorage su true per conservare il modello di archiviazione precedente in modo che la tua app possa eseguire la migrazione dei dati di un utente quando esegue l'upgrade alla nuova versione della tua app che ha come target Android 11.

  2. Continua a disattivare l'archiviazione mirata in modo che la tua app possa continuare ad accedere ai file nella posizione di archiviazione precedente sui dispositivi Android 10.

Se la tua app ha come target Android 10

Disattiva l'archiviazione mirata per semplificare il mantenimento del comportamento della tua app nelle varie versioni di Android.

Esegui la migrazione dei dati delle app

Quando l'app è pronta per la migrazione, utilizza il seguente approccio:

  1. Target Android 10 o versioni precedenti.
  2. Disattiva l'archiviazione mirata in modo che la tua app abbia accesso ai file di cui devi eseguire la migrazione.

  3. Esegui il deployment del codice che utilizza l'API File per spostare i file dalla loro posizione attuale in /sdcard/ a una posizione accessibile con l'archiviazione mirata:

    1. Sposta tutti i file privati dell'app nella directory restituita dal metodo getExternalFilesDir().
    2. Sposta tutti i file non multimediali condivisi in una sottodirectory dedicata all'app della directory Downloads/.
  4. Rimuovi le directory di archiviazione legacy dell'app dalla directory /sdcard/.

Dopo aver installato la nuova versione dell'app, gli utenti completano la procedura di migrazione dei dati sui propri dispositivi. Puoi monitorare il processo di migrazione nella tua base utenti creando un evento di analisi.

Dopo che gli utenti hanno eseguito la migrazione dei dati, pubblica un altro aggiornamento della tua app, in cui scegli come target Android 11.

Condividi contenuti con altre app

Per condividere i file della tua app con un'altra singola app, utilizza un FileProvider. Per le app che devono condividere file tra loro, ti consigliamo di utilizzare un provider di contenuti per ogni app e poi di sincronizzare i dati man mano che le app vengono aggiunte alla raccolta.

Memorizza nella cache i file non multimediali

L'approccio da utilizzare dipende dal tipo di file che devi memorizzare nella cache.

Esporta file non multimediali su un dispositivo

Definisci una località predefinita appropriata per archiviare i file non multimediali. Consenti agli utenti di esportare i file dalle directory specifiche dell'app in una posizione più accessibile. Utilizza le raccolte di download o documenti di MediaStore per esportare file non multimediali sul dispositivo.

Gestisci i file specifici dell'app

Se la tua app crea file a cui altre app non devono o non dovrebbero accedere, puoi archiviarli in posizioni di archiviazione specifiche per l'app.

Directory di archiviazione interna

Il sistema impedisce ad altre app di accedere a queste posizioni e, su Android 10 (livello API 29) e versioni successive, queste posizioni sono criptate. Queste posizioni sono un buon posto per archiviare dati sensibili a cui solo la tua app può accedere.

Directory di archiviazione esterna

Se lo spazio di archiviazione interno non è sufficiente per archiviare i file specifici dell'app, valuta la possibilità di utilizzare lo spazio di archiviazione esterno. Sebbene sia possibile per un'altra app accedere a queste directory se dispone delle autorizzazioni appropriate, i file archiviati in queste directory sono destinati all'utilizzo solo da parte della tua app.

Su Android 4.4 (livello API 19) o versioni successive, l'app non deve richiedere autorizzazioni relative allo spazio di archiviazione per accedere alle directory specifiche dell'app all'interno dello spazio di archiviazione esterno.

Quando l'utente disinstalla l'app, i file salvati nello spazio di archiviazione specifico dell'app vengono rimossi, pertanto non devi utilizzare questo spazio di archiviazione per salvare elementi che l'utente si aspetta che vengano conservati indipendentemente dall'app.

Disattivare temporaneamente l'archiviazione mirata

Prima che la tua app sia completamente compatibile con l'archiviazione mirata, puoi disattivarla temporaneamente, sia nei test sia nell'app di produzione.

Disattivazione nei test

Su Android 10 (livello API 29) e versioni successive, i test della tua app vengono eseguiti in una sandbox di archiviazione per impostazione predefinita. Questa sandbox impedisce all'app di accedere ai file al di fuori della directory specifica dell'app e delle directory condivise pubblicamente.

Se un test genera file per l'host, ad esempio screenshot, dati di debug, dati di copertura o metriche sul rendimento, puoi scrivere questi file in directory globali. Per farlo, aggiungi il seguente flag all'harness pertinente che richiama am instrument:

-e no-isolated-storage 1

Questo flag influisce su tutto il comportamento dello scenario di test di instrumentazione e su tutto il codice di test richiamato. Pertanto, quando utilizzi questo flag, non puoi convalidare la compatibilità della tua app con l'archiviazione mirata. Per l'output di test, è meglio scrivere nell'archiviazione mirata leggibile dalla shell. Puoi quindi estrarre la directory con ambito app. Per determinare da quale directory eseguire il pull, chiama getExternalMediaDirs().

Disattivazione nell'app di produzione

Se la tua app ha come target Android 10 (livello API 29) o versioni precedenti, puoi disattivare temporaneamente l'archiviazione mirata nell'app di produzione. Se il target è Android 10, devi impostare il valore di requestLegacyExternalStorage su true nel file manifest dell'app:

<manifest ... >
  <!-- This attribute is "false" by default on apps targeting
       Android 10. -->
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

Per testare il comportamento di un'app che ha come target Android 10 o versioni precedenti quando utilizza l'archiviazione mirata, puoi attivare il comportamento impostando il valore di requestLegacyExternalStorage su false. Se esegui i test su un dispositivo con Android 11, puoi anche utilizzare i flag di compatibilità delle app per testare il comportamento della tua app con o senza archiviazione mirata.

Risorse aggiuntive

Per saperne di più sullo spazio di archiviazione di Android, consulta i seguenti materiali:

Blog post