Info.plist Usage Description — ce este, cheile NS*UsageDescription și configurarea

Ce este Info.plist Usage Description?

Info.plist Usage Description — sunt valorile șirurilor cheilor cu prefixul NS*UsageDescription care definesc textul dialogului de sistem la solicitarea accesului la resursele protejate iOS. Când aplicația apelează pentru prima dată o API care necesită permisiunea utilizatorului (de exemplu, AVCaptureDevice pentru cameră), iOS afișează un dialog cu acest text și butoanele de permisiune sau refuz.

Textul descrierii este singurul lucru pe care dezvoltatorul îl poate controla în dialogul de sistem. Titlul dialogului „Aplicația dorește să obțină acces la [resursa]” este generat automat de iOS pe baza tipului de resursă solicitată. Dezvoltatorul nu poate modifica titlul, butoanele sau aspectul — doar textul explicației.

Usage Description este strâns legat de modelul runtime permissions în iOS. Utilizatorul acordă permisiunea pentru o solicitare, care poate fi revocată ulterior prin Setări. La o solicitare repetată, dialogul nu mai este afișat — aplicația trebuie să verifice starea permisiunii și să reacționeze corespunzător.

Apple recomandă insistent să indicați în descriere un motiv concret al solicitării accesului. De exemplu, „Pentru realizarea fotografiilor de profil” este mai bine decât „Pentru accesul la cameră”. Textele concrete cresc încrederea utilizatorului și procentul permisiunilor acordate. Conform datelor Localytics (2023), descrierile personalizate cresc consimțământul cu 15-25% comparativ cu formulările generale.

Diferența dintre Usage Description și ATT

Nu confundați NS*UsageDescription cu ATT (App Tracking Transparency). Usage Description este o solicitare de acces la resursele sistemului (cameră, geolocație, foto), iar ATT este o solicitare de urmărire (acces la IDFA). ATT utilizează un cadru separat AppTrackingTransparency și cheia NSUserTrackingUsageDescription, care nu aparține NS*UsageDescription.

Ceea ce au în comun este că ambele folosesc dialogul de sistem cu text pe care aplicația nu îl poate modifica. Diferența constă în faptul că Usage Description funcționează la nivel de resurse, iar ATT la nivelul identificatorului dispozitivului. Cheile NS*UsageDescription au fost introduse în iOS 6, ATT — în iOS 14.5.

Evoluția cheilor în diferite versiuni iOS

Cu fiecare versiune iOS, Apple a adăugat noi resurse protejate și chei corespunzătoare. iOS 6: contacte, calendar, memento-uri, foto. iOS 7: microfon. iOS 8: HomeKit, Health. iOS 10: bibliotecă media, Siri. iOS 11: NFC. iOS 14: urmărire (ATT). iOS 17: acces la clipboard (necesită confirmare suplimentară).

Important: dacă aplicația utilizează o API introdusă într-o anumită versiune iOS, dar versiunea minimă suportată este mai mică, cheia este tot obligatorie. iOS verifică prezența cheii înainte de prima apelare a API, indiferent de versiunea pe care rulează aplicația.

Ce chei NS*UsageDescription sunt obligatorii

Lista completă a cheilor depinde de funcțiile pe care le utilizează aplicația. Să examinăm cele 14 chei principale care sunt cel mai des necesare în aplicațiile mobile.

Accesul la multimedia

Cheia NSCameraUsageDescription — obligatorie la accesul la cameră prin AVCaptureDevice sau UIImagePickerController cu sursa .camera. Cheia NSMicrophoneUsageDescription — la înregistrarea audio prin AVAudioRecorder sau la filmarea video cu sunet. Ambele chei sunt adesea necesare împreună dacă aplicația înregistrează video.

Cheia NSPhotoLibraryUsageDescription — la citirea fotografiilor și videoclipurilor din biblioteca media a utilizatorului prin PHPicker sau UIImagePickerController. Cheia NSPhotoLibraryAddUsageDescription — dacă aplicația doar salvează fotografii, dar nu le citește. Prima solicită acces de citire, a doua — doar de scriere.

Geolocație și navigație

Cheia NSLocationWhenInUseUsageDescription — acces la geolocație când aplicația este activă (pe ecran). NSLocationAlwaysAndWhenInUseUsageDescription — acces permanent (inclusiv în fundal). iOS necesită ambele chei dacă este necesar accesul permanent: mai întâi WhenInUse, apoi Always.

Cheile NSLocationTemporaryUsageDescription și NSLocationPreciseUsageDescription — chei suplimentare pentru solicitarea accesului temporar sau a geolocației precise. Locația precisă necesită o permisiune separată, iar utilizatorul poate activa doar pe cea aproximativă.

Contacte, calendar și alte date

Cheia NSContactsUsageDescription — acces la contactele utilizatorului prin CNContactStore. NSCalendarsUsageDescription — acces la calendar pentru citirea și crearea evenimentelor. NSRemindersUsageDescription — acces la memento-uri. NSBluetoothAlwaysUsageDescription — acces la Bluetooth în fundal (de exemplu, pentru dispozitive BLE).

Cheia NSHealthShareUsageDescription — acces la citirea datelor HealthKit. NSHealthUpdateUsageDescription — acces la scrierea datelor în HealthKit. Ambele sunt obligatorii dacă aplicația operează în domeniul sănătății. Apple verifică cu atenție aplicațiile care utilizează HealthKit și poate respinge dacă descrierea utilizării nu corespunde funcționalității.

Cum să formulați corect descrierea

Textul din Usage Description trebuie să fie concret, corect și concis. Apple oferă recomandări privind formulările, iar moderatorii verifică conformitatea lor cu funcționalitatea.

Structura unei bune descrieri

O descriere bună constă din trei părți: ce anume face aplicația cu resursa, de ce este necesar acest lucru utilizatorului și ce beneficiu are utilizatorul din acordarea accesului. Exemplu: „Pentru realizarea fotografiilor de profil și încărcarea lor în formular". Evitați frazele generale: „Pentru îmbunătățirea funcționării aplicației" nu explică de ce este necesară camera.

Apple interzice descrierile înșelătoare. Dacă scrie „Pentru realizarea fotografiilor", dar aplicația înregistrează și video, acest lucru poate fi considerat înșelător. Moderatorul poate respinge aplicația sau poate solicita clarificări. În iOS 17, Apple a adăugat verificarea automată: descrierea trebuie să conțină cuvinte cheie corespunzătoare resursei solicitate.

Localizarea: descrierea trebuie tradusă în toate limbile suportate de aplicație. Dacă aplicația este disponibilă în 10 limbi, fiecare cheie Usage Description trebuie să aibă traduceri în fișierele Localizable.strings sau InfoPlist.strings. Apple recomandă utilizarea InfoPlist.strings pentru localizarea cheilor Info.plist.

Exemple proaste și bune

• Rău: „Este necesar accesul la cameră" — nu explică de ce
• Bine: „Pentru scanarea codurilor QR la plată" — concret și clar
• Rău: „Pentru determinarea locației" — vag
• Bine: „Pentru găsirea celor mai apropiate restaurante pe hartă" — arată valoarea
• Rău: „Pentru îmbunătățirea serviciului" — neinformativ
• Bine: „Pentru încărcarea fotografiilor în recenzia produsului" — acțiune concretă

Localizarea prin InfoPlist.strings

Pentru localizarea Usage Description nu este necesară duplicarea Info.plist pentru fiecare limbă. Creați fișierul InfoPlist.strings în fiecare director lingvistic și specificați valorile cheilor. iOS va utiliza automat limba corespunzătoare în dialog. Xcode suportă localizarea de bază pentru Info.plist începând cu versiunea 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Pentru scanarea codurilor QR";
"NSPhotoLibraryUsageDescription" =
    "Pentru încărcarea imaginilor în profil";
"NSLocationWhenInUseUsageDescription" =
    "Pentru afișarea magazinelor apropiate pe hartă";

Implementare: cod și setări

Implementarea corectă a Usage Description include adăugarea cheilor în Info.plist, verificarea stării permisiunii în cod și gestionarea refuzului.

Adăugarea cheilor prin Xcode

În Xcode deschideți Info.plist, plasați cursorul pe un rând și apăsați „+". Introduceți numele cheii (de exemplu, NSCameraUsageDescription) și specificați șirul descrierii. Xcode completează automat numele cheilor, ceea ce reduce riscul greșelilor de tastare. După adăugare, reconstruiți proiectul și verificați că cheia se afișează în fișierul binar final.

Important: cheile fac diferența între majuscule și minuscule. NSCameraUsageDescription — corect, NSCamerausagedescription — eroare. O cheie incorectă este ignorată, iar aplicația se va bloca la apelarea API. Utilizați copierea din documentația Apple sau completarea automată Xcode pentru a evita greșelile de tastare.

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

Gestionarea refuzului accesului

Dacă utilizatorul a refuzat accesul, aplicația nu trebuie să reapeleze dialogul de sistem — acest lucru este imposibil. În schimb, afișați un ecran informativ cu explicația cum să activați accesul prin Setări și un buton „Deschide setările" (UIApplicationOpenSettingsURLString). Această practică îmbunătățește experiența utilizatorului și crește probabilitatea ca utilizatorul să activeze accesul.

Nu afișați un alert cu solicitarea de a activa accesul imediat după refuz — oferiți utilizatorului posibilitatea de a înțelege de ce ar putea avea nevoie de această funcție. Este mai bine să afișați o explicație la încercarea de a utiliza funcționalitatea care necesită respectiva permisiune. UX Movement (2023) recomandă afișarea ecranului de explicație după 2-3 sesiuni de la refuz.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Acces la \(feature)",
        message: "Permiteți accesul în Setări, "
            + "pentru a utiliza această funcție",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Deschide Setări",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Nu acum", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Ce se întâmplă dacă nu specificați Usage Description

Absența cheii obligatorii Usage Description duce la crașarea imediată a aplicației la prima apelare a API corespunzătoare. Aceasta nu este o avertizare Xcode, ci o blocare la runtime cu excepția NSInvalidArgumentException și mesajul în consolă: „This app has crashed because it attempted to access privacy-sensitive data without a usage description".

Comportamentul la runtime fără cheie

iOS verifică prezența cheii NS*UsageDescription în Info.plist la prima apelare a API pentru o resursă protejată. Dacă cheia lipsește, sistemul încheie imediat aplicația cu semnalul SIGABRT. Acest lucru se întâmplă chiar și pe dispozitivele cu depanare — Xcode afișează excepția în log, dar debuggerul nu o prinde ca punct de întrerupere.

Blocarea are loc pe dispozitive reale și pe simulator. Singura modalitate de a o evita este adăugarea cheii înainte de apelarea API. Analizorul static Xcode nu avertizează întotdeauna despre absența cheii, mai ales dacă API este apelată prin SDK-uri terțe. TestFlight testerii vor vedea, de asemenea, blocarea, ceea ce poate duce la recenzii negative.

O situație specială cu iOS 17+: Apple a introdus o verificare suplimentară pentru accesul la clipboard (UIPasteboard). Dacă aplicația citește clipboard-ul fără o acțiune explicită a utilizatorului, iOS afișează un banner de avertizare, chiar dacă cheia Usage Description este prezentă. Pentru clipboard nu este necesară o cheie separată, dar Apple recomandă minimizarea citirii automate.

Erori la revizia App Store

Pe lângă blocarea la runtime, absența cheii poate fi un motiv de respingere a aplicației la moderare. Apple verifică Info.plist în etapa de revizie și poate respinge build-ul dacă detectează apeluri API fără cheile corespunzătoare. Xcode nu blochează arhivarea, dar App Store Connect poate returna o eroare la procesarea fișierului binar.

Dacă aplicația nu utilizează resursa direct, dar SDK-ul terț o face (de exemplu, SDK-ul analitic solicită IDFA), dezvoltatorul trebuie totuși să adauge cheia corespunzătoare. Apple verifică toate apelurile API în fișierul binar, inclusiv codul din bibliotecile statice și dinamice. Eroarea „Missing Info.plist key" este una dintre cele mai frecvente cauze de respingere a actualizărilor.