Documents Directory: cos'è, scopo e accesso ai file

Cos'è Documents Directory in iOS?

Documents Directory è una directory all'interno del sandbox di un'app iOS progettata per archiviare dati utente che devono persistere tra i lanci ed essere accessibili all'utente. Ogni app riceve il proprio sandbox isolato e Documents è una delle directory chiave insieme a Caches, tmp e Library.

iOS utilizza un sandbox rigoroso: un'app non ha accesso al file system di altre app o a directory di sistema senza permessi speciali. Documents Directory è l'unica directory il cui contenuto l'utente può visualizzare tramite iTunes File Sharing (quando la chiave UIFileSharingEnabled è attivata in Info.plist).

Secondo Apple WWDC 2023, oltre l'85% delle app nell'App Store utilizza Documents Directory per archiviare almeno un tipo di dato utente — dai PDF esportati ai file di gioco salvati e alle immagini esportate.

È importante che lo sviluppatore capisca: i file in Documents vengono automaticamente inclusi nei backup di iCloud e iTunes. Se un'app archivia grandi volumi di dati recuperabili in Documents (ad esempio, cache di immagini o file temporanei), ciò porta a un consumo non necessario dello spazio di archiviazione iCloud dell'utente.

Come ottenere il percorso di Documents Directory

In Swift, il percorso di Documents Directory si ottiene tramite FileManager. Apple consiglia di utilizzare l'API basata su URL invece di quella basata su stringhe per una migliore compatibilità con le funzionalità moderne di iOS.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Creare file in Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C utilizza NSSearchPathForDirectoriesInDomains — un approccio più vecchio ma ancora supportato che restituisce un percorso stringa invece di un URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

I progetti moderni in Swift dovrebbero usare FileManager.urls, poiché questo metodo restituisce un URL invece di una stringa, riducendo il rischio di errori di codifica del percorso e rendendo il codice più sicuro dal punto di vista dei tipi.

Quali dati archiviare in Documents

Documents Directory è destinata ai dati creati dall'utente o esplicitamente necessari all'utente. Apple evidenzia diverse categorie appropriate per questa directory.

Documenti e file utente

File che l'utente crea o importa — documenti di testo, PDF, immagini, report esportati, file di backup. Questi dati hanno un valore diretto per l'utente e la loro perdita sarebbe critica.

Salvataggi di giochi e stato dell'app

Salvataggi di giochi, file di stato dell'app, progetti esportati — tutto ciò che l'utente si aspetta di ripristinare dopo la reinstallazione dell'app. Tuttavia, per i dati critici si consiglia di utilizzare anche iCloud Key-Value Storage o Core Data con sincronizzazione iCloud.

Il criterio chiave: se i dati possono essere scaricati nuovamente dalla rete o ricreati — il loro posto è in Caches, non in Documents. Ogni gigabyte in Documents è un gigabyte nel backup iCloud dell'utente.

Backup e sincronizzazione

iOS include automaticamente il contenuto di Documents Directory nei backup quando il dispositivo è connesso a iTunes o durante la sincronizzazione con iCloud. Questo comportamento non può essere disattivato a livello di directory — solo per file tramite l'attributo NSURLIsExcludedFromBackupKey.

A partire da iOS 5.0, Apple ha iniziato a rifiutare le app che archiviano grandi volumi di dati recuperabili in Documents. La raccomandazione di Apple: i file che possono essere scaricati nuovamente dovrebbero essere archiviati in Caches Directory con il flag di esclusione dal backup.

import Foundation

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

// Escludere file dal backup iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

La sincronizzazione iCloud funziona tramite NSUbiquitousContainer se l'app utilizza iCloud Documents. In questo caso, i file di Documents Directory vengono automaticamente sincronizzati tra i dispositivi dell'utente. Per le app senza iCloud, la sincronizzazione è limitata al backup.

Documents Directory vs Caches Directory

La differenza tra Documents e Caches è uno degli equivoci più comuni tra gli sviluppatori iOS principianti. La differenza principale: il sistema può eliminare i file da Caches in qualsiasi momento per liberare spazio, ma non tocca mai Documents senza il consenso dell'utente.

Secondo la Documentazione Apple Developer (2024), l'uso improprio di Documents Directory è una delle ragioni comuni di rifiuto delle app durante la revisione: se un'app archivia più di pochi megabyte di dati recuperabili in Documents, Apple consiglia di spostarli in Caches o di applicare NSURLIsExcludedFromBackupKey.

Una regola pratica: se l'utente sarebbe arrabbiato per la perdita del file — conservalo in Documents. Se il file può essere scaricato nuovamente o rigenerato — conservalo in Caches.

Buone pratiche per lavorare con Documents

Gli sviluppatori iOS esperti hanno sviluppato diverse regole che aiutano a evitare problemi con Documents Directory in tutte le fasi del ciclo di vita dell'app — dallo sviluppo alla pubblicazione sull'App Store.

Monitoraggio delle dimensioni della directory

Regolarmente controlla le dimensioni di Documents Directory tramite FileManager.enumerator(at:includingPropertiesForKeys:). Se le dimensioni superano 100 MB per dati non utente — è un motivo per riconsiderare l'architettura di archiviazione.

Esclusione dei file recuperabili dal backup

Per qualsiasi file che possa essere scaricato nuovamente, imposta isExcludedFromBackup = true. Questo riduce il carico sull'archiviazione iCloud dell'utente e diminuisce il rischio di rifiuto da parte di App Review.

Migrazione durante gli aggiornamenti

Quando modifichi il formato dei dati in Documents, pianifica la migrazione: non eliminare i file vecchi finché non sei sicuro che quelli nuovi siano stati creati correttamente. Usa sottodirectory specifiche per versione.

import Foundation

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

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Seguire queste buone pratiche riduce il rischio di perdita di dati utente, diminuisce le dimensioni del backup iCloud e semplifica la revisione sull'App Store.