Documents Directory: Was es ist, Zweck und Dateizugriff

Was ist Documents Directory in iOS?

Documents Directory ist ein Verzeichnis innerhalb der iOS-App-Sandbox, das zum Speichern von Benutzerdaten entwickelt wurde, die zwischen Starts erhalten bleiben und dem Benutzer zugänglich sein sollen. Jede App erhält ihre eigene isolierte Sandbox, und Documents ist neben Caches, tmp und Library eines der wichtigsten Verzeichnisse.

iOS verwendet eine strenge Sandbox: Eine App hat ohne spezielle Berechtigungen keinen Zugriff auf das Dateisystem anderer Apps oder auf Systemverzeichnisse. Documents Directory ist das einzige Verzeichnis, dessen Inhalt der Benutzer über iTunes File Sharing anzeigen kann (wenn der Schlüssel UIFileSharingEnabled in Info.plist aktiviert ist).

Laut Apple WWDC 2023 verwenden mehr als 85% der Apps im App Store Documents Directory, um mindestens eine Art von Benutzerdaten zu speichern — von exportierten PDFs über gespeicherte Spieldateien bis hin zu exportierten Bildern.

Für den Entwickler ist es wichtig zu verstehen: Dateien in Documents werden automatisch in iCloud- und iTunes-Backups einbezogen. Wenn eine App große Mengen wiederherstellbarer Daten in Documents speichert (z.B. Bildercache oder temporäre Dateien), führt dies zu einer unnötigen Belegung des iCloud-Speicherplatzes des Benutzers.

So erhalten Sie den Pfad zu Documents Directory

In Swift wird der Pfad zu Documents Directory über FileManager ermittelt. Apple empfiehlt die Verwendung der URL-basierten API anstelle der string-basierten für eine bessere Kompatibilität mit modernen iOS-Funktionen.

import Foundation

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

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

Objective-C verwendet NSSearchPathForDirectoriesInDomains — einen älteren, aber weiterhin unterstützten Ansatz, der einen String-Pfad anstelle einer URL zurückgibt.

@import Foundation;

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

Moderne Projekte in Swift sollten FileManager.urls verwenden, da diese Methode eine URL statt eines Strings zurückgibt, wodurch das Risiko von Pfadkodierungsfehlern verringert und der Code typsicherer wird.

Welche Daten in Documents speichern

Documents Directory ist für Daten gedacht, die vom Benutzer erstellt wurden oder vom Benutzer explizit benötigt werden. Apple hebt mehrere Kategorien hervor, die für dieses Verzeichnis geeignet sind.

Benutzerdokumente und -dateien

Dateien, die der Benutzer erstellt oder importiert — Textdokumente, PDFs, Bilder, exportierte Berichte, Sicherungsdateien. Diese Daten haben einen direkten Wert für den Benutzer, und ihr Verlust wäre kritisch.

Spielstände und App-Zustand

Spielstände, App-Zustandsdateien, exportierte Projekte — alles, was der Benutzer nach einer Neuinstallation der App wiederherzustellen erwartet. Für kritische Daten wird jedoch zusätzlich die Verwendung von iCloud Key-Value Storage oder Core Data mit iCloud-Synchronisierung empfohlen.

Das entscheidende Kriterium: Wenn Daten aus dem Netzwerk erneut heruntergeladen oder neu erstellt werden können — gehören sie in Caches, nicht in Documents. Jedes Gigabyte in Documents ist ein Gigabyte im iCloud-Backup des Benutzers.

Backup und Synchronisierung

iOS bezieht automatisch den Inhalt von Documents Directory in Backups ein, wenn das Gerät mit iTunes verbunden wird oder bei der Synchronisierung mit iCloud. Dieses Verhalten kann nicht auf Verzeichnisebene deaktiviert werden — nur dateiweise über das Attribut NSURLIsExcludedFromBackupKey.

Ab iOS 5.0 begann Apple, Apps abzulehnen, die große Mengen wiederherstellbarer Daten in Documents speichern. Apples Empfehlung: Dateien, die erneut heruntergeladen werden können, sollten im Caches Directory mit dem Backup-Ausschluss-Flag gespeichert werden.

import Foundation

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

// Datei vom iCloud-Backup ausschließen
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Die iCloud-Synchronisierung funktioniert über NSUbiquitousContainer, wenn die App iCloud Documents verwendet. In diesem Fall werden Dateien aus Documents Directory automatisch zwischen den Geräten des Benutzers synchronisiert. Für Apps ohne iCloud beschränkt sich die Synchronisierung auf das Backup.

Documents Directory vs Caches Directory

Der Unterschied zwischen Documents und Caches ist eines der häufigsten Missverständnisse unter iOS-Anfängern. Der Hauptunterschied: Das System kann jederzeit Dateien aus Caches löschen, um Speicherplatz freizugeben, greift aber niemals ohne Wissen des Benutzers auf Documents zu.

Laut Apple Developer Documentation (2024) ist die unsachgemäße Verwendung von Documents Directory einer der häufigsten Gründe für die Ablehnung von Apps während der Überprüfung: Wenn eine App mehr als einige Megabyte wiederherstellbarer Daten in Documents speichert, empfiehlt Apple, diese nach Caches zu verschieben oder NSURLIsExcludedFromBackupKey anzuwenden.

Eine praktische Regel: Wenn der Benutzer über den Verlust der Datei verärgert wäre — speichern Sie sie in Documents. Wenn die Datei erneut heruntergeladen oder neu generiert werden kann — speichern Sie sie in Caches.

Bewährte Praktiken für die Arbeit mit Documents

Erfahrene iOS-Entwickler haben mehrere Regeln aufgestellt, die helfen, Probleme mit Documents Directory in allen Phasen des App-Lebenszyklus zu vermeiden — von der Entwicklung bis zur Veröffentlichung im App Store.

Überwachung der Verzeichnisgröße

Regelmäßig die Größe von Documents Directory über FileManager.enumerator(at:includingPropertiesForKeys:) überprüfen. Wenn die Größe 100 MB für nicht-benutzerspezifische Daten überschreitet — ist dies ein Grund, die Speicherarchitektur zu überdenken.

Ausschluss wiederherstellbarer Dateien vom Backup

Für alle Dateien, die erneut heruntergeladen werden können, setzen Sie isExcludedFromBackup = true. Dies reduziert die Belastung des iCloud-Speichers des Benutzers und verringert das Risiko einer Ablehnung durch App Review.

Migration bei Aktualisierungen

Wenn Sie das Datenformat in Documents ändern, planen Sie die Migration: Löschen Sie alte Dateien nicht, bis Sie sicher sind, dass neue korrekt erstellt wurden. Verwenden Sie versionsspezifische Unterverzeichnisse.

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
)

Die Befolgung dieser Praktiken reduziert das Risiko von Benutzerdatenverlust, verringert die Größe des iCloud-Backups und vereinfacht die App Store-Überprüfung.