Info.plist Usage Description — nedir, NS*UsageDescription anahtarları ve kurulum

Info.plist Usage Description nedir?

Info.plist Usage Description, iOS'un korunan kaynaklarına erişim istenirken sistem diyalogunun metnini tanımlayan NS*UsageDescription ön ekli anahtarların dize değerleridir. Bir uygulama ilk kez kullanıcı izni gerektiren bir API'yi çağırdığında (örneğin, kamera için AVCaptureDevice), iOS bu metni ve izin ver/reddet düğmelerini içeren bir diyalog gösterir.

Açıklama metni, geliştiricinin sistem diyalogunda kontrol edebileceği tek şeydir. Diyalog başlığı “ [kaynağa] erişmek istiyor” iOS tarafından istenen kaynak türüne göre otomatik olarak oluşturulur. Geliştirici başlığı, düğmeleri veya görünümü değiştiremez — yalnızca açıklama metnini değiştirebilir.

Usage Description, iOS'taki çalışma zamanı izinleri modeliyle yakından ilişkilidir. Kullanıcı bir istek için izin verir ve bu izin daha sonra Ayarlar üzerinden iptal edilebilir. Sonraki bir istekte diyalog tekrar gösterilmez — uygulama izin durumunu kontrol etmeli ve buna göre yanıt vermelidir.

Apple, açıklamada erişim isteği için belirli bir neden belirtilmesini şiddetle önerir. Örneğin, “Profil fotoğrafları çekmek için”, “Kameraya erişmek için” ifadesinden daha iyidir. Belirli metinler kullanıcı güvenini ve izin verme oranını artırır. Localytics (2023)'e göre, özel açıklamalar genel ifadelere kıyasla onayı %15-25 oranında artırır.

Usage Description ve ATT arasındaki fark

NS*UsageDescription'ı ATT (App Tracking Transparency) ile karıştırmayın. Usage Description, sistem kaynaklarına (kamera, coğrafi konum, fotoğraflar) erişim isteğidir; ATT ise izleme (IDFA'ya erişim) isteğidir. ATT, ayrı bir framework olan AppTrackingTransparency'yi ve NS*UsageDescription'ın parçası olmayan NSUserTrackingUsageDescription anahtarını kullanır.

Ortak noktaları, her ikisinin de uygulamanın değiştiremeyeceği metin içeren bir sistem diyalogu kullanmasıdır. Fark, Usage Description'ın kaynak düzeyinde çalışması, ATT'nin ise cihaz tanımlayıcı düzeyinde çalışmasıdır. NS*UsageDescription anahtarları iOS 6'da, ATT ise iOS 14.5'te tanıtıldı.

iOS sürümlerinde anahtarların gelişimi

Her iOS sürümüyle Apple, yeni korunan kaynaklar ve ilgili anahtarlar ekledi. iOS 6: kişiler, takvim, hatırlatıcılar, fotoğraflar. iOS 7: mikrofon. iOS 8: HomeKit, Sağlık. iOS 10: medya kitaplığı, Siri. iOS 11: NFC. iOS 14: izleme (ATT). iOS 17: pano erişimi (ek onay gerektirir).

Önemli: uygulama belirli bir iOS sürümünde tanıtılan bir API'yi kullanıyorsa ancak desteklenen minimum sürüm daha düşükse, anahtar yine de zorunludur. iOS, uygulamanın hangi sürümde çalıştığına bakılmaksızın, ilk API çağrısından önce anahtarın varlığını kontrol eder.

Zorunlu NS*UsageDescription anahtarları

Anahtarların tam listesi, uygulamanın kullandığı işlevlere bağlıdır. Mobil uygulamalarda en sık gereken 14 ana anahtarı inceleyelim.

Medya erişimi

NSCameraUsageDescription anahtarı, AVCaptureDevice veya .camera kaynaklı UIImagePickerController aracılığıyla kameraya erişirken zorunludur. NSMicrophoneUsageDescription anahtarı, AVAudioRecorder aracılığıyla ses kaydederken veya sesli video çekerken gereklidir. Uygulama video kaydediyorsa her iki anahtar da genellikle birlikte gerekir.

NSPhotoLibraryUsageDescription anahtarı, PHPicker veya UIImagePickerController aracılığıyla kullanıcının medya kitaplığından fotoğraf ve video okurken kullanılır. NSPhotoLibraryAddUsageDescription anahtarı, uygulama yalnızca fotoğrafları kaydediyor ancak okumuyorsa kullanılır. İlki okuma erişimi ister, ikincisi yalnızca yazma erişimi ister.

Coğrafi konum ve navigasyon

NSLocationWhenInUseUsageDescription anahtarı, uygulama etkinken (ekrandayken) coğrafi konum erişimi sağlar. NSLocationAlwaysAndWhenInUseUsageDescription her zaman erişim sağlar (arka plan modu dahil). Sürekli erişim gerekiyorsa iOS her iki anahtarı da ister: önce WhenInUse, sonra Always.

NSLocationTemporaryUsageDescription ve NSLocationPreciseUsageDescription anahtarları, geçici erişim veya hassas coğrafi konum istemek için ek anahtarlardır. Hassas konum ayrı bir izin gerektirir ve kullanıcı yalnızca yaklaşık konumu etkinleştirebilir.

Kişiler, takvim ve diğer veriler

NSContactsUsageDescription anahtarı, CNContactStore aracılığıyla kullanıcının kişilerine erişim sağlar. NSCalendarsUsageDescription, etkinlikleri okumak ve oluşturmak için takvim erişimi sağlar. NSRemindersUsageDescription, hatırlatıcılara erişim sağlar. NSBluetoothAlwaysUsageDescription, arka planda Bluetooth erişimi sağlar (örneğin, BLE cihazları için).

NSHealthShareUsageDescription anahtarı, HealthKit verilerini okuma erişimi sağlar. NSHealthUpdateUsageDescription, HealthKit'e veri yazma erişimi sağlar. Uygulama sağlık verileriyle çalışıyorsa her ikisi de zorunludur. Apple, HealthKit kullanan uygulamaları dikkatle inceler ve kullanım açıklaması işlevsellikle eşleşmezse uygulamayı reddedebilir.

Açıklama nasıl doğru şekilde yazılır

Usage Description metni belirli, doğru ve öz olmalıdır. Apple, ifade konusunda öneriler sunar ve denetleyiciler işlevsellikle uyumu kontrol eder.

İyi bir açıklamanın yapısı

İyi bir açıklama üç bölümden oluşur: uygulamanın kaynakla tam olarak ne yaptığı, kullanıcının neden buna ihtiyacı olduğu ve erişim izni vererek kullanıcının hangi faydayı elde ettiği. Örnek: “Profil fotoğrafları çekmek ve profilinize yüklemek için.” Genel ifadelerden kaçının: “Uygulama performansını iyileştirmek için” kameraya neden ihtiyaç duyulduğunu açıklamaz.

Apple yanıltıcı açıklamaları yasaklar. “Fotoğraf çekmek için” yazıyorsa ancak uygulama ayrıca video da kaydediyorsa, bu aldatıcı olarak kabul edilebilir. Denetleyici uygulamayı reddedebilir veya açıklama talep edebilir. iOS 17'de Apple otomatik doğrulama ekledi: açıklama, istenen kaynağa karşılık gelen anahtar kelimeler içermelidir.

Yerelleştirme: açıklama, uygulamanın desteklediği tüm dillere çevrilmelidir. Uygulama 10 dilde mevcutsa, her Usage Description anahtarının Localizable.strings veya InfoPlist.strings dosyalarında çevirileri olmalıdır. Apple, Info.plist anahtarlarını yerelleştirmek için InfoPlist.strings kullanılmasını önerir.

Kötü ve iyi örnekler

• Kötü: “Kamera erişimi gerekiyor” — nedenini açıklamaz
• İyi: “Ödeme sırasında QR kodlarını taramak için” — belirli ve net
• Kötü: “Konum belirlemek için” — belirsiz
• İyi: “Haritada yakındaki restoranları bulmak için” — değeri gösterir
• Kötü: “Hizmeti iyileştirmek için” — bilgilendirici değil
• İyi: “Ürün incelemesine fotoğraf yüklemek için” — belirli eylem

InfoPlist.strings ile yerelleştirme

Usage Description'ı yerelleştirmek için her dil için Info.plist'i çoğaltmanız gerekmez. Her dil dizininde bir InfoPlist.strings dosyası oluşturun ve anahtar değerlerini belirtin. iOS, diyalogu gösterirken otomatik olarak doğru dili kullanacaktır. Xcode, sürüm 14'ten itibaren Info.plist için temel yerelleştirmeyi destekler.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "QR kodlarını taramak için";
"NSPhotoLibraryUsageDescription" =
    "Profile resim yüklemek için";
"NSLocationWhenInUseUsageDescription" =
    "Haritada yakındaki mağazaları göstermek için";

Uygulama: kod ve ayarlar

Usage Description'ın doğru uygulanması, Info.plist'e anahtar eklemeyi, kodda izin durumunu kontrol etmeyi ve reddetmeyi yönetmeyi içerir.

Xcode ile anahtar ekleme

Xcode'da Info.plist'i açın, bir satırın üzerine gelin ve “+” tıklayın. Anahtar adını girin (örneğin, NSCameraUsageDescription) ve açıklama dizesini belirtin. Xcode anahtar adlarını otomatik tamamlar ve yazım hatası riskini azaltır. Ekledikten sonra projeyi yeniden derleyin ve anahtarın son ikili dosyada göründüğünü doğrulayın.

Önemli: anahtarlar büyük/küçük harfe duyarlıdır. NSCameraUsageDescription doğrudur, NSCamerausagedescription hatadır. Yanlış bir anahtar yok sayılır ve API çağrıldığında uygulama çöker. Yazım hatalarını önlemek için Apple belgelerinden kopyalayın veya Xcode otomatik tamamlama özelliğini kullanın.

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)")
        }
    }
}

Erişim reddini yönetme

Kullanıcı erişimi reddederse, uygulama sistem diyalogunu tekrar çağırmamalıdır — bu mümkün değildir. Bunun yerine, Ayarlar üzerinden erişimin nasıl etkinleştirileceğini açıklayan bir bilgi ekranı gösterin ve “Ayarları Aç” düğmesi (UIApplicationOpenSettingsURLString) sunun. Bu uygulama kullanıcı deneyimini ve kullanıcının erişimi etkinleştirme olasılığını artırır.

Reddetmeden hemen sonra erişimi etkinleştirmeyi isteyen bir uyarı göstermeyin — kullanıcıya bu özelliğe neden ihtiyaç duyabileceğini anlaması için zaman verin. Bu izni gerektiren işlevselliği kullanmaya çalışırken açıklamayı göstermek daha iyidir. UX Movement (2023), reddetmeden 2-3 oturum sonra açıklama ekranının gösterilmesini önerir.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Erişim: \(feature)",
        message: "Allow access in Settings, "
            + "to use this feature",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Open Settings",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Not now", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Usage Description belirtilmezse ne olur

Zorunlu bir Usage Description anahtarının olmaması, ilgili API'nin ilk çağrısında uygulamanın anında çökmesine neden olur. Bu bir Xcode uyarısı değil, NSInvalidArgumentException ve konsolda “Bu uygulama, kullanım açıklaması olmadan gizliliğe duyarlı verilere erişmeye çalıştığı için çöktü” mesajıyla birlikte bir çalışma zamanı çökmesidir.

Anahtar olmadan çalışma zamanı davranışı

iOS, korunan bir kaynak için ilk API çağrısında Info.plist'te NS*UsageDescription anahtarının varlığını kontrol eder. Anahtar eksikse, işletim sistemi uygulamayı SIGABRT sinyaliyle hemen sonlandırır. Bu, hata ayıklama cihazlarında bile olur — Xcode istisnayı günlükte gösterir, ancak hata ayıklayıcı bunu bir kesme noktası olarak yakalamaz.

Çökme, gerçek cihazlarda ve simülatörde tekrarlanır. Bunu önlemenin tek yolu, API'yi çağırmadan önce anahtarı eklemektir. Xcode'un statik analizörü, özellikle API üçüncü taraf SDK'lar aracılığıyla çağrılıyorsa, eksik anahtar konusunda her zaman uyarmaz. TestFlight test kullanıcıları da çökmeyi görecek ve bu da olumsuz yorumlara yol açabilir.

iOS 17+ ile özel durum: Apple, pano erişimi (UIPasteboard) için ek bir kontrol getirdi. Uygulama, kullanıcının açık eylemi olmadan panoyu okursa, Usage Description anahtarı mevcut olsa bile iOS bir uyarı banner'ı gösterir. Pano ayrı bir anahtar gerektirmez, ancak Apple otomatik okumanın en aza indirilmesini önerir.

App Store inceleme hataları

Çalışma zamanı çökmesine ek olarak, anahtar eksikliği inceleme sırasında uygulama reddine neden olabilir. Apple, inceleme aşamasında Info.plist'i kontrol eder ve ilgili anahtarlar olmadan API çağrıları tespit ederse derlemeyi reddedebilir. Xcode arşivlemeyi engellemez, ancak App Store Connect ikili dosyayı işlerken bir hata döndürebilir.

Uygulama kaynağı doğrudan kullanmıyorsa ancak bir üçüncü taraf SDK kullanıyorsa (örneğin, bir analitik SDK'sı IDFA talep ediyorsa), geliştirici yine de ilgili anahtarı eklemelidir. Apple, statik ve dinamik kitaplıkların kodu dahil olmak üzere ikili dosyadaki tüm API çağrılarını kontrol eder. “Info.plist anahtarı eksik” hatası, güncelleme reddinin en yaygın nedenlerinden biridir.