Documents Directory: apa itu, tujuan dan akses ke file

Apa itu Documents Directory di iOS?

Documents Directory — adalah direktori di dalam sandbox aplikasi iOS, ditujukan untuk menyimpan data pengguna yang harus dipertahankan antar peluncuran dan dapat diakses oleh pengguna. Setiap aplikasi mendapatkan sandbox terisolasi sendiri, dan Documents adalah salah satu direktori kunci bersama Caches, tmp, dan Library.

iOS menggunakan sandbox yang ketat: aplikasi tidak memiliki akses ke sistem file aplikasi lain dan direktori sistem tanpa izin khusus. Documents Directory — satu-satunya direktori yang kontennya dapat dilihat oleh pengguna melalui iTunes File Sharing (saat mengaktifkan kunci UIFileSharingEnabled yang sesuai di Info.plist).

Menurut data Apple WWDC 2023, lebih dari 85% aplikasi di App Store menggunakan Documents Directory untuk menyimpan setidaknya satu jenis data pengguna — dari PDF yang diekspor hingga file game yang disimpan dan gambar yang diekspor.

Pengembang harus memahami: file di Documents secara otomatis disertakan dalam pencadangan iCloud dan iTunes. Jika aplikasi menyimpan data dalam jumlah besar yang dapat dipulihkan di Documents (misalnya, cache gambar atau file sementara), ini akan menyebabkan penggunaan ruang penyimpanan iCloud pengguna yang tidak perlu.

Cara mendapatkan jalur ke Documents Directory

Di Swift, jalur ke Documents Directory diperoleh melalui FileManager. Apple merekomendasikan penggunaan API berbasis URL daripada berbasis string untuk kompatibilitas yang lebih baik dengan kemampuan iOS modern.

import Foundation

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

// Buat file di Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C menggunakan NSSearchPathForDirectoriesInDomains — pendekatan yang lebih lama namun masih didukung yang mengembalikan jalur string, bukan URL.

@import Foundation;

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

Proyek modern di Swift harus menggunakan FileManager.urls karena metode ini mengembalikan URL, bukan string, yang mengurangi risiko kesalahan pengkodean jalur dan membuat kode lebih aman secara tipe.

Data apa yang disimpan di Documents

Documents Directory ditujukan untuk data yang dibuat oleh pengguna atau diperlukan pengguna dalam bentuk eksplisit. Apple menyoroti beberapa kategori yang cocok untuk direktori ini.

Dokumen dan file pengguna

File yang dibuat atau diimpor pengguna — dokumen teks, PDF, gambar, laporan yang diekspor, file cadangan. Data ini memiliki nilai langsung bagi pengguna, dan kehilangannya akan sangat berarti.

Penyimpanan game dan status aplikasi

Simpanan game, file status aplikasi, proyek yang diekspor — semua yang diharapkan pengguna untuk dipulihkan setelah menginstal ulang aplikasi. Namun, untuk data penting, disarankan juga menggunakan iCloud Key-Value Storage atau Core Data dengan sinkronisasi iCloud.

Kriteria utama: jika data dapat dipulihkan dari jaringan atau dibuat ulang — tempatnya di Caches, bukan di Documents. Setiap gigabyte di Documents adalah gigabyte di cadangan iCloud pengguna.

Pencadangan dan sinkronisasi

iOS secara otomatis menyertakan konten Documents Directory dalam pencadangan saat perangkat terhubung ke iTunes atau saat sinkronisasi dengan iCloud. Perilaku ini tidak dapat dinonaktifkan di tingkat direktori — hanya per file melalui atribut NSURLIsExcludedFromBackupKey.

Mulai iOS 5.0, Apple mulai menolak aplikasi yang menyimpan data dalam jumlah besar yang dapat dipulihkan di Documents. Rekomendasi Apple: file yang dapat diunduh ulang harus disimpan di Caches Directory dengan flag pengecualian dari cadangan.

import Foundation

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

// Kecualikan file dari cadangan iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Sinkronisasi iCloud bekerja melalui NSUbiquitousContainer jika aplikasi menggunakan iCloud Documents. Dalam kasus ini, file dari Documents Directory secara otomatis disinkronkan antar perangkat pengguna. Untuk aplikasi tanpa iCloud, sinkronisasi terbatas pada pencadangan.

Documents Directory vs Caches Directory

Perbedaan antara Documents dan Caches — salah satu kesalahpahaman paling umum di kalangan pengembang iOS pemula. Perbedaan utama: sistem dapat kapan saja menghapus file dari Caches untuk membebaskan ruang, tetapi tidak pernah menyentuh Documents tanpa sepengetahuan pengguna.

Menurut Apple Developer Documentation (2024), penggunaan Documents Directory yang tidak tepat — salah satu alasan umum penolakan aplikasi saat review: jika aplikasi menyimpan lebih dari beberapa megabyte data yang dapat dipulihkan di Documents, Apple merekomendasikan untuk memindahkannya ke Caches atau menerapkan NSURLIsExcludedFromBackupKey.

Aturan praktis: jika pengguna akan sedih saat kehilangan file — simpan di Documents. Jika file dapat diunduh atau dibuat ulang — simpan di Caches.

Praktik terbaik bekerja dengan Documents

Pengembang iOS berpengalaman telah menyusun beberapa aturan yang membantu menghindari masalah dengan Documents Directory di semua tahap siklus hidup aplikasi — dari pengembangan hingga publikasi di App Store.

Memantau ukuran direktori

Secara teratur periksa ukuran Documents Directory melalui FileManager.enumerator(at:includingPropertiesForKeys:). Jika ukuran melebihi 100 MB untuk data yang bukan data pengguna — ini adalah alasan untuk mempertimbangkan kembali arsitektur penyimpanan.

Mengecualikan file yang dapat dipulihkan dari cadangan

Untuk semua file yang dapat diunduh ulang dari jaringan, atur isExcludedFromBackup = true. Ini mengurangi beban pada penyimpanan iCloud pengguna dan mengurangi risiko penolakan aplikasi oleh App Review.

Migrasi saat pembaruan

Saat mengubah format data di Documents, sediakan migrasi: jangan hapus file lama sampai Anda yakin file baru telah dibuat dengan benar. Gunakan subdirektori khusus versi.

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
)

Mematuhi praktik ini mengurangi risiko kehilangan data pengguna, memperkecil ukuran cadangan iCloud, dan memudahkan proses review di App Store.