Info.plist Usage Description — apa itu, kunci NS*UsageDescription dan pengaturan

Apa itu Info.plist Usage Description?

Info.plist Usage Description — adalah nilai string dari kunci dengan awalan NS*UsageDescription yang menentukan teks dialog sistem saat meminta akses ke sumber daya iOS yang dilindungi. Ketika aplikasi pertama kali memanggil API yang memerlukan izin pengguna (misalnya AVCaptureDevice untuk kamera), iOS menampilkan dialog dengan teks ini dan tombol izin atau penolakan.

Teks deskripsi adalah satu-satunya hal yang dapat dikontrol pengembang dalam dialog sistem. Judul dialog "Aplikasi ingin mendapatkan akses ke [sumber daya]" dihasilkan secara otomatis oleh iOS berdasarkan jenis sumber daya yang diminta. Pengembang tidak dapat mengubah judul, tombol, atau tampilan — hanya teks penjelasan.

Usage Description terkait erat dengan model runtime permissions di iOS. Pengguna memberikan izin untuk satu permintaan, yang dapat dicabut nanti melalui Pengaturan. Saat permintaan ulang, dialog tidak ditampilkan — aplikasi harus memeriksa status izin dan bereaksi sesuai.

Apple sangat merekomendasikan untuk menyebutkan alasan spesifik permintaan akses dalam deskripsi. Misalnya, "Untuk mengambil foto profil" lebih baik daripada "Untuk akses ke kamera". Teks spesifik meningkatkan kepercayaan pengguna dan persentase izin yang diberikan. Menurut data Localytics (2023), deskripsi kustom meningkatkan persetujuan sebesar 15-25% dibandingkan dengan formulasi umum.

Perbedaan antara Usage Description dan ATT

Jangan bingung NS*UsageDescription dengan ATT (App Tracking Transparency). Usage Description adalah permintaan akses ke sumber daya sistem (kamera, geolokasi, foto), sedangkan ATT adalah permintaan pelacakan (akses ke IDFA). ATT menggunakan framework terpisah AppTrackingTransparency dan kunci NSUserTrackingUsageDescription, yang tidak termasuk dalam NS*UsageDescription.

Kesamaan mereka adalah keduanya menggunakan dialog sistem dengan teks yang tidak dapat dimodifikasi aplikasi. Perbedaannya adalah Usage Description bekerja pada tingkat sumber daya, sedangkan ATT pada tingkat pengenal perangkat. Kunci NS*UsageDescription diperkenalkan di iOS 6, ATT — di iOS 14.5.

Evolusi kunci di berbagai versi iOS

Dengan setiap rilis iOS, Apple menambahkan sumber daya yang dilindungi baru dan kunci yang sesuai. iOS 6: kontak, kalender, pengingat, foto. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: perpustakaan media, Siri. iOS 11: NFC. iOS 14: pelacakan (ATT). iOS 17: akses ke clipboard (memerlukan konfirmasi tambahan).

Penting: jika aplikasi menggunakan API yang diperkenalkan di versi iOS tertentu, tetapi versi minimum yang didukung lebih rendah, kunci tetap wajib. iOS memeriksa keberadaan kunci sebelum panggilan API pertama, terlepas dari versi tempat aplikasi berjalan.

Kunci NS*UsageDescription mana yang wajib

Daftar lengkap kunci tergantung pada fungsi apa yang digunakan aplikasi. Mari kita lihat 14 kunci utama yang paling sering diperlukan dalam aplikasi seluler.

Akses ke multimedia

Kunci NSCameraUsageDescription — wajib saat mengakses kamera melalui AVCaptureDevice atau UIImagePickerController dengan sumber .camera. Kunci NSMicrophoneUsageDescription — saat merekam audio melalui AVAudioRecorder atau merekam video dengan suara. Kedua kunci sering diperlukan bersama jika aplikasi merekam video.

Kunci NSPhotoLibraryUsageDescription — saat membaca foto dan video dari perpustakaan media pengguna melalui PHPicker atau UIImagePickerController. Kunci NSPhotoLibraryAddUsageDescription — jika aplikasi hanya menyimpan foto tetapi tidak membacanya. Yang pertama meminta akses baca, yang kedua — hanya akses tulis.

Geolokasi dan navigasi

Kunci NSLocationWhenInUseUsageDescription — akses ke geolokasi saat aplikasi aktif (di layar). NSLocationAlwaysAndWhenInUseUsageDescription — akses selalu (termasuk latar belakang). iOS memerlukan kedua kunci jika akses selalu diperlukan: pertama WhenInUse, lalu Always.

Kunci NSLocationTemporaryUsageDescription dan NSLocationPreciseUsageDescription — kunci tambahan untuk meminta akses sementara atau geolokasi yang tepat. Lokasi tepat memerlukan izin terpisah, dan pengguna hanya dapat mengaktifkan perkiraan.

Kontak, kalender, dan data lainnya

Kunci NSContactsUsageDescription — akses ke kontak pengguna melalui CNContactStore. NSCalendarsUsageDescription — akses ke kalender untuk membaca dan membuat acara. NSRemindersUsageDescription — akses ke pengingat. NSBluetoothAlwaysUsageDescription — akses ke Bluetooth di latar belakang (misalnya untuk perangkat BLE).

Kunci NSHealthShareUsageDescription — akses untuk membaca data HealthKit. NSHealthUpdateUsageDescription — akses untuk menulis data ke HealthKit. Keduanya wajib jika aplikasi bekerja di bidang kesehatan. Apple dengan cermat memeriksa aplikasi yang menggunakan HealthKit dan dapat menolak jika deskripsi penggunaan tidak sesuai dengan fungsionalitas.

Cara merumuskan deskripsi yang benar

Teks dalam Usage Description harus spesifik, jujur, dan ringkas. Apple memberikan rekomendasi untuk formulasi, dan moderator memeriksa kesesuaiannya dengan fungsionalitas.

Struktur deskripsi yang baik

Deskripsi yang baik terdiri dari tiga bagian: apa yang sebenarnya dilakukan aplikasi dengan sumber daya, mengapa pengguna membutuhkannya, dan manfaat apa bagi pengguna dari memberikan akses. Contoh: "Untuk mengambil foto profil dan mengunggahnya ke formulir". Hindari frasa umum: "Untuk meningkatkan kinerja aplikasi" tidak menjelaskan mengapa kamera diperlukan.

Apple melarang deskripsi yang menyesatkan. Jika tertulis "Untuk mengambil foto" tetapi aplikasi juga merekam video, ini dapat dianggap menipu. Moderator dapat menolak aplikasi atau meminta klarifikasi. Di iOS 17, Apple menambahkan pemeriksaan otomatis: deskripsi harus mengandung kata kunci yang sesuai dengan sumber daya yang diminta.

Lokalisasi: deskripsi harus diterjemahkan ke semua bahasa yang didukung aplikasi. Jika aplikasi tersedia dalam 10 bahasa, setiap kunci Usage Description harus memiliki terjemahan dalam file Localizable.strings atau InfoPlist.strings. Apple merekomendasikan penggunaan InfoPlist.strings untuk lokalisasi kunci Info.plist.

Contoh buruk dan baik

• Buruk: "Akses ke kamera diperlukan" — tidak menjelaskan mengapa
• Baik: "Untuk memindai kode QR saat pembayaran" — spesifik dan jelas
• Buruk: "Untuk menentukan lokasi" — tidak jelas
• Baik: "Untuk menemukan restoran terdekat di peta" — menunjukkan nilai
• Buruk: "Untuk meningkatkan layanan" — tidak informatif
• Baik: "Untuk mengunggah foto dalam ulasan produk" — tindakan spesifik

Lokalisasi melalui InfoPlist.strings

Untuk lokalisasi Usage Description, tidak perlu menggandakan Info.plist untuk setiap bahasa. Buat file InfoPlist.strings di setiap direktori bahasa dan tentukan nilai kunci. iOS secara otomatis menggunakan bahasa yang sesuai dalam dialog. Xcode mendukung lokalisasi dasar untuk Info.plist mulai versi 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Untuk memindai kode QR";
"NSPhotoLibraryUsageDescription" =
    "Untuk mengunggah gambar ke profil";
"NSLocationWhenInUseUsageDescription" =
    "Untuk menampilkan toko terdekat di peta";

Implementasi: kode dan pengaturan

Implementasi yang benar dari Usage Description mencakup penambahan kunci ke Info.plist, pemeriksaan status izin dalam kode, dan penanganan penolakan.

Menambahkan kunci melalui Xcode

Di Xcode buka Info.plist, arahkan kursor ke baris dan klik "+". Masukkan nama kunci (misalnya NSCameraUsageDescription) dan tentukan string deskripsi. Xcode melengkapi nama kunci secara otomatis, mengurangi risiko kesalahan ketik. Setelah menambahkan, bangun ulang proyek dan periksa apakah kunci muncul di file biner akhir.

Penting: kunci bersifat case-sensitive. NSCameraUsageDescription — benar, NSCamerausagedescription — salah. Kunci yang salah diabaikan, dan aplikasi akan crash saat memanggil API. Gunakan salinan dari dokumentasi Apple atau pelengkapan otomatis Xcode untuk menghindari kesalahan ketik.

import AVFoundation
import Photos

final class PermissionManager {
    static func checkCameraPermission() {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        switch status {
        case .notDetermined:
            AVCaptureDevice.requestAccess(for: .video) { granted in
                print("Camera access: \(granted)")
            }
        case .denied:
            print("Camera access denied")
        case .authorized:
            print("Camera access authorized")
        @unknown default:
            break
        }
    }

    static func requestPhotoLibraryAccess() {
        PHPhotoLibrary.requestAuthorization { status in
            print("Photo library status: \(status.rawValue)")
        }
    }
}

Menangani penolakan akses

Jika pengguna menolak akses, aplikasi tidak boleh memanggil ulang dialog sistem — ini tidak mungkin. Sebagai gantinya, tampilkan layar informasi dengan penjelasan cara mengaktifkan akses melalui Pengaturan dan tombol "Buka pengaturan" (UIApplicationOpenSettingsURLString). Praktik ini meningkatkan pengalaman pengguna dan meningkatkan kemungkinan pengguna mengaktifkan akses.

Jangan tampilkan alert dengan permintaan untuk mengaktifkan akses segera setelah penolakan — beri pengguna kesempatan untuk memahami mengapa mereka mungkin membutuhkan fitur ini. Lebih baik menampilkan penjelasan saat mencoba menggunakan fungsionalitas yang memerlukan izin tersebut. UX Movement (2023) merekomendasikan menampilkan layar penjelasan 2-3 sesi setelah penolakan.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Akses ke \(feature)",
        message: "Izinkan akses di Pengaturan, "
            + "untuk menggunakan fitur ini",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Buka Pengaturan",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Nanti", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Apa yang terjadi jika tidak mencantumkan Usage Description

Tidak adanya kunci Usage Description yang wajib menyebabkan crash langsung aplikasi saat panggilan pertama API yang sesuai. Ini bukan peringatan Xcode, tetapi crash runtime dengan pengecualian NSInvalidArgumentException dan pesan konsol: "This app has crashed because it attempted to access privacy-sensitive data without a usage description".

Perilaku runtime tanpa kunci

iOS memeriksa keberadaan kunci NS*UsageDescription di Info.plist pada panggilan API pertama untuk sumber daya yang dilindungi. Jika kunci tidak ada, sistem segera mengakhiri aplikasi dengan sinyal SIGABRT. Ini terjadi bahkan pada perangkat dengan debugging — Xcode menunjukkan pengecualian di log, tetapi debugger tidak menangkapnya sebagai breakpoint.

Crash terjadi pada perangkat nyata dan simulator. Satu-satunya cara untuk menghindarinya adalah menambahkan kunci sebelum panggilan API. Penganalisis statis Xcode tidak selalu memperingatkan tentang tidak adanya kunci, terutama jika API dipanggil melalui SDK pihak ketiga. TestFlight penguji juga akan melihat crash, yang dapat menyebabkan ulasan negatif.

Situasi khusus dengan iOS 17+: Apple menambahkan pemeriksaan tambahan untuk akses ke clipboard (UIPasteboard). Jika aplikasi membaca clipboard tanpa tindakan eksplisit pengguna, iOS menampilkan spanduk peringatan, meskipun kunci Usage Description ada. Untuk clipboard tidak diperlukan kunci terpisah, tetapi Apple merekomendasikan untuk meminimalkan pembacaan otomatis.

Kesalahan saat peninjauan App Store

Selain crash runtime, tidak adanya kunci dapat menjadi alasan penolakan aplikasi saat moderasi. Apple memeriksa Info.plist pada tahap peninjauan dan dapat menolak build jika mendeteksi panggilan API tanpa kunci yang sesuai. Xcode tidak memblokir pengarsipan, tetapi App Store Connect dapat mengembalikan kesalahan saat memproses file biner.

Jika aplikasi tidak menggunakan sumber daya secara langsung, tetapi SDK pihak ketiga melakukannya (misalnya SDK analitik meminta IDFA), pengembang tetap harus menambahkan kunci yang sesuai. Apple memeriksa semua panggilan API dalam file biner, termasuk kode dari pustaka statis dan dinamis. Kesalahan "Missing Info.plist key" adalah salah satu alasan paling umum penolakan pembaruan.