Direktori Dokumen di Aplikasi Mobile — apa itu, tujuan dan cara mengatur penyimpanan

Apa itu direktori dokumen aplikasi?

Direktori dokumen — tempat penyimpanan khusus di dalam sandbox aplikasi, yang dirancang untuk penyimpanan permanen file pengguna. Tidak seperti cache, file dalam direktori ini dianggap penting bagi pengguna: tidak dihapus oleh sistem saat kekurangan ruang, dipertahankan saat pembaruan aplikasi, dan dicadangkan saat sinkronisasi perangkat. Di iOS, direktori Documents adalah bagian dari kontainer Sandbox dan secara otomatis disertakan dalam pencadangan iCloud. Di Android tidak ada padanan langsung — yang setara adalah context.filesDir, juga dirancang untuk file permanen, tetapi tidak memiliki mekanisme pencadangan bawaan.

Perbedaan antara direktori dokumen dan penyimpanan internal (Internal Storage) di Android minimal: keduanya berada di sandbox aplikasi, keduanya dihapus saat pencopotan pemasangan, keduanya tidak dapat diakses oleh aplikasi lain. Perbedaan utamanya bersifat semantik: Documents Directory mengasumsikan bahwa file dibuat atau diimpor oleh pengguna, sementara Internal Storage dapat berisi file internal aplikasi (database, konfigurasi). Di iOS perbedaannya lebih signifikan: Documents secara otomatis dicadangkan, sedangkan Library/Application Support tidak. Ini memengaruhi strategi penyimpanan: di Documents tempatkan hanya apa yang pengguna ingin pulihkan di perangkat baru, dan di Application Support — data internal yang dapat dibuat ulang oleh aplikasi.

Arsitektur sandbox memastikan bahwa aplikasi lain tidak memiliki akses ke direktori dokumen aplikasi Anda. Di iOS, akses ke Documents aplikasi lain tidak mungkin tanpa jailbreak. Di Android, akses root memungkinkan membaca filesDir aplikasi mana pun, oleh karena itu data rahasia (token, kunci enkripsi) harus dilindungi tambahan dengan EncryptedSharedPreferences atau EncryptedFile dari pustaka AndroidX Security.

Data apa yang disimpan di direktori dokumen

Di direktori dokumen harus ditempatkan data yang bernilai bagi pengguna dan harus tersedia setelah memulai ulang aplikasi atau memulihkan perangkat. Tidak semua file cocok untuk disimpan di direktori ini — pilihan tergantung pada jenis data dan skenario penggunaan.

Dokumen dan file pengguna

File pengguna — konten utama direktori dokumen. Ini bisa berupa dokumen teks yang dibuat di editor, gambar yang diambil dengan kamera aplikasi, laporan PDF yang diekspor, rekaman audio, catatan. Setiap file tersebut dibuat oleh pengguna atau atas permintaannya dan harus tersedia setiap saat. Di iOS, file dari Documents ditampilkan di aplikasi sistem Files, memungkinkan pengguna mengelolanya melalui pengelola file standar. Di Android tidak ada tampilan serupa — aplikasi harus menyediakan sendiri antarmuka untuk melihat file yang disimpan.

Database dan pengaturan aplikasi

Database SQLite dan file pengaturan biasanya disimpan di sebelah direktori dokumen, tetapi tidak di dalamnya. Di iOS, database ditempatkan di Library/Application Support, karena tidak boleh ditampilkan di aplikasi Files dan dicadangkan secara terpisah. Di Android, database secara default dibuat di /data/data/<package>/databases/ melalui Room atau SQLiteOpenHelper. Jika database berisi konten pengguna (catatan, buku harian, catatan keuangan), dapat ditempatkan di filesDir untuk memastikan pencadangan melalui sistem. Room memungkinkan menentukan direktori kustom untuk penyimpanan database melalui callback RoomDatabase.Builder.

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

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

Data yang diekspor dan diimpor

File yang diimpor pengguna dari aplikasi lain atau diekspor dari aplikasi Anda, juga harus disimpan di direktori dokumen. Di iOS, impor melalui UIDocumentPickerViewController secara otomatis menempatkan salinan file di Documents saat menggunakan parameter asCopy: true. Di Android, impor melalui dialog SAF juga membuat salinan file di sandbox aplikasi. Saat mengekspor data (misalnya, membuat file CSV dengan kontak), simpan file terlebih dahulu di Documents/filesDir, lalu tawarkan pengguna untuk membagikannya melalui Share Sheet. Ini memastikan bahwa bahkan jika pengguna lupa menyimpan file setelah dikirim, salinannya tetap ada di aplikasi untuk penggunaan selanjutnya.

Cara bekerja dengan direktori dokumen di Android

Di Android, fungsi direktori dokumen dilakukan oleh context.filesDir. Selain itu, direktori context.externalFilesDir tersedia di kartu SD, tetapi tidak menjamin keamanan data. Mari kita bahas cara utama bekerja dengan direktori ini.

Akses dan manajemen file melalui filesDir

filesDir — direktori utama untuk file permanen aplikasi di Android. Direktori ini berada di sandbox aplikasi dan sepenuhnya dihapus saat pencopotan pemasangan. Untuk mendapatkan instance File, gunakan context.filesDir, yang mengembalikan jalur ke direktori /data/data/<package>/files/. Untuk membuat dan membaca file, gunakan operasi File standar di Java/Kotlin atau metode Context openFileInput() dan openFileOutput(), yang menerima nama file dan mengembalikan FileInputStream/FileOutputStream. Metode openFileOutput() secara otomatis membuat file di filesDir jika belum ada dan memungkinkan menentukan mode akses: MODE_PRIVATE (hanya aplikasi saat ini), MODE_APPEND (menambahkan) atau MODE_WORLD_READABLE (usang, tidak digunakan sejak 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()
}

Karakteristik penyimpanan di Android 10+

Di Android 10+, model Scoped Storage tidak memengaruhi filesDir — akses ke sandbox aplikasi sendiri tetap penuh. Semua operasi baca dan tulis di dalam filesDir tidak memerlukan izin tambahan. Namun, saat mencoba mengakses file aplikasi lain melalui filesDir, Anda akan mendapatkan pengecualian. Untuk pertukaran file, gunakan FileProvider, yang membuat content URI sementara untuk mengirimkan file ke aplikasi lain. FileProvider dideklarasikan di AndroidManifest.xml melalui tag <provider> dan dikonfigurasi dalam file XML jalur. Ini adalah mekanisme standar untuk transfer file antar aplikasi, digunakan misalnya saat mengirim gambar melalui Intent dengan ACTION_SEND.

Cara bekerja dengan direktori dokumen di iOS

Di iOS, Documents Directory adalah bagian dari kontainer Sandbox aplikasi dengan status khusus. File dari direktori ini secara otomatis disertakan dalam pencadangan iCloud, ditampilkan di aplikasi Files, dan dipertahankan saat pembaruan aplikasi melalui App Store.

Documents Directory dan pencadangan

Pencadangan otomatis Documents — keuntungan utama iOS. Saat pengguna menghubungkan perangkat ke iTunes atau mengaktifkan iCloud Backup, semua file dari Documents/ disalin ke cadangan. Saat memulihkan di perangkat baru, pengguna menerima semua file mereka tanpa tindakan tambahan. Namun, keuntungan ini menjadi kerugian jika aplikasi menyimpan data dalam jumlah besar di Documents: waktu pencadangan meningkat dan ruang iCloud bisa cepat habis. Oleh karena itu, di Documents hanya boleh menyimpan file yang benar-benar diperlukan pengguna saat pemulihan. File sementara, cache, dan data yang dapat dibuat ulang harus berada di Caches atau Library/Application Support. Apple merekomendasikan untuk mengecualikan dari pencadangan file yang dapat diunduh ulang dari internet, melalui atribut isExcludedFromBackup.

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

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

iCloud Drive dan sinkronisasi antar perangkat

iCloud Drive memungkinkan sinkronisasi file dari Documents antar perangkat pengguna yang sama. Untuk mengaktifkan sinkronisasi, aplikasi harus menggunakan API NSDocument atau UIDocument, yang secara otomatis mengelola versioning dan penyelesaian konflik. Pendekatan alternatif — menggunakan iCloud dengan CloudKit, yang memberikan kontrol lebih fleksibel atas sinkronisasi, tetapi memerlukan konfigurasi di CloudKit Dashboard. Saat menggunakan iCloud Drive, pastikan Anda menangani konflik pengeditan dengan benar (merge atau last-write-wins) dan memberi tahu pengguna tentang status sinkronisasi melalui antarmuka aplikasi. iCloud tidak menjamin sinkronisasi instan — penundaan bisa berkisar dari beberapa detik hingga beberapa menit tergantung pada ukuran file dan kualitas koneksi. Untuk data yang sangat penting, gunakan penulisan transaksional dan versioning, sehingga jika terjadi konflik, versi file sebelumnya dapat dipulihkan.

Perbedaan dari Cache Directory dan praktik terbaik

Pilihan yang tepat antara Documents Directory dan Cache Directory menentukan keandalan penyimpanan data pengguna. Kesalahan dalam pemilihan menyebabkan hilangnya data (jika file penting disimpan di cache) atau kelebihan cadangan (jika file sementara disimpan di Documents).

Praktik terbaik penggunaan direktori dokumen mencakup beberapa aturan kunci. Pertama, selalu minta konfirmasi pengguna sebelum menghapus file dari direktori ini. Tidak seperti cache, penghapusan dokumen dapat menyebabkan hilangnya konten pengguna yang tidak dapat dipulihkan. Kedua, implementasikan versioning file: saat menimpa file yang ada, simpan versi sebelumnya dengan akhiran _backup atau gunakan mekanisme Snapshot. Ketiga, berikan pengguna antarmuka untuk melihat, mengganti nama, menghapus, dan mengekspor file dari direktori dokumen. Di iOS, file dari Documents secara otomatis ditampilkan di Files, di Android perlu mengimplementasikan pengelola file sendiri atau menggunakan pustaka pihak ketiga.

Berikan perhatian khusus pada migrasi data saat pembaruan aplikasi. Jika versi baru mengubah struktur penyimpanan file (misalnya, memindahkan data dari satu subdirektori ke subdirektori lain atau mengubah format file), implementasikan migrasi satu kali pada peluncuran pertama setelah pembaruan. Simpan nomor versi skema data di SharedPreferences dan jika tidak cocok, jalankan migrasi. Jangan hapus file lama sampai migrasi selesai — jika terjadi kegagalan, pengguna tidak boleh kehilangan data. Jika migrasi mencakup konversi format (misalnya, peralihan dari JSON ke SQLite), simpan file asli sebagai cadangan di direktori terpisah dengan tanggal migrasi. Pengguna harus dapat memutar kembali perubahan melalui pengaturan aplikasi dalam 30 hari pertama setelah pembaruan, seperti yang direkomendasikan oleh Apple Human Interface Guidelines.