Info.plist Usage Description — mi ez, NS*UsageDescription kulcsok és beállítás

Mi az Info.plist Usage Description?

Info.plist Usage Description — az NS*UsageDescription előtagú kulcsok sztringértékei, amelyek meghatározzák a rendszer párbeszédablakának szövegét a védett iOS-erőforrásokhoz való hozzáférés kérésekor. Amikor az alkalmazás először hív meg egy API-t, amely a felhasználó engedélyét igényli (pl. AVCaptureDevice a kamera esetében), az iOS megjeleníti a párbeszédablakot ezzel a szöveggel és az engedélyezés vagy elutasítás gombjaival.

A leírás szövege az egyetlen dolog, amit a fejlesztő kontrollálni tud a rendszer párbeszédablakában. A párbeszédablak címe „Az alkalmazás hozzáférést szeretne [erőforráshoz]” az iOS által automatikusan generált a kért erőforrás típusa alapján. A fejlesztő nem változtathatja meg a címet, a gombokat vagy a megjelenést — csak a magyarázó szöveget.

A Usage Description szorosan kapcsolódik az iOS runtime permissions modelljéhez. A felhasználó engedélyt ad egy kérelemre, amely később a Beállításokon keresztül visszavonható. Ismételt kérés esetén a párbeszédablak nem jelenik meg — az alkalmazásnak ellenőriznie kell az engedély állapotát és megfelelően reagálnia.

Az Apple erősen ajánlja, hogy a leírásban tüntesse fel a hozzáférési kérelem konkrét okát. Például „Profilfotók készítéséhez” jobb, mint „A kamerához való hozzáféréshez”. A konkrét szövegek növelik a felhasználói bizalmat és a megadott engedélyek százalékát. A Localytics (2023) adatai szerint az egyéni leírások 15-25%-kal növelik a beleegyezést az általános megfogalmazásokhoz képest.

A Usage Description és az ATT közötti különbség

Ne keverje össze az NS*UsageDescription-t az ATT-val (App Tracking Transparency). A Usage Description hozzáférési kérelem a rendszer erőforrásaihoz (kamera, geolokáció, fotó), míg az ATT nyomkövetési kérelem (hozzáférés az IDFA-hoz). Az ATT külön AppTrackingTransparency keretrendszert és az NSUserTrackingUsageDescription kulcsot használja, amely nem tartozik az NS*UsageDescription-hez.

A közös bennük, hogy mindkettő rendszer párbeszédablakot használ olyan szöveggel, amelyet az alkalmazás nem módosíthat. A különbség az, hogy a Usage Description erőforrás szinten működik, míg az ATT az eszközazonosító szintjén. Az NS*UsageDescription kulcsok az iOS 6-ban, az ATT az iOS 14.5-ben kerültek bevezetésre.

A kulcsok evolúciója a különböző iOS-verziókban

Minden iOS-kiadással az Apple új védett erőforrásokat és megfelelő kulcsokat adott hozzá. iOS 6: névjegyek, naptár, emlékeztetők, fotó. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: médiatár, Siri. iOS 11: NFC. iOS 14: nyomkövetés (ATT). iOS 17: hozzáférés a vágólaphoz (további megerősítést igényel).

Fontos: ha az alkalmazás egy adott iOS-verzióban bevezetett API-t használ, de a minimális támogatott verzió alacsonyabb, a kulcs akkor is kötelező. Az iOS ellenőrzi a kulcs meglétét az első API-hívás előtt, függetlenül attól, hogy az alkalmazás melyik verzión fut.

Mely NS*UsageDescription kulcsok kötelezőek

A kulcsok teljes listája attól függ, hogy az alkalmazás milyen funkciókat használ. Tekintsük át a 14 fő kulcsot, amelyek a leggyakrabban szükségesek a mobilalkalmazásokban.

Hozzáférés multimédiához

A NSCameraUsageDescription kulcs — kötelező a kamerához való hozzáféréskor AVCaptureDevice vagy UIImagePickerController segítségével .camera forrással. A NSMicrophoneUsageDescription kulcs — hangfelvételkor AVAudioRecorder segítségével vagy video hanggal történő rögzítésekor. Mindkét kulcs gyakran együtt szükséges, ha az alkalmazás videót rögzít.

A NSPhotoLibraryUsageDescription kulcs — fotók és videók olvasásakor a felhasználó médiatárából PHPicker vagy UIImagePickerController segítségével. A NSPhotoLibraryAddUsageDescription kulcs — ha az alkalmazás csak fotókat ment, de nem olvassa azokat. Az első olvasási hozzáférést kér, a második — csak írási hozzáférést.

Geolokáció és navigáció

A NSLocationWhenInUseUsageDescription kulcs — hozzáférés a geolokációhoz, amikor az alkalmazás aktív (a képernyőn). NSLocationAlwaysAndWhenInUseUsageDescription — mindig hozzáférés (beleértve a háttérmódot is). Az iOS mindkét kulcsot megköveteli, ha állandó hozzáférés szükséges: először WhenInUse, majd Always.

A NSLocationTemporaryUsageDescription és NSLocationPreciseUsageDescription kulcsok — további kulcsok ideiglenes hozzáférés vagy pontos geolokáció kéréséhez. A pontos helyszín külön engedélyt igényel, és a felhasználó csak a hozzávetőlegest kapcsolhatja be.

Névjegyek, naptár és egyéb adatok

A NSContactsUsageDescription kulcs — hozzáférés a felhasználó névjegyeihez CNContactStore segítségével. NSCalendarsUsageDescription — hozzáférés a naptárhoz események olvasásához és létrehozásához. NSRemindersUsageDescription — hozzáférés az emlékeztetőkhöz. NSBluetoothAlwaysUsageDescription — hozzáférés a Bluetooth-hoz háttérben (pl. BLE-eszközökhöz).

A NSHealthShareUsageDescription kulcs — hozzáférés a HealthKit-adatok olvasásához. NSHealthUpdateUsageDescription — hozzáférés az adatok HealthKit-be írásához. Mindkettő kötelező, ha az alkalmazás az egészségügy területén működik. Az Apple alaposan ellenőrzi a HealthKit-et használó alkalmazásokat, és elutasíthatja, ha a használati leírás nem felel meg a funkcionalitásnak.

Hogyan kell helyesen megfogalmazni a leírást

A Usage Description szövegének konkrétnak, valósnak és tömörnek kell lennie. Az Apple ajánlásokat ad a megfogalmazásokhoz, a moderátorok pedig ellenőrzik azok megfelelését a funkcionalitásnak.

A jó leírás szerkezete

A jó leírás három részből áll: mit csinál pontosan az alkalmazás az erőforrással, miért van erre szüksége a felhasználónak, és milyen előnye származik a felhasználónak a hozzáférés megadásából. Példa: „Profilfotók készítéséhez és űrlapra történő feltöltéséhez”. Kerülje az általános kifejezéseket: „Az alkalmazás működésének javításához” nem magyarázza meg, miért van szükség a kamerára.

Az Apple tiltja a megtévesztő leírásokat. Ha az áll, hogy „Fotók készítéséhez”, de az alkalmazás videót is rögzít, ez megtévesztőnek minősülhet. A moderátor elutasíthatja az alkalmazást, vagy magyarázatot kérhet. Az iOS 17-ben az Apple automatikus ellenőrzést vezetett be: a leírásnak a kért erőforrásnak megfelelő kulcsszavakat kell tartalmaznia.

Lokalizáció: a leírást le kell fordítani az alkalmazás által támogatott összes nyelvre. Ha az alkalmazás 10 nyelven érhető el, minden Usage Description kulcsnak rendelkeznie kell fordításokkal a Localizable.strings vagy InfoPlist.strings fájlokban. Az Apple ajánlja az InfoPlist.strings használatát az Info.plist kulcsok lokalizálásához.

Rossz és jó példák

• Rossz: „Hozzáférést igényel a kamerához” — nem magyarázza meg, miért
• Jó: „QR-kódok beolvasásához fizetéskor” — konkrét és érthető
• Rossz: „A hely meghatározásához” — pontatlan
• Jó: „A legközelebbi éttermek megtalálásához a térképen” — mutatja az értéket
• Rossz: „A szolgáltatás javításához” — nem informatív
• Jó: „Fotók feltöltéséhez a termék véleményéhez” — konkrét cselekvés

Lokalizáció InfoPlist.strings segítségével

A Usage Description lokalizálásához nem kell megduplázni az Info.plist-et minden nyelvre. Hozzon létre egy InfoPlist.strings fájlt minden nyelvi könyvtárban, és adja meg a kulcsértékeket. Az iOS automatikusan a megfelelő nyelvet használja a párbeszédablak megjelenítésekor. Az Xcode a 14-es verziótól támogatja az Info.plist alap lokalizációját.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "QR-kódok beolvasásához";
"NSPhotoLibraryUsageDescription" =
    "Képek feltöltéséhez a profilba";
"NSLocationWhenInUseUsageDescription" =
    "Közeli üzletek megjelenítéséhez a térképen";

Implementáció: kód és beállítások

A Usage Description helyes implementációja magában foglalja a kulcsok hozzáadását az Info.plist-hez, az engedély állapotának ellenőrzését a kódban és az elutasítás kezelését.

Kulcsok hozzáadása az Xcode segítségével

Az Xcode-ban nyissa meg az Info.plist-et, vigye az egérmutatót egy sorra, és kattintson a „+” gombra. Adja meg a kulcs nevét (pl. NSCameraUsageDescription) és adja meg a leírás sztringjét. Az Xcode automatikusan kiegészíti a kulcsneveket, ami csökkenti az elírások kockázatát. Hozzáadás után építse újra a projektet, és ellenőrizze, hogy a kulcs megjelenik-e a végső bináris fájlban.

Fontos: a kulcsok kis- és nagybetűérzékenyek. NSCameraUsageDescription — helyes, NSCamerausagedescription — hiba. A helytelen kulcsot a rendszer figyelmen kívül hagyja, és az alkalmazás összeomlik az API hívásakor. Az elírások elkerülése érdekében használja az Apple dokumentációjából történő másolást vagy az Xcode automatikus kiegészítését.

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

A hozzáférés elutasításának kezelése

Ha a felhasználó elutasította a hozzáférést, az alkalmazás nem hívhatja meg újra a rendszer párbeszédablakát — ez lehetetlen. Ehelyett jelenítsen meg egy tájékoztató képernyőt, amely elmagyarázza, hogyan lehet engedélyezni a hozzáférést a Beállításokon keresztül, és egy „Beállítások megnyitása” gombot (UIApplicationOpenSettingsURLString). Ez a gyakorlat javítja a felhasználói élményt és növeli annak valószínűségét, hogy a felhasználó engedélyezi a hozzáférést.

Ne jelenítsen meg azonnal az elutasítás után egy figyelmeztetést a hozzáférés engedélyezésének kérésével — adjon lehetőséget a felhasználónak, hogy megértse, miért lehet szüksége erre a funkcióra. Jobb, ha magyarázatot jelenít meg, amikor a felhasználó megpróbálja használni azt a funkciót, amely az adott engedélyt igényli. A UX Movement (2023) azt ajánlja, hogy a magyarázó képernyőt 2-3 munkamenettel az elutasítás után jelenítse meg.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Hozzáférést kér a(z) \(feature)",
        message: "Engedélyezze a hozzáférést a Beállításokban, "
            + "a funkció használatához",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Beállítások megnyitása",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Most nem", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Mi történik, ha nem adja meg a Usage Description-t

A kötelező Usage Description kulcs hiánya az alkalmazás azonnali összeomlásához vezet a megfelelő API első hívásakor. Ez nem Xcode figyelmeztetés, hanem runtime crash NSInvalidArgumentException kivétellel és a konzol üzenettel: „This app has crashed because it attempted to access privacy-sensitive data without a usage description”.

Runtime viselkedés kulcs nélkül

Az iOS ellenőrzi az NS*UsageDescription kulcs meglétét az Info.plist-ben a védett erőforráshoz tartozó API első hívásakor. Ha a kulcs hiányzik, a rendszer azonnal megszakítja az alkalmazást SIGABRT jellel. Ez még hibakeresési eszközökön is megtörténik — az Xcode megjeleníti a kivételt a naplóban, de a debugger nem fogja el töréspontként.

Az összeomlás valódi eszközökön és a szimulátoron is jelentkezik. Az egyetlen módja az elkerülésének, ha a kulcsot az API hívása előtt adja hozzá. Az Xcode statikus elemzője nem mindig figyelmeztet a kulcs hiányára, különösen, ha az API-t harmadik fél SDK-i hívják meg. A TestFlight tesztelők is látni fogják az összeomlást, ami negatív véleményekhez vezethet.

Különleges helyzet az iOS 17+-szal: az Apple további ellenőrzést vezetett be a vágólaphoz (UIPasteboard) való hozzáféréshez. Ha az alkalmazás a felhasználó kifejezett művelete nélkül olvassa a vágólapot, az iOS figyelmeztető sávot jelenít meg, még akkor is, ha a Usage Description kulcs jelen van. A vágólaphoz nem szükséges külön kulcs, de az Apple az automatikus olvasás minimalizálását ajánlja.

App Store felülvizsgálati hibák

A runtime összeomláson kívül a kulcs hiánya az alkalmazás moderálás alatti elutasításának oka lehet. Az Apple ellenőrzi az Info.plist-et a felülvizsgálati szakaszban, és elutasíthatja a build-et, ha API-hívásokat észlel a megfelelő kulcsok nélkül. Az Xcode nem blokkolja az archiválást, de az App Store Connect hibát adhat vissza a bináris fájl feldolgozásakor.

Ha az alkalmazás nem használja közvetlenül az erőforrást, de egy harmadik fél SDK-ja igen (pl. egy analitikai SDK IDFA-t kér), a fejlesztőnek akkor is hozzá kell adnia a megfelelő kulcsot. Az Apple ellenőrzi az összes API-hívást a bináris fájlban, beleértve a statikus és dinamikus könyvtárak kódját is. A „Missing Info.plist key” hiba a frissítések elutasításának egyik leggyakoribb oka.