Info.plist Usage Description — bu nədir, NS*UsageDescription açarları və konfiqurasiyası

Info.plist Usage Description nədir?

Info.plist Usage Description — iOS-un qorunan resurslarına giriş tələb edərkən sistem dialoqunun mətnini təyin edən NS*UsageDescription prefiksli açarların sətir dəyərləridir. Proqram ilk dəfə istifadəçinin icazəsini tələb edən API-i çağırdıqda (məsələn, kamera üçün AVCaptureDevice), iOS bu mətn və icazə və ya imtina düymələri ilə dialoq göstərir.

Təsvir mətni tərtibatçının sistem dialoqunda idarə edə biləcəyi yeganə şeydir. Dialoqun başlığı “Proqram [resurs]a giriş əldə etmək istəyir” iOS tərəfindən tələb olunan resursun növünə əsasən avtomatik yaradılır. Tərtibatçı başlığı, düymələri və ya görünüşü dəyişə bilməz — yalnız izahat mətnini.

Usage Description iOS-da runtime permissions modeli ilə sıx bağlıdır. İstifadəçi bir tələb üçün icazə verir, sonradan Parametrlər vasitəsilə geri götürülə bilər. Təkrar tələb edildikdə dialoq göstərilmir — proqram icazə statusunu yoxlamalı və müvafiq reaksiya verməlidir.

Apple təsvirdə giriş tələbinin konkret səbəbini göstərməyi tövsiyə edir. Məsələn, “Profil şəkillərinin çəkilməsi üçün” “Kameraya giriş üçün”-dən daha yaxşıdır. Konkret mətnlər istifadəçi etibarını və verilən icazələrin faizini artırır. Localytics (2023) məlumatlarına görə, fərdi təsvirlər ümumi ifadələrlə müqayisədə razılığı 15-25% artırır.

Usage Description və ATT arasındakı fərq

NS*UsageDescription-ı ATT (App Tracking Transparency) ilə qarışdırmayın. Usage Description sistem resurslarına (kamera, geolokasiya, foto) giriş tələbidir, ATT isə izləmə tələbidir (IDFA-ya giriş). ATT ayrıca AppTrackingTransparency çərçivəsindən və NS*UsageDescription-a aid olmayan NSUserTrackingUsageDescription açarından istifadə edir.

Onları birləşdirən odur ki, hər ikisi proqramın dəyişdirə bilməyəcəyi mətnlə sistem dialoqundan istifadə edir. Fərq ondadır ki, Usage Description resurslar səviyyəsində, ATT isə cihaz identifikatoru səviyyəsində işləyir. NS*UsageDescription açarları iOS 6-da, ATT isə iOS 14.5-də tətbiq edilmişdir.

Müxtəlif iOS versiyalarında açarların təkamülü

Hər iOS buraxılışı ilə Apple yeni qorunan resurslar və müvafiq açarlar əlavə edirdi. iOS 6: kontaktlar, təqvim, xatırlatmalar, foto. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: media kitabxanası, Siri. iOS 11: NFC. iOS 14: izləmə (ATT). iOS 17: mübadilə buferinə giriş (əlavə təsdiq tələb edir).

Vacib: proqram müəyyən iOS versiyasında təqdim edilmiş API-dən istifadə edirsə, lakin minimum dəstəklənən versiya aşağıdırsa, açar yenə də məcburidir. iOS açarın mövcudluğunu API-nin ilk çağırışından əvvəl yoxlayır, proqramın işlədiyi versiyadan asılı olmayaraq.

Hansı NS*UsageDescription açarları məcburidir

Açarların tam siyahısı proqramın hansı funksiyalardan istifadə etməsindən asılıdır. Mobil proqramlarda ən çox tələb olunan 14 əsas açarı nəzərdən keçirək.

Multimedia girişi

NSCameraUsageDescription açarı — AVCaptureDevice və ya .camera mənbəyi ilə UIImagePickerController vasitəsilə kameraya girişdə məcburidir. NSMicrophoneUsageDescription açarı — AVAudioRecorder vasitəsilə səs yazarkən və ya səslə video çəkərkən. Hər iki açar tez-tez birlikdə tələb olunur, əgər proqram video çəkirsə.

NSPhotoLibraryUsageDescription açarı — PHPicker və ya UIImagePickerController vasitəsilə istifadəçinin media kitabxanasından foto və videoları oxuyarkən. NSPhotoLibraryAddUsageDescription açarı — proqram yalnız foto saxlayırsa, lakin oxumursa. Birincisi oxuma girişi, ikincisi yalnız yazma üçün tələb edir.

Geolokasiya və naviqasiya

NSLocationWhenInUseUsageDescription açarı — proqram aktiv olduqda (ekranda) geolokasiyaya giriş. NSLocationAlwaysAndWhenInUseUsageDescription — həmişə giriş (fon rejimi daxil). Həmişəlik giriş lazımdırsa, iOS hər iki açarı tələb edir: əvvəlcə WhenInUse, sonra Always.

NSLocationTemporaryUsageDescription və NSLocationPreciseUsageDescription açarları — müvəqqəti giriş və ya dəqiq geolokasiya tələbi üçün əlavə açarlar. Dəqiq lokasiya ayrıca icazə tələb edir və istifadəçi yalnız təxmini olanı aktiv edə bilər.

Kontaktlar, təqvim və digər məlumatlar

NSContactsUsageDescription açarı — CNContactStore vasitəsilə istifadəçi kontaktlarına giriş. NSCalendarsUsageDescription — təqvimə giriş, hadisələri oxumaq və yaratmaq üçün. NSRemindersUsageDescription — xatırlatmalara giriş. NSBluetoothAlwaysUsageDescription — fonda Bluetooth-a giriş (məsələn, BLE cihazları üçün).

NSHealthShareUsageDescription açarı — HealthKit məlumatlarını oxumaq girişi. NSHealthUpdateUsageDescription — HealthKit-ə məlumat yazmaq girişi. Proqram sağlamlıq sahəsində işləyirsə, hər ikisi məcburidir. Apple HealthKit istifadə edən proqramları diqqətlə yoxlayır və istifadə təsviri funksionallığa uyğun gəlmirsə, rədd edə bilər.

Təsviri necə düzgün formalaşdırmaq olar

Usage Description-də mətn konkret, doğru və qısa olmalıdır. Apple ifadələrlə bağlı tövsiyələr verir, moderatorlar isə onların funksionallığa uyğunluğunu yoxlayır.

Yaxşı təsvirin strukturu

Yaxşı təsvir üç hissədən ibarətdir: proqramın resursla nə etdiyi, bunun istifadəçiyə nə üçün lazım olduğu və girişin verilməsindən istifadəçinin hansı fayda əldə etdiyi. Nümunə: “Profil şəkillərinin çəkilməsi və anketə yüklənməsi üçün”. Ümumi ifadələrdən qaçının: “Proqramın işini yaxşılaşdırmaq üçün” kameranın nə üçün lazım olduğunu izah etmir.

Apple yanıltıcı təsvirləri qadağan edir. Əgər “Foto çəkmək üçün” yazılıbsa, lakin proqram həmçinin video çəkirsə, bu aldadıcı hesab edilə bilər. Moderator proqramı rədd edə və ya izahat tələb edə bilər. iOS 17-də Apple avtomatik yoxlama əlavə etdi: təsvir tələb olunan resursa uyğun açar sözlər ehtiva etməlidir.

Lokallaşdırma: təsvir proqramın dəstəklədiyi bütün dillərə tərcümə edilməlidir. Proqram 10 dildə mövcuddursa, hər Usage Description açarı Localizable.strings və ya InfoPlist.strings fayllarında tərcümələrə malik olmalıdır. Apple Info.plist açarlarının lokallaşdırılması üçün InfoPlist.strings-dən istifadə etməyi tövsiyə edir.

Pis və yaxşı nümunələr

• Pis: “Kameraya giriş tələb olunur” — nə üçün olduğunu izah etmir
• Yaxşı: “Ödəniş zamanı QR kodlarını skan etmək üçün” — konkret və aydın
• Pis: “Məkanı müəyyən etmək üçün” — qeyri-dəqiq
• Yaxşı: “Xəritədə ən yaxın restoranları tapmaq üçün” — dəyəri göstərir
• Pis: “Xidməti yaxşılaşdırmaq üçün” — məlumatlandırıcı deyil
• Yaxşı: “Məhsul haqqında rəydə foto yükləmək üçün” — konkret hərəkət

InfoPlist.strings vasitəsilə lokallaşdırma

Usage Description-i lokallaşdırmaq üçün Info.plist-i hər dil üçün təkrarlamaq lazım deyil. Hər bir dil kataloqunda InfoPlist.strings faylı yaradın və açar dəyərlərini göstərin. iOS dialoq göstərərkən avtomatik olaraq müvafiq dili istifadə edir. Xcode 14-cü versiyadan etibarən Info.plist üçün əsas lokallaşdırmanı dəstəkləyir.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "QR kodlarını skan etmək üçün";
"NSPhotoLibraryUsageDescription" =
    "Profile şəkilləri yükləmək üçün";
"NSLocationWhenInUseUsageDescription" =
    "Ən yaxın mağazaları xəritədə göstərmək üçün";

Tətbiq: kod və parametrlər

Usage Description-in düzgün tətbiqi Info.plist-ə açarların əlavə edilməsini, kodda icazə statusunun yoxlanılmasını və imtinanın işlənməsini əhatə edir.

Xcode vasitəsilə açarların əlavə edilməsi

Xcode-da Info.plist-i açın, sətir üzərinə gəlin və “+” düyməsini sıxın. Açarın adını daxil edin (məsələn, NSCameraUsageDescription) və təsvir sətrini göstərin. Xcode açar adlarını avtomatik tamamlayır, bu da səhv riskini azaldır. Əlavə etdikdən sonra layihəni yenidən qurun və açarın son binar faylda göründüyünü yoxlayın.

Vacib: açarlar böyük-kiçik hərfə həssasdır. NSCameraUsageDescription — düzgün, NSCamerausagedescription — səhv. Yanlış açar nəzərə alınmır və API çağırışında proqram çökür. Səhvləri istisna etmək üçün Apple sənədlərindən kopyalama və ya Xcode-un avtomatik tamamlamasından istifadə edin.

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

Girişdən imtinanın işlənməsi

İstifadəçi girişdən imtina edərsə, proqram sistem dialoqunu təkrar çağırmamalıdır — bu mümkün deyil. Bunun əvəzinə Parametrlər vasitəsilə girişi necə aktiv etməyi izah edən məlumat ekranı və “Parametrləri aç” düyməsi (UIApplicationOpenSettingsURLString) göstərin. Bu təcrübə istifadəçi təcrübəsini yaxşılaşdırır və istifadəçinin girişi aktiv etmə ehtimalını artırır.

İmtinadan dərhal sonra girişi aktiv etmək xahişi ilə alert göstərməyin — istifadəçiyə bu funksiyaya niyə ehtiyacı ola biləcəyini anlamağa imkan verin. İcazə tələb edən funksionallıqdan istifadə cəhdində izahat göstərmək daha yaxşıdır. UX Movement (2023) imtinadan 2-3 sessiya sonra izahat ekranı göstərməyi tövsiyə edir.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Giriş: \(feature)",
        message: "Parametrlərdə girişə icazə verin, "
            + "bu funksiyadan istifadə etmək üçün",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Parametrləri aç",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "İndi yox", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Usage Description göstərilməsə nə olar

Məcburi Usage Description açarının olmaması müvafiq API-nin ilk çağırışında proqramın dərhal çökməsinə səbəb olur. Bu Xcode xəbərdarlığı deyil, konsola “This app has crashed because it attempted to access privacy-sensitive data without a usage description” mesajı ilə NSInvalidArgumentException istisnası olan runtime crash-dır.

Açar olmadan iş vaxtı davranışı

iOS qorunan resurs üçün API-nin ilk çağırışında Info.plist-də NS*UsageDescription açarının mövcudluğunu yoxlayır. Açar yoxdursa, sistem dərhal proqramı SIGABRT siqnalı ilə sonlandırır. Bu hətta sazlama cihazlarında da baş verir — Xcode logda istisna göstərir, lakin debugger onu fasilə nöqtəsi kimi tutmur.

Çökmə real cihazlarda və simulyatorda təkrarlanır. Bunun qarşısını almağın yeganə yolu API çağırışından əvvəl açarı əlavə etməkdir. Xcode statik analizatoru həmişə açarın olmaması barədə xəbərdarlıq etmir, xüsusən API üçüncü tərəf SDK-ları vasitəsilə çağırılırsa. TestFlight testçiləri də çökməni görəcək, bu da mənfi rəylərə səbəb ola bilər.

iOS 17+ ilə xüsusi vəziyyət: Apple mübadilə buferinə (UIPasteboard) giriş üçün əlavə yoxlama tətbiq etdi. Proqram istifadəçinin açıq hərəkəti olmadan buferi oxuyursa, iOS Usage Description açarı mövcud olsa belə, xəbərdarlıq banneri göstərir. Mübadilə buferi üçün ayrıca açar tələb olunmur, lakin Apple avtomatik oxumanı minimuma endirməyi tövsiyə edir.

App Store baxışında səhvlər

İş vaxtı çökməsindən əlavə, açarın olmaması proqramın moderasiya zamanı rədd edilməsinə səbəb ola bilər. Apple baxış mərhələsində Info.plist-i yoxlayır və müvafiq açarlar olmadan API çağırışları aşkar edərsə, build-i rədd edə bilər. Xcode arxivləşdirməni bloklamır, lakin App Store Connect binar faylı emal edərkən xəta qaytara bilər.

Proqram resursdan birbaşa istifadə etmirsə, lakin üçüncü tərəf SDK-sı bunu edirsə (məsələn, analitika SDK-sı IDFA tələb edir), tərtibatçı yenə də müvafiq açarı əlavə etməlidir. Apple binar fayldakı bütün API çağırışlarını, o cümlədən statik və dinamik kitabxanalardan kodu yoxlayır. “Missing Info.plist key” xətası yeniləmələrin rədd edilməsinin ən ümumi səbəblərindən biridir.