Documentenmap in de mobiele app — wat is het, doel en hoe opslag te organiseren

Wat is de documentenmap van de app?

De documentenmap is een gespecialiseerde opslagruimte in de sandbox van de app, bedoeld voor permanente opslag van gebruikersbestanden. In tegenstelling tot de cache worden bestanden in deze map als belangrijk voor de gebruiker beschouwd: ze worden niet door het systeem verwijderd bij ruimtegebrek, blijven behouden bij app-updates en worden geback-upt bij apparaatsynchronisatie. Op iOS maakt de Documents-map deel uit van de Sandbox-container en wordt automatisch opgenomen in iCloud-back-up. Op Android is er geen direct equivalent — context.filesDir dient als equivalent, ook bedoeld voor permanente bestanden, maar zonder ingebouwd back-upmechanisme.

Het verschil tussen de documentenmap en interne opslag (Internal Storage) op Android is minimaal: beide bevinden zich in de sandbox van de app, beide worden verwijderd bij deïnstallatie, beide zijn ontoegankelijk voor andere apps. Het belangrijkste verschil is semantisch: Documents Directory veronderstelt dat bestanden door de gebruiker zijn gemaakt of geïmporteerd, terwijl Internal Storage interne app-bestanden (databases, configuraties) kan bevatten. Op iOS is het verschil significanter: Documents wordt automatisch geback-upt, maar Library/Application Support niet. Dit beïnvloedt de opslagstrategie: plaats in Documents alleen wat de gebruiker wil herstellen op een nieuw apparaat, en in Application Support — interne gegevens die de app kan herbouwen.

De sandbox-architectuur garandeert dat andere apps geen toegang hebben tot de documentenmap van uw app. Op iOS is toegang tot Documents van andere apps onmogelijk zonder jailbreak. Op Android maakt root-toegang het mogelijk om filesDir van elke app te lezen, daarom moeten vertrouwelijke gegevens (tokens, coderingssleutels) extra worden beschermd met EncryptedSharedPreferences of EncryptedFile uit de AndroidX Security-bibliotheek.

Welke gegevens worden opgeslagen in de documentenmap

In de documentenmap moeten gegevens worden geplaatst die waardevol zijn voor de gebruiker en beschikbaar moeten zijn na het herstarten van de app of het herstellen van het apparaat. Niet alle bestanden zijn geschikt voor opslag in deze map — de keuze hangt af van het gegevenstype en het gebruiksscenario.

Gebruikersdocumenten en bestanden

Gebruikersbestanden — de hoofdinhoud van de documentenmap. Dit kunnen tekstdocumenten zijn die in een editor zijn gemaakt, afbeeldingen gemaakt met de camera van de app, geëxporteerde PDF-rapporten, audio-opnamen, notities. Elk dergelijk bestand is door de gebruiker of op zijn verzoek gemaakt en moet op elk moment beschikbaar zijn. Op iOS worden bestanden uit Documents weergegeven in de systeemapp Files, waardoor de gebruiker ze kan beheren via de standaard bestandsbeheerder. Op Android is er geen vergelijkbare weergave — de app moet zelf een interface bieden voor het bekijken van opgeslagen bestanden.

Databases en app-instellingen

SQLite-databases en instellingenbestanden worden meestal naast de documentenmap opgeslagen, maar niet erin. Op iOS worden databases in Library/Application Support geplaatst, omdat ze niet in de Files-app mogen worden weergegeven en apart geback-upt moeten worden. Op Android worden databases standaard aangemaakt in /data/data/<package>/databases/ via Room of SQLiteOpenHelper. Als de database gebruikersinhoud bevat (notities, dagboek, financiële gegevens), kan deze in filesDir worden geplaatst om back-up via het systeem te garanderen. Room maakt het mogelijk om een aangepaste map voor databaseopslag op te geven via de RoomDatabase.Builder-callback.

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

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

Geëxporteerde en geïmporteerde gegevens

Bestanden die de gebruiker uit andere apps importeert of exporteert uit uw app, moeten ook in de documentenmap worden opgeslagen. Op iOS plaatst importeren via UIDocumentPickerViewController automatisch een kopie van het bestand in Documents bij gebruik van de parameter asCopy: true. Op Android maakt importeren via het SAF-dialoogvenster ook een kopie van het bestand in de sandbox van de app. Bij het exporteren van gegevens (bijvoorbeeld het maken van een CSV-bestand met contacten), sla het bestand eerst op in Documents/filesDir en bied de gebruiker vervolgens aan om het te delen via Share Sheet. Dit garandeert dat, zelfs als de gebruiker vergeet het bestand op te slaan na verzending, de kopie in de app blijft voor later gebruik.

Werken met de documentenmap op Android

Op Android vervult context.filesDir de functies van de documentenmap. Daarnaast is de map context.externalFilesDir op de SD-kaart beschikbaar, maar deze garandeert geen gegevensbehoud. Laten we de belangrijkste werkwijzen met deze mappen bekijken.

Toegang en beheer van bestanden via filesDir

filesDir — de hoofdmap voor permanente app-bestanden op Android. Het bevindt zich in de sandbox van de app en wordt volledig verwijderd bij deïnstallatie. Gebruik context.filesDir om een File-instantie te krijgen, die het pad naar de map /data/data/<package>/files/ retourneert. Gebruik voor het maken en lezen van bestanden standaard File-bewerkingen in Java/Kotlin of de Context-methoden openFileInput() en openFileOutput(), die de bestandsnaam accepteren en FileInputStream/FileOutputStream retourneren. De methode openFileOutput() maakt automatisch het bestand in filesDir aan als het nog niet bestaat en maakt het mogelijk om de toegangsmodus op te geven: MODE_PRIVATE (alleen huidige app), MODE_APPEND (toevoegen) of MODE_WORLD_READABLE (verouderd, niet gebruikt sinds 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()
}

Opslagkenmerken op Android 10+

Op Android 10+ heeft het Scoped Storage-model geen invloed op filesDir — de toegang tot de eigen sandbox van de app blijft volledig. Alle lees- en schrijfbewerkingen in filesDir vereisen geen extra machtigingen. Bij een poging tot toegang tot bestanden van een andere app via filesDir krijgt u echter een uitzondering. Gebruik FileProvider voor bestandsuitwisseling, die een tijdelijk content-URI maakt om het bestand naar een andere app te verzenden. FileProvider wordt gedeclareerd in AndroidManifest.xml via de tag <provider> en geconfigureerd in het XML-padenbestand. Dit is het standaardmechanisme voor bestandsoverdracht tussen apps, gebruikt bijvoorbeeld bij het verzenden van een afbeelding via Intent met ACTION_SEND.

Werken met de documentenmap op iOS

Op iOS maakt Documents Directory deel uit van de Sandbox-container van de app met een speciale status. Bestanden uit deze map worden automatisch opgenomen in iCloud-back-up, weergegeven in de Files-app en behouden bij app-updates via de App Store.

Documents Directory en back-up

Automatische back-up van Documents — het belangrijkste voordeel van iOS. Wanneer de gebruiker het apparaat aansluit op iTunes of iCloud Backup inschakelt, worden alle bestanden uit Documents/ naar de back-up gekopieerd. Bij herstel op een nieuw apparaat ontvangt de gebruiker al zijn bestanden zonder extra handelingen. Dit voordeel wordt echter een nadeel als de app grote hoeveelheden gegevens in Documents opslaat: de back-uptijd neemt toe en de iCloud-opslag kan snel vol raken. Daarom moeten in Documents alleen bestanden worden opgeslagen die de gebruiker echt nodig heeft bij herstel. Tijdelijke bestanden, cache en herbruikbare gegevens moeten in Caches of Library/Application Support worden geplaatst. Apple raadt aan om bestanden die opnieuw van internet kunnen worden gedownload uit te sluiten van back-up via het kenmerk isExcludedFromBackup.

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

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

iCloud Drive en synchronisatie tussen apparaten

iCloud Drive maakt synchronisatie van bestanden uit Documents mogelijk tussen apparaten van dezelfde gebruiker. Voor het inschakelen van synchronisatie moet de app de API NSDocument of UIDocument gebruiken, die automatisch versiebeheer en conflictoplossing beheren. Een alternatieve benadering — het gebruik van iCloud met CloudKit, dat flexibelere controle over synchronisatie biedt, maar configuratie op CloudKit Dashboard vereist. Zorg bij gebruik van iCloud Drive dat u bewerkingsconflicten correct afhandelt (merge of last-write-wins) en de gebruiker informeert over de synchronisatiestatus via de app-interface. iCloud garandeert geen directe synchronisatie — de vertraging kan variëren van enkele seconden tot enkele minuten, afhankelijk van de bestandsgrootte en verbindingskwaliteit. Gebruik voor kritieke gegevens transactioneel schrijven en versiebeheer, zodat bij een conflict de vorige versie van het bestand kan worden hersteld.

Verschillen met Cache Directory en beste praktijken

De juiste keuze tussen Documents Directory en Cache Directory bepaalt de betrouwbaarheid van gebruikersgegevensopslag. Een fout in de keuze leidt ofwel tot gegevensverlies (als belangrijke bestanden in de cache worden opgeslagen) ofwel tot overvolle back-up (als tijdelijke bestanden in Documents worden opgeslagen).

Beste praktijken voor het gebruik van de documentenmap omvatten verschillende belangrijke regels. Vraag eerst altijd om bevestiging van de gebruiker voordat u bestanden uit deze map verwijdert. In tegenstelling tot de cache kan het verwijderen van een document leiden tot onomkeerbaar verlies van gebruikersinhoud. Implementeer ten tweede versiebeheer van bestanden: behoud bij het overschrijven van een bestaand bestand de vorige versie met het achtervoegsel _backup of gebruik Snapshot-mechanismen. Bied de gebruiker ten derde een interface voor het bekijken, hernoemen, verwijderen en exporteren van bestanden uit de documentenmap. Op iOS worden bestanden uit Documents automatisch weergegeven in Files, op Android moet u een eigen bestandsbeheerder implementeren of bibliotheken van derden gebruiken.

Besteed speciale aandacht aan gegevensmigratie bij het bijwerken van de app. Als de nieuwe versie de opslagstructuur van bestanden wijzigt (bijvoorbeeld gegevens van de ene submap naar de andere verplaatst of het bestandsformaat wijzigt), implementeer dan een eenmalige migratie bij de eerste start na de update. Bewaar het versienummer van het gegevensschema in SharedPreferences en start bij niet-overeenstemming de migratie. Verwijder oude bestanden niet tot de migratie is voltooid — bij een storing mag de gebruiker geen gegevens verliezen. Als de migratie formaatconversie omvat (bijvoorbeeld overgang van JSON naar SQLite), bewaar dan de originele bestanden als back-up in een aparte map met de migratiedatum. De gebruiker moet de mogelijkheid hebben om wijzigingen binnen 30 dagen na de update terug te draaien via de app-instellingen, zoals aanbevolen door Apple Human Interface Guidelines.