Documents Directory: wat is het, doel en toegang tot bestanden

Wat is Documents Directory in iOS?

Documents Directory — is een map in de sandbox van de iOS-app, bedoeld voor het opslaan van gebruikersgegevens die bewaard moeten blijven tussen starts en toegankelijk moeten zijn voor de gebruiker. Elke app krijgt zijn eigen geïsoleerde sandbox en Documents is een van de belangrijkste mappen naast Caches, tmp en Library.

iOS gebruikt een strikte sandbox: de app heeft geen toegang tot het bestandssysteem van andere apps en systeemmappen zonder speciale machtigingen. Documents Directory — de enige map waarvan de inhoud door de gebruiker kan worden bekeken via iTunes File Sharing (bij het inschakelen van de overeenkomstige sleutel UIFileSharingEnabled in Info.plist).

Volgens gegevens van Apple WWDC 2023 gebruikt meer dan 85% van de apps in de App Store Documents Directory voor het opslaan van ten minste één type gebruikersgegevens — van geëxporteerde PDF’s tot opgeslagen spelbestanden en geëxporteerde afbeeldingen.

De ontwikkelaar moet begrijpen: bestanden in Documents worden automatisch opgenomen in de iCloud- en iTunes-back-up. Als de app grote hoeveelheden gegevens in Documents opslaat die kunnen worden hersteld (bijvoorbeeld afbeeldingscache of tijdelijke bestanden), leidt dit tot onnodig ruimtegebruik in de iCloud-opslag van de gebruiker.

Hoe krijg je het pad naar Documents Directory

In Swift wordt het pad naar Documents Directory verkregen via FileManager. Apple raadt aan om URL-based API te gebruiken in plaats van string-based voor een betere compatibiliteit met moderne iOS-mogelijkheden.

import Foundation

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

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

Objective-C gebruikt NSSearchPathForDirectoriesInDomains — een oudere maar nog steeds ondersteunde benadering die een stringpad retourneert in plaats van een URL.

@import Foundation;

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

Moderne projecten in Swift moeten FileManager.urls gebruiken omdat deze methode een URL retourneert, geen string, wat het risico op fouten met padcodering vermindert en de code type-veiliger maakt.

Welke gegevens opslaan in Documents

Documents Directory is bedoeld voor gegevens die door de gebruiker zijn gemaakt of die de gebruiker in expliciete vorm nodig heeft. Apple onderscheidt verschillende categorieën die geschikt zijn voor deze map.

Gebruikersdocumenten en -bestanden

Bestanden die de gebruiker maakt of importeert — tekstdocumenten, PDF’s, afbeeldingen, geëxporteerde rapporten, back-upbestanden. Deze gegevens hebben directe waarde voor de gebruiker en het verlies ervan zou kritisch zijn.

Spelopslagen en applicatiestatus

Spelopslagen, applicatiestatusbestanden, geëxporteerde projecten — alles wat de gebruiker verwacht te herstellen na het opnieuw installeren van de app. Voor kritieke gegevens wordt echter aangeraden om ook iCloud Key-Value Storage of Core Data met iCloud-synchronisatie te gebruiken.

Het belangrijkste criterium: als gegevens uit het netwerk kunnen worden hersteld of opnieuw kunnen worden aangemaakt — hun plaats is in Caches, niet in Documents. Elke gigabyte in Documents is een gigabyte in de iCloud-back-up van de gebruiker.

Back-up en synchronisatie

iOS neemt de inhoud van Documents Directory automatisch op in de back-up bij het verbinden van het apparaat met iTunes of bij synchronisatie met iCloud. Dit gedrag kan niet op mapniveau worden uitgeschakeld — alleen bestand voor bestand via het kenmerk NSURLIsExcludedFromBackupKey.

Vanaf iOS 5.0 begon Apple apps af te wijzen die grote hoeveelheden te herstellen gegevens in Documents opslaan. Apple’s aanbeveling: bestanden die opnieuw kunnen worden gedownload, moeten in Caches Directory worden opgeslagen met een uitsluitingsvlag voor back-up.

import Foundation

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

// Sluit bestand uit van iCloud-back-up
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

iCloud-synchronisatie werkt via NSUbiquitousContainer als de app iCloud Documents gebruikt. In dat geval worden bestanden uit Documents Directory automatisch gesynchroniseerd tussen de apparaten van de gebruiker. Voor apps zonder iCloud blijft synchronisatie beperkt tot back-up.

Documents Directory vs Caches Directory

Het verschil tussen Documents en Caches — een van de meest voorkomende misvattingen onder beginnende iOS-ontwikkelaars. Het belangrijkste verschil: het systeem kan op elk moment bestanden uit Caches verwijderen om ruimte vrij te maken, maar raakt Documents nooit aan zonder medeweten van de gebruiker.

Volgens Apple Developer Documentation (2024) is oneigenlijk gebruik van Documents Directory — een van de veelvoorkomende redenen voor afwijzing van apps bij review: als de app meer dan enkele megabytes aan te herstellen gegevens in Documents opslaat, raadt Apple aan ze naar Caches te verplaatsen of NSURLIsExcludedFromBackupKey toe te passen.

Praktische regel: als de gebruiker verdrietig zal zijn bij het verlies van het bestand — bewaar in Documents. Als het bestand opnieuw kan worden gedownload of gegenereerd — bewaar in Caches.

Beste praktijken voor werken met Documents

Ervaren iOS-ontwikkelaars hebben verschillende regels opgesteld die helpen problemen met Documents Directory in alle fasen van de levenscyclus van de app te voorkomen — van ontwikkeling tot publicatie in de App Store.

Monitor de grootte van de map

Controleer regelmatig de grootte van Documents Directory via FileManager.enumerator(at:includingPropertiesForKeys:). Als de grootte 100 MB overschrijdt voor gegevens die geen gebruikersgegevens zijn — is dit een reden om de opslagarchitectuur te heroverwegen.

Sluit herbruikbare bestanden uit van back-up

Stel voor alle bestanden die opnieuw uit het netwerk kunnen worden gedownload isExcludedFromBackup = true in. Dit vermindert de belasting van de iCloud-opslag van de gebruiker en verlaagt het risico op afwijzing van de app door App Review.

Migreer bij update

Voorzie bij het wijzigen van het gegevensformaat in Documents een migratie: verwijder oude bestanden pas als je zeker weet dat nieuwe correct zijn aangemaakt. Gebruik versie-specifieke submappen.

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
)

Het naleven van deze praktijken vermindert het risico op verlies van gebruikersgegevens, verkleint de grootte van de iCloud-back-up en vergemakkelijkt het doorlopen van de review in de App Store.