Directory documenti in un'app mobile — cos'è, scopo e come organizzare l'archiviazione

Cos'è la directory dei documenti dell'applicazione?

La directory dei documenti è un archivio specializzato all'interno del sandbox dell'applicazione, progettato per l'archiviazione permanente dei file utente. A differenza della cache, i file in questa directory sono considerati importanti per l'utente: il sistema non li elimina quando lo spazio scarseggia, vengono preservati durante gli aggiornamenti dell'app e vengono sottoposti a backup durante la sincronizzazione del dispositivo. Su iOS, la directory Documents fa parte del contenitore Sandbox e viene inclusa automaticamente nel backup di iCloud. Su Android, non esiste un equivalente diretto — l'equivalente è context.filesDir, anch'esso destinato a file permanenti ma senza un meccanismo di backup integrato.

La differenza tra la directory dei documenti e l'archiviazione interna su Android è minima: entrambi si trovano nel sandbox dell'app, entrambi vengono eliminati alla disinstallazione, entrambi sono inaccessibili ad altre app. La differenza principale è semantica: la Directory Documenti presuppone che i file siano creati o importati dall'utente, mentre l'archiviazione interna può contenere file interni dell'app (database, configurazioni). Su iOS, la differenza è più sostanziale: Documents viene sottoposto automaticamente a backup, mentre Library/Application Support no. Questo influenza la strategia di archiviazione: metti solo ciò che l'utente vorrebbe ripristinare su un nuovo dispositivo in Documents, e i dati interni che l'app può ricreare in Application Support.

L'architettura a sandbox garantisce che altre applicazioni non possano accedere alla directory dei documenti della tua app. Su iOS, l'accesso ai Documents di altre app è impossibile senza jailbreak. Su Android, l'accesso root permette di leggere il filesDir di qualsiasi app, quindi i dati sensibili (token, chiavi di crittografia) devono essere protetti ulteriormente con EncryptedSharedPreferences o EncryptedFile della libreria AndroidX Security.

Quali dati sono archiviati nella directory dei documenti

La directory dei documenti dovrebbe archiviare dati che hanno valore per l'utente e devono essere accessibili dopo il riavvio dell'app o il ripristino del dispositivo. Non tutti i file sono adatti all'archiviazione in questa directory — la scelta dipende dal tipo di dati e dallo scenario d'uso.

Documenti e file utente

I file utente sono il contenuto principale della directory dei documenti. Possono essere documenti di testo creati in un editor, immagini scattate con la fotocamera dell'app, report PDF esportati, registrazioni audio, note. Ciascuno di questi file è creato dall'utente o su sua richiesta e deve essere accessibile in qualsiasi momento. Su iOS, i file di Documents vengono visualizzati nell'app File di sistema, consentendo all'utente di gestirli tramite il gestore file standard. Su Android, non esiste una visualizzazione simile — l'app deve fornire essa stessa un'interfaccia per visualizzare i file salvati.

Database e impostazioni dell'app

I database SQLite e i file di impostazione vengono solitamente archiviati vicino alla directory dei documenti, ma non al suo interno. Su iOS, i database vengono collocati in Library/Application Support, poiché non dovrebbero apparire nell'app File ed essere sottoposti a backup separatamente. Su Android, i database vengono creati per impostazione predefinita in /data/data/<package>/databases/ tramite Room o SQLiteOpenHelper. Se il database contiene contenuti utente (note, diario, registri finanziari), può essere collocato in filesDir per garantire il backup di sistema. Room consente di specificare una directory di archiviazione personalizzata per il database tramite il callback RoomDatabase.Builder.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

Dati esportati e importati

I file che l'utente importa da altre app o esporta dalla tua app dovrebbero essere anch'essi salvati nella directory dei documenti. Su iOS, l'import tramite UIDocumentPickerViewController posiziona automaticamente una copia del file in Documents quando si utilizza il parametro asCopy: true. Su Android, l'import tramite il dialogo SAF crea anch'esso una copia del file nel sandbox dell'app. Durante l'esportazione dei dati (ad esempio, la creazione di un file CSV con i contatti), salva prima il file in Documents/filesDir, quindi offri all'utente di condividerlo tramite Share Sheet. Questo garantisce che, anche se l'utente dimentica di salvare il file dopo l'invio, una copia rimanga nell'app per un uso successivo.

Come lavorare con la directory dei documenti su Android

Su Android, la funzione della directory dei documenti è svolta da context.filesDir. Inoltre, è disponibile la directory context.externalFilesDir sulla scheda SD, ma non garantisce l'integrità dei dati. Esaminiamo le principali tecniche per lavorare con queste directory.

Accesso e gestione dei file tramite filesDir

filesDir è la directory principale per i file permanenti dell'app su Android. Si trova nel sandbox dell'app e viene completamente eliminata alla disinstallazione. Per ottenere un'istanza File, usa context.filesDir, che restituisce il percorso a /data/data/<package>/files/. Per creare e leggere file, usa le operazioni Java/Kotlin File standard o i metodi Context openFileInput() e openFileOutput(), che prendono un nome file e restituiscono FileInputStream/FileOutputStream. Il metodo openFileOutput() crea automaticamente il file in filesDir se non esiste ancora e permette di specificare la modalità di accesso: MODE_PRIVATE (solo l'app corrente), MODE_APPEND (aggiunta) o MODE_WORLD_READABLE (deprecato, non utilizzato da API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Caratteristiche di archiviazione su Android 10+

Su Android 10+, il modello Scoped Storage non influisce su filesDir — l'accesso completo al proprio sandbox dell'app rimane. Tutte le operazioni di lettura e scrittura all'interno di filesDir non richiedono autorizzazioni aggiuntive. Tuttavia, se provi ad accedere ai file di un'altra app tramite filesDir, otterrai un'eccezione. Per condividere file, usa FileProvider, che crea un URI di contenuto temporaneo per trasferire un file a un'altra app. FileProvider viene dichiarato in AndroidManifest.xml tramite il tag <provider> e configurato in un file XML dei percorsi. Questo è il meccanismo standard per il trasferimento di file tra app, utilizzato, ad esempio, quando si invia un'immagine tramite Intent con ACTION_SEND.

Come lavorare con la directory dei documenti su iOS

Su iOS, la Documents Directory fa parte del contenitore Sandbox dell'app con uno status speciale. I file di questa directory vengono automaticamente inclusi nel backup di iCloud, visualizzati nell'app File e preservati durante gli aggiornamenti dell'app tramite App Store.

Directory dei documenti e backup

Il backup automatico di Documents è un vantaggio chiave di iOS. Quando l'utente collega il dispositivo a iTunes o attiva iCloud Backup, tutti i file da Documents/ vengono copiati nel backup. Al ripristino su un nuovo dispositivo, l'utente riceve tutti i suoi file senza azioni aggiuntive. Tuttavia, questo vantaggio diventa uno svantaggio se l'app archivia grandi quantità di dati in Documents: il tempo di backup aumenta e lo spazio iCloud potrebbe esaurirsi rapidamente. Pertanto, Documents dovrebbe archiviare solo i file di cui l'utente ha realmente bisogno durante il ripristino. I file temporanei, la cache e i dati ricreabili dovrebbero trovarsi in Caches o Library/Application Support. Apple raccomanda di escludere dal backup i file che possono essere scaricati nuovamente da Internet, tramite l'attributo isExcludedFromBackup.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Contenuto della nota"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive e sincronizzazione tra dispositivi

iCloud Drive consente di sincronizzare i file di Documents tra i dispositivi di un utente. Per attivare la sincronizzazione, l'app dovrebbe utilizzare le API NSDocument o UIDocument, che gestiscono automaticamente il versionamento e la risoluzione dei conflitti. Un approccio alternativo è l'uso di iCloud con CloudKit, che offre un controllo più flessibile sulla sincronizzazione ma richiede configurazione su CloudKit Dashboard. Quando utilizzi iCloud Drive, assicurati di gestire correttamente i conflitti di modifica (merge o last-write-wins) e di informare l'utente sullo stato della sincronizzazione tramite l'interfaccia dell'app. iCloud non garantisce la sincronizzazione istantanea — il ritardo può variare da pochi secondi a diversi minuti a seconda della dimensione del file e della qualità della connessione. Per i dati critici, utilizza scrittura transazionale e versionamento in modo che in caso di conflitto, la versione precedente del file possa essere ripristinata.

Differenze dalla directory cache e migliori pratiche

Scegliere correttamente tra Documents Directory e Cache Directory determina l'affidabilità dell'archiviazione dei dati utente. Un errore nella scelta porta alla perdita di dati (se i file importanti sono archiviati nella cache) o al sovraccarico del backup (se i file temporanei sono archiviati in Documents).

Le migliori pratiche per l'uso della directory dei documenti includono diverse regole chiave. Primo, chiedi sempre conferma all'utente prima di eliminare file da questa directory. A differenza della cache, eliminare un documento può portare alla perdita irreversibile di contenuti utente. Secondo, implementa il versionamento dei file: quando sovrascrivi un file esistente, salva la versione precedente con il suffisso _backup o utilizza meccanismi Snapshot. Terzo, fornisci all'utente un'interfaccia per visualizzare, rinominare, eliminare ed esportare file dalla directory dei documenti. Su iOS, i file di Documents vengono automaticamente visualizzati in File; su Android, devi implementare un tuo gestore file o utilizzare librerie di terze parti.

Presta particolare attenzione alla migrazione dei dati durante gli aggiornamenti dell'app. Se la nuova versione modifica la struttura di archiviazione dei file (ad esempio, sposta i dati da una sottodirectory a un'altra o cambia il formato del file), implementa una migrazione una tantum al primo avvio dopo l'aggiornamento. Conserva il numero di versione dello schema dati in SharedPreferences ed esegui la migrazione se non corrispondono. Non eliminare i file vecchi prima del completamento della migrazione — in caso di fallimento, l'utente non deve perdere dati. Se la migrazione comporta una conversione di formato (ad esempio, il passaggio da JSON a SQLite), salva i file originali come backup in una directory separata con la data di migrazione. L'utente dovrebbe essere in grado di annullare le modifiche tramite le impostazioni dell'app entro i primi 30 giorni dall'aggiornamento, come raccomandato dalle Apple Human Interface Guidelines.