Директоријум докумената у мобилној апликацији — шта је то, намена и како организовати складиштење

Шта је директоријум докумената апликације?

Директоријум докумената — специјализовано складиште унутар пешчаника апликације, намењено за стално чување корисничких датотека. За разлику од кеша, датотеке у овом директоријуму се сматрају важним за корисника: не бришу се од стране система при недостатку простора, чувају се при ажурирању апликације и бележе се при синхронизацији уређаја. На iOS-у, директоријум Documents је део Sandbox контејнера и аутоматски се укључује у резервну копију iCloud. На Android-у нема директног аналога — еквивалент је context.filesDir, који је такође намењен за сталне датотеке, али нема уграђени механизам резервног копирања.

Разлика између директоријума докумената и интерне меморије (Internal Storage) на Android-у је минимална: оба се налазе у пешчанику апликације, оба се бришу при деинсталацији, оба су недоступна другим апликацијама. Главна разлика је семантичка: Documents Directory претпоставља да су датотеке креиране или увезене од стране корисника, док Internal Storage може садржати интерне датотеке апликације (базе података, конфигурације). На iOS-у разлика је значајнија: Documents се аутоматски бележи, а Library/Application Support — не. Ово утиче на стратегију складиштења: у Documents постављајте само оно што корисник жели да обнови на новом уређају, а у Application Support — интерне податке које апликација може поново да креира.

Архитектура пешчаника гарантује да друге апликације немају приступ директоријуму докумената ваше апликације. На iOS-у приступ Documents другим апликацијама није могућ без jailbreak-а. На Android-у роот приступ омогућава читање filesDir било које апликације, зато поверљиве податке (токене, кључеве за шифровање) треба додатно заштитити помоћу EncryptedSharedPreferences или EncryptedFile из библиотеке AndroidX Security.

Који подаци се чувају у директоријуму докумената

У директоријум докумената треба сместити податке који представљају вредност за корисника и морају бити доступни након поновног покретања апликације или обнављања уређаја. Нису све датотеке погодне за чување у овом директоријуму — избор зависи од врсте података и сценарија коришћења.

Кориснички документи и датотеке

Корисничке датотеке — главни садржај директоријума докумената. То могу бити текстуални документи креирани у уређивачу, слике снимљене камером апликације, извезени PDF извештаји, аудио снимци, белешке. Свака таква датотека је креирана од стране корисника или по његовом захтеву и мора бити доступна у сваком тренутку. На iOS-у датотеке из Documents се приказују у системској апликацији Files, што омогућава кориснику да њима управља преко стандардног менаџера датотека. На Android-у не постоји слично приказивање — апликација мора сама да обезбеди интерфејс за преглед сачуваних датотека.

Базе података и подешавања апликације

SQLite базе података и датотеке подешавања обично се чувају поред директоријума докумената, али не у њему самом. На iOS-у базе података се постављају у Library/Application Support, јер не треба да се приказују у апликацији Files и да се засебно бележе. На Android-у базе података се подразумевано креирају у /data/data/<package>/databases/ преко Room-а или SQLiteOpenHelper-а. Ако база података садржи кориснички садржај (белешке, дневник, финансијске записе), може се поставити у filesDir да би се обезбедило резервно копирање кроз систем. Room омогућава одређивање прилагођеног директоријума за чување базе података преко callback-а RoomDatabase.Builder.

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

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

Извезени и увезени подаци

Датотеке које корисник увози из других апликација или извози из ваше апликације, такође треба чувати у директоријуму докумената. На iOS-у увоз преко UIDocumentPickerViewController-а аутоматски поставља копију датотеке у Documents када се користи параметар asCopy: true. На Android-у увоз кроз SAF дијалог такође креира копију датотеке у пешчанику апликације. При извозу података (на пример, креирање CSV датотеке са контактима), сачувајте датотеку прво у Documents/filesDir, а затим понудите кориснику да је подели преко Share Sheet-а. Ово гарантује да, чак и ако корисник заборави да сачува датотеку након слања, копија остаје у апликацији за касније коришћење.

Како радити са директоријумом докумената на Android-у

На Android-у функције директоријума докумената обавља context.filesDir. Додатно је доступан директоријум context.externalFilesDir на SD картици, али он не гарантује сигурност података. Размотримо основне технике рада са овим директоријумима.

Приступ и управљање датотекама кроз filesDir

filesDir — главни директоријум за сталне датотеке апликације на Android-у. Налази се у пешчанику апликације и потпуно се брише при деинсталацији. За добијање инстанце File користите context.filesDir, који враћа путању до директоријума /data/data/<package>/files/. За креирање и читање датотека користите стандардне File операције у Java/Kotlin-у или Context методе openFileInput() и openFileOutput(), које примају име датотеке и враћају FileInputStream/FileOutputStream. Метод openFileOutput() аутоматски креира датотеку у filesDir ако још не постоји и омогућава одређивање режима приступа: MODE_PRIVATE (само тренутна апликација), MODE_APPEND (дописивање) или MODE_WORLD_READABLE (застарело, не користи се од 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()
}

Карактеристике складиштења на Android 10+

На Android 10+ модел Scoped Storage не утиче на filesDir — приступ сопственом пешчанику апликације остаје потпун. Све операције читања и писања унутар filesDir не захтевају додатне дозволе. Међутим, при покушају приступа датотекама друге апликације кроз filesDir добићете изузетак. За размену датотека користите FileProvider, који креира привремени content URI за пренос датотеке другој апликацији. FileProvider се декларише у AndroidManifest.xml кроз ознаку <provider> и конфигурише се у XML датотеци путања. Ово је стандардни механизам за пренос датотека између апликација, који се користи, на пример, при слању слике кроз Intent са ACTION_SEND.

Како радити са директоријумом докумената на iOS-у

На iOS-у Documents Directory је део Sandbox контејнера апликације са посебним статусом. Датотеке из овог директоријума се аутоматски укључују у резервну копију iCloud, приказују се у апликацији Files и чувају се при ажурирању апликације кроз App Store.

Documents Directory и резервно копирање

Аутоматско резервно копирање Documents — кључна предност iOS-а. Када корисник повеже уређај са iTunes-ом или укључи iCloud Backup, све датотеке из Documents/ се копирају у резервну копију. При обнављању на новом уређају, корисник добија све своје датотеке без додатних радњи. Међутим, ова предност постаје недостатак ако апликација чува велике количине података у Documents-у: време резервног копирања се повећава, а простор на iCloud-у може брзо да се потроши. Зато у Documents-у треба чувати само оне датотеке које су кориснику заиста потребне при обнављању. Привремене датотеке, кеш и подаци који се могу поново креирати треба да буду у Caches или Library/Application Support. Apple препоручује изузимање из резервне копије датотека које се могу поново преузети са интернета, кроз атрибут isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Садржај белешке"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive и синхронизација између уређаја

iCloud Drive омогућава синхронизацију датотека из Documents-а између уређаја истог корисника. За укључивање синхронизације, апликација треба да користи API NSDocument или UIDocument, који аутоматски управљају верзионисањем и решавањем конфликата. Алтернативни приступ — коришћење iCloud-а са CloudKit-ом, који пружа флексибилнију контролу над синхронизацијом, али захтева подешавање на CloudKit Dashboard-у. При коришћењу iCloud Drive-а уверите се да правилно обрађујете конфликте уређивања (merge или last-write-wins) и да обавештавате корисника о стању синхронизације кроз интерфејс апликације. iCloud не гарантује тренутну синхронизацију — кашњење може бити од неколико секунди до неколико минута у зависности од величине датотеке и квалитета везе. За критично важне податке користите трансакцијско упис и верзионисање, тако да се при конфликту може обновити претходна верзија датотеке.

Разлике од Cache Directory и најбоље праксе

Правилан избор између Documents Directory и Cache Directory одређује поузданост чувања корисничких података. Грешка у избору доводи или до губитка података (ако се важне датотеке чувају у кешу) или до препуњавања резервне копије (ако се привремене датотеке чувају у Documents-у).

Најбоље праксе коришћења директоријума докумената укључују неколико кључних правила. Прво, увек тражите потврду корисника пре брисања датотека из овог директоријума. За разлику од кеша, брисање документа може довести до неповратног губитка корисничког садржаја. Друго, имплементирајте верзионисање датотека: при преписивању постојеће датотеке сачувајте претходну верзију са суфиксом _backup или користите Snapshot механизме. Треће, обезбедите кориснику интерфејс за преглед, преименовање, брисање и извоз датотека из директоријума докумената. На iOS-у датотеке из Documents-а се аутоматски приказују у Files-у, на Android-у је потребно имплементирати сопствени менаџер датотека или користити библиотеке трећих страна.

Посебну пажњу посветите миграцији података при ажурирању апликације. Ако нова верзија мења структуру чувања датотека (на пример, премешта податке из једног поддиректоријума у други или мења формат датотека), имплементирајте једнократну миграцију при првом покретању након ажурирања. Чувајте број верзије шеме података у SharedPreferences-у и при неусаглашености покрените миграцију. Немојте брисати старе датотеке до завршетка миграције — у случају квара корисник не сме да изгуби податке. Ако миграција укључује конверзију формата (на пример, прелазак са JSON-а на SQLite), сачувајте оригиналне датотеке као резервну копију у засебном директоријуму са датумом миграције. Корисник треба да има могућност да врати промене кроз подешавања апликације у првих 30 дана након ажурирања, како препоручује Apple Human Interface Guidelines.