Storage Access Framework: apa itu, prinsip kerja dan akses ke file

Apa itu Storage Access Framework?

Storage Access Framework — adalah bagian dari Android SDK yang menyediakan antarmuka terpadu untuk memilih dan membuat dokumen melalui dialog sistem. SAF mengabstraksi lokasi fisik file: aplikasi tidak tahu dari mana file dibaca — dari disk lokal, Google Drive, atau Dropbox.

Arsitektur SAF mencakup tiga komponen: aplikasi klien yang memulai permintaan, pemilih sistem — dialog standar pemilihan file, dan DocumentProvider — penyedia konten yang mengimplementasikan akses ke file dari penyimpanan tertentu. Pengguna melihat antarmuka terpadu terlepas dari sumber data.

SAF tersedia mulai Android 4.4 (API 19). Awalnya framework hanya mendukung dokumen, tetapi di Android 5.0 dukungan untuk direktori ditambahkan melalui ACTION_OPEN_DOCUMENT_TREE. Sejak Android 10, SAF menjadi cara yang direkomendasikan untuk mengakses file apa pun di luar app-specific storage.

Cara kerja SAF: pemilih sistem dan URI

SAF meluncurkan dialog sistem pemilihan file melalui Intent dengan tindakan ACTION_OPEN_DOCUMENT. Pengguna melihat daftar sumber yang tersedia: penyimpanan internal, Google Drive, Dropbox, dan penyedia terdaftar lainnya. Setelah memilih file, sistem mengembalikan content URI dengan hak akses sementara.

Content URI memiliki format content://com.android.externalstorage.documents/document/primary/Download/file.pdf. Berbeda dengan URI file://, content URI tidak mengungkapkan jalur sebenarnya ke file dan bekerja melalui DocumentProvider. Aplikasi membaca file melalui ContentResolver.openInputStream berdasarkan URI yang diperoleh.

Pemilih sistem secara otomatis mendukung pencarian, pengurutan, dan pemfilteran file berdasarkan tipe MIME. Pengembang menentukan tipe yang diperlukan melalui Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")), dan pemilih hanya menampilkan file yang relevan.

Siklus hidup URI akses

Secara default, URI berlaku hingga restart aplikasi atau reboot perangkat. Untuk akses jangka panjang, aplikasi meminta takePersistableUriPermission — ini memungkinkan membaca file pada startup berikutnya tanpa memilih ulang melalui dialog.

ACTION_OPEN_DOCUMENT dan ACTION_CREATE_DOCUMENT

SAF menyediakan tiga tindakan utama untuk bekerja dengan file: membuka, membuat, dan memilih pohon folder. ACTION_OPEN_DOCUMENT membuka pemilih sistem untuk memilih file yang sudah ada. ACTION_CREATE_DOCUMENT membuat file baru — pengguna memasukkan nama di dialog, dan aplikasi menerima URI untuk menulis.

ACTION_OPEN_DOCUMENT_TREE memungkinkan memilih seluruh direktori dan mendapatkan akses ke semua file di dalamnya. Ini digunakan di manajer file, aplikasi cadangan, dan sinkronisasi. Aplikasi menerima URI direktori dan dapat secara rekursif mendaftar konten melalui DocumentFile.

Untuk setiap tindakan, tipe MIME ditentukan melalui EXTRA_MIME_TYPES. Beberapa tipe dapat ditentukan: "application/pdf", "image/*", "text/plain". Jika tipe tidak ditentukan, pemilih menampilkan semua file.

Persistent URI permissions

Persistent URI permissions — mekanisme SAF yang memungkinkan mempertahankan akses ke file setelah sesi saat ini berakhir. Tanpa bendera ini, URI hanya berlaku hingga restart aplikasi. Aplikasi meminta bendera FLAG_GRANT_PERSISTABLE_URI_PERMISSION bersama dengan bendera READ dan WRITE.

Untuk menyimpan hak, metode ContentResolver.takePersistableUriPermission digunakan. Sistem menyimpan URI dalam registri khusus dan memulihkan akses saat aplikasi dijalankan berikutnya. Untuk memeriksa apakah aplikasi memiliki akses persisten ke URI, digunakan ContentResolver.persistedUriPermissions.

Pengguna dapat mencabut izin yang disimpan melalui Pengaturan → Aplikasi → Izin. Aplikasi harus menangani skenario ketika akses ke file tiba-tiba hilang. Disarankan untuk memeriksa akses melalui ContentResolver.openInputStream sebelum mulai bekerja dan menangani SecurityException dengan benar.

Contoh kode: memilih file melalui SAF

SAF diluncurkan melalui Intent standar. Kode minimal: buat Intent dengan ACTION_OPEN_DOCUMENT, tentukan tipe MIME, dan jalankan melalui ActivityResultContracts.StartActivityForResult. Setelah memilih file, callback menerima URI di data.data, yang kemudian digunakan untuk membaca.

val pickFile = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.data?.let { uri ->
        val inputStream = contentResolver?.openInputStream(uri)
        // read from inputStream
    }
}

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    setType("application/pdf")
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
}
pickFile.launch(intent)

Membuat file melalui ACTION_CREATE_DOCUMENT

Untuk menulis file baru, gunakan ACTION_CREATE_DOCUMENT. Intent menerima tipe MIME dan nama file melalui EXTRA_TITLE. Setelah memilih folder dan mengonfirmasi, pengguna mengembalikan URI tempat aplikasi menulis data melalui ContentResolver.openOutputStream. Sistem secara otomatis membuat file di lokasi yang dipilih.

SAF vs READ_EXTERNAL_STORAGE

SAF berbeda dari READ_EXTERNAL_STORAGE tradisional dengan pendekatan keamanan yang fundamental berbeda. Alih-alih meminta akses ke seluruh penyimpanan “sekaligus”, SAF hanya meminta akses ke file tertentu. Ini meminimalkan permukaan serangan dan meningkatkan kepercayaan pengguna.

READ_EXTERNAL_STORAGE memberikan akses ke semua file di perangkat, termasuk foto dan dokumen aplikasi lain. Di Android 10+ pendekatan ini dibatasi. SAF sebaliknya, hanya memberikan akses ke file yang dipilih pengguna dan memerlukan konfirmasi eksplisit untuk setiap file. Untuk kerja batch dengan media, gunakan MediaStore; untuk dokumen individual, gunakan SAF.

Kekurangan utama SAF adalah kebutuhan untuk memilih setiap file secara terpisah. Untuk operasi massal (cadangan, sinkronisasi folder), gunakan ACTION_OPEN_DOCUMENT_TREE yang memberikan akses ke semua file di direktori yang dipilih. Solusi tergantung pada skenario: SAF optimal untuk pemilihan oleh pengguna, MediaStore — untuk akses programatik ke media.