Dokumentenverzeichnis in einer mobilen App — was es ist, Zweck und wie man die Speicherung organisiert

Was ist das Dokumentenverzeichnis der Anwendung?

Das Dokumentenverzeichnis ist ein spezialisierter Speicher innerhalb der App-Sandbox, der für die dauerhafte Speicherung von Benutzerdateien ausgelegt ist. Im Gegensatz zum Cache werden Dateien in diesem Verzeichnis als wichtig für den Benutzer betrachtet: Sie werden vom System bei Platzmangel nicht gelöscht, bleiben bei App-Updates erhalten und werden bei der Gerätesynchronisation gesichert. Unter iOS ist das Documents-Verzeichnis Teil des Sandbox-Containers und wird automatisch in das iCloud-Backup einbezogen. Unter Android gibt es kein direktes Äquivalent — das Äquivalent ist context.filesDir, das ebenfalls für dauerhafte Dateien vorgesehen ist, aber keinen integrierten Backup-Mechanismus hat.

Der Unterschied zwischen dem Dokumentenverzeichnis und dem internen Speicher unter Android ist minimal: Beide befinden sich in der App-Sandbox, beide werden bei der Deinstallation gelöscht, beide sind für andere Apps nicht zugänglich. Der Hauptunterschied ist semantischer Natur: Das Documents Directory geht davon aus, dass Dateien vom Benutzer erstellt oder importiert wurden, während der interne Speicher interne App-Dateien (Datenbanken, Konfigurationen) enthalten kann. Unter iOS ist der Unterschied substanzieller: Documents wird automatisch gesichert, Library/Application Support jedoch nicht. Dies beeinflusst die Speicherstrategie: Legen Sie nur das in Documents ab, was der Benutzer auf einem neuen Gerät wiederherstellen möchte, und interne Daten, die die App neu erstellen kann, in Application Support.

Die Sandbox-Architektur stellt sicher, dass andere Anwendungen nicht auf das Dokumentenverzeichnis Ihrer App zugreifen können. Unter iOS ist der Zugriff auf Documents anderer Apps ohne Jailbreak unmöglich. Unter Android ermöglicht Root-Zugriff das Lesen des filesDir jeder App, daher müssen sensible Daten (Tokens, Verschlüsselungsschlüssel) zusätzlich mit EncryptedSharedPreferences oder EncryptedFile aus der AndroidX Security-Bibliothek geschützt werden.

Welche Daten werden im Dokumentenverzeichnis gespeichert

Das Dokumentenverzeichnis sollte Daten speichern, die für den Benutzer wertvoll sind und nach einem Neustart der App oder Wiederherstellung des Geräts zugänglich sein müssen. Nicht alle Dateien sind für die Speicherung in diesem Verzeichnis geeignet — die Wahl hängt vom Datentyp und Nutzungsszenario ab.

Benutzerdokumente und -dateien

Benutzerdateien sind der Hauptinhalt des Dokumentenverzeichnisses. Dies können Textdokumente sein, die in einem Editor erstellt wurden, mit der App-Kamera aufgenommene Bilder, exportierte PDF-Berichte, Audioaufnahmen, Notizen. Jede solche Datei wird vom Benutzer oder auf dessen Anfrage erstellt und muss jederzeit zugänglich sein. Unter iOS werden Dateien aus Documents in der systemeigenen Files-App angezeigt, sodass der Benutzer sie über den Standard-Dateimanager verwalten kann. Unter Android gibt es keine ähnliche Anzeige — die App muss selbst eine Oberfläche zum Anzeigen gespeicherter Dateien bereitstellen.

Datenbanken und App-Einstellungen

SQLite-Datenbanken und Einstellungsdateien werden normalerweise in der Nähe des Dokumentenverzeichnisses gespeichert, aber nicht darin. Unter iOS werden Datenbanken in Library/Application Support abgelegt, da sie nicht in der Files-App angezeigt und nicht separat gesichert werden sollen. Unter Android werden Datenbanken standardmäßig in /data/data/<package>/databases/ über Room oder SQLiteOpenHelper erstellt. Wenn die Datenbank Benutzerinhalte (Notizen, Tagebuch, Finanzaufzeichnungen) enthält, kann sie in filesDir abgelegt werden, um die Systemsicherung zu gewährleisten. Room ermöglicht die Angabe eines benutzerdefinierten Verzeichnisses für die Datenbankspeicherung über den RoomDatabase.Builder-Callback.

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

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

Exportierte und importierte Daten

Dateien, die der Benutzer aus anderen Apps importiert oder aus Ihrer App exportiert, sollten ebenfalls im Dokumentenverzeichnis gespeichert werden. Unter iOS legt der Import über UIDocumentPickerViewController bei Verwendung des Parameters asCopy: true automatisch eine Kopie der Datei in Documents ab. Unter Android erstellt der Import über den SAF-Dialog ebenfalls eine Kopie der Datei in der App-Sandbox. Beim Exportieren von Daten (z.B. Erstellen einer CSV-Datei mit Kontakten) speichern Sie die Datei zunächst in Documents/filesDir und bieten dem Benutzer dann an, sie über das Share Sheet zu teilen. Dies stellt sicher, dass selbst wenn der Benutzer vergisst, die Datei nach dem Senden zu speichern, eine Kopie in der App für die spätere Verwendung verbleibt.

Arbeiten mit dem Dokumentenverzeichnis unter Android

Unter Android übernimmt context.filesDir die Funktion des Dokumentenverzeichnisses. Zusätzlich ist das Verzeichnis context.externalFilesDir auf der SD-Karte verfügbar, garantiert aber nicht die Datenintegrität. Sehen wir uns die wichtigsten Techniken für die Arbeit mit diesen Verzeichnissen an.

Zugriff auf und Verwaltung von Dateien über filesDir

filesDir ist das Hauptverzeichnis für dauerhafte App-Dateien unter Android. Es befindet sich in der App-Sandbox und wird bei der Deinstallation vollständig gelöscht. Um eine File-Instanz zu erhalten, verwenden Sie context.filesDir, das den Pfad zu /data/data/<package>/files/ zurückgibt. Zum Erstellen und Lesen von Dateien verwenden Sie standardmäßige Java/Kotlin File-Operationen oder die Context-Methoden openFileInput() und openFileOutput(), die einen Dateinamen entgegennehmen und FileInputStream/FileOutputStream zurückgeben. Die Methode openFileOutput() erstellt die Datei automatisch in filesDir, falls sie noch nicht existiert, und ermöglicht die Angabe des Zugriffsmodus: MODE_PRIVATE (nur aktuelle App), MODE_APPEND (anhängen) oder MODE_WORLD_READABLE (veraltet, nicht verwendet seit 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()
}

Speicherfunktionen unter Android 10+

Unter Android 10+ beeinflusst das Scoped Storage-Modell filesDir nicht — der vollständige Zugriff auf die eigene App-Sandbox bleibt erhalten. Alle Lese- und Schreiboperationen innerhalb von filesDir erfordern keine zusätzlichen Berechtigungen. Wenn Sie jedoch versuchen, auf Dateien einer anderen App über filesDir zuzugreifen, erhalten Sie eine Ausnahme. Zum Teilen von Dateien verwenden Sie FileProvider, der einen temporären Content-URI erstellt, um eine Datei an eine andere App zu übertragen. FileProvider wird in der AndroidManifest.xml über das <provider>-Tag deklariert und in einer XML-Pfaddatei konfiguriert. Dies ist der Standardmechanismus für die Dateiübertragung zwischen Apps, der beispielsweise beim Senden eines Bildes über Intent mit ACTION_SEND verwendet wird.

Arbeiten mit dem Dokumentenverzeichnis unter iOS

Unter iOS ist das Documents Directory Teil des Sandbox-Containers der App mit einem besonderen Status. Dateien aus diesem Verzeichnis werden automatisch in das iCloud-Backup einbezogen, in der Files-App angezeigt und bei App-Updates über den App Store erhalten.

Dokumentenverzeichnis und Backup

Das automatische Backup von Documents ist ein wichtiger Vorteil von iOS. Wenn der Benutzer das Gerät mit iTunes verbindet oder iCloud Backup aktiviert, werden alle Dateien aus Documents/ in das Backup kopiert. Bei der Wiederherstellung auf einem neuen Gerät erhält der Benutzer alle seine Dateien ohne zusätzliche Schritte. Dieser Vorteil wird jedoch zum Nachteil, wenn die App große Datenmengen in Documents speichert: Die Backup-Zeit verlängert sich und der iCloud-Speicher kann schnell aufgebraucht sein. Daher sollten in Documents nur Dateien gespeichert werden, die der Benutzer bei der Wiederherstellung wirklich benötigt. Temporäre Dateien, Cache und neu erstellbare Daten sollten in Caches oder Library/Application Support abgelegt werden. Apple empfiehlt, Dateien, die aus dem Internet erneut heruntergeladen werden können, über das Attribut isExcludedFromBackup vom Backup auszuschließen.

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

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

iCloud Drive und geräteübergreifende Synchronisation

iCloud Drive ermöglicht die Synchronisation von Dateien aus Documents zwischen den Geräten eines Benutzers. Um die Synchronisation zu aktivieren, sollte die App die NSDocument- oder UIDocument-APIs verwenden, die automatisch die Versionierung und Konfliktlösung verwalten. Ein alternativer Ansatz ist die Verwendung von iCloud mit CloudKit, das eine flexiblere Kontrolle über die Synchronisation bietet, aber eine Konfiguration im CloudKit Dashboard erfordert. Bei Verwendung von iCloud Drive stellen Sie sicher, dass Sie Bearbeitungskonflikte korrekt behandeln (Merge oder Last-Write-Wins) und den Benutzer über den Synchronisationsstatus über die App-Oberfläche informieren. iCloud garantiert keine sofortige Synchronisation — die Verzögerung kann je nach Dateigröße und Verbindungsqualität zwischen einigen Sekunden und mehreren Minuten liegen. Verwenden Sie für kritische Daten transaktionales Schreiben und Versionierung, damit bei einem Konflikt die vorherige Version der Datei wiederhergestellt werden kann.

Unterschiede zum Cache-Verzeichnis und Best Practices

Die richtige Wahl zwischen Documents Directory und Cache Directory bestimmt die Zuverlässigkeit der Benutzerdatenspeicherung. Ein Fehler bei der Wahl führt entweder zu Datenverlust (wenn wichtige Dateien im Cache gespeichert werden) oder zu Backup-Überlauf (wenn temporäre Dateien in Documents gespeichert werden).

Die Best Practices für die Verwendung des Dokumentenverzeichnisses umfassen mehrere Schlüsselregeln. Erstens: Fragen Sie immer die Bestätigung des Benutzers an, bevor Sie Dateien aus diesem Verzeichnis löschen. Im Gegensatz zum Cache kann das Löschen eines Dokuments zu einem irreversiblen Verlust von Benutzerinhalten führen. Zweitens: Implementieren Sie Dateiversionierung: Wenn Sie eine vorhandene Datei überschreiben, speichern Sie die vorherige Version mit dem Suffix _backup oder verwenden Sie Snapshot-Mechanismen. Drittens: Stellen Sie dem Benutzer eine Oberfläche zum Anzeigen, Umbenennen, Löschen und Exportieren von Dateien aus dem Dokumentenverzeichnis zur Verfügung. Unter iOS werden Dateien aus Documents automatisch in Files angezeigt; unter Android müssen Sie einen eigenen Dateimanager implementieren oder Bibliotheken von Drittanbietern verwenden.

Legen Sie besonderes Augenmerk auf die Datenmigration bei App-Updates. Wenn die neue Version die Dateispeicherstruktur ändert (z.B. Daten von einem Unterverzeichnis in ein anderes verschiebt oder das Dateiformat ändert), implementieren Sie eine einmalige Migration beim ersten Start nach dem Update. Speichern Sie die Versionsnummer des Datenschemas in SharedPreferences und führen Sie die Migration durch, wenn sie nicht übereinstimmen. Löschen Sie alte Dateien nicht vor Abschluss der Migration — im Falle eines Fehlers sollte der Benutzer keine Daten verlieren. Wenn die Migration eine Formatkonvertierung beinhaltet (z.B. Wechsel von JSON zu SQLite), speichern Sie die Originaldateien als Backup in einem separaten Verzeichnis mit dem Migrationsdatum. Der Benutzer sollte in der Lage sein, die Änderungen über die App-Einstellungen innerhalb der ersten 30 Tage nach dem Update rückgängig zu machen, wie von den Apple Human Interface Guidelines empfohlen.