Info.plist Usage Description — co to je, klíče NS*UsageDescription a nastavení

Co je Info.plist Usage Description?

Info.plist Usage Description — jsou řetězcové hodnoty klíčů s předponou NS*UsageDescription, které určují text systémového dialogu při žádosti o přístup k chráněným zdrojům iOS. Když aplikace poprvé zavolá API vyžadující souhlas uživatele (např. AVCaptureDevice pro kameru), iOS zobrazí dialog s tímto textem a tlačítky pro povolení nebo odmítnutí.

Text popisu je jediná věc, kterou může vývojář v systémovém dialogu ovládat. Název dialogu „Aplikace chce získat přístup k [zdroji]“ je generován automaticky iOS na základě typu požadovaného zdroje. Vývojář nemůže změnit název, tlačítka ani vzhled — pouze vysvětlující text.

Usage Description je úzce spojen s modelem runtime permissions v iOS. Uživatel uděluje povolení pro jednu žádost, které může být později odvoláno prostřednictvím Nastavení. Při opakované žádosti se dialog nezobrazí — aplikace musí zkontrolovat stav povolení a odpovídajícím způsobem reagovat.

Apple důrazně doporučuje uvést v popisu konkrétní důvod žádosti o přístup. Například „Pro pořizování profilových fotografií“ je lepší než „Pro přístup ke kameře“. Konkrétní texty zvyšují důvěru uživatele a procento udělených povolení. Podle údajů Localytics (2023) zvyšují vlastní popisy souhlas o 15-25% ve srovnání s obecnými formulacemi.

Rozdíl mezi Usage Description a ATT

Nepleťte si NS*UsageDescription s ATT (App Tracking Transparency). Usage Description je žádost o přístup k systémovým zdrojům (kamera, geolokace, foto), zatímco ATT je žádost o sledování (přístup k IDFA). ATT používá samostatný framework AppTrackingTransparency a klíč NSUserTrackingUsageDescription, který nepatří do NS*UsageDescription.

Společné mají to, že oba používají systémový dialog s textem, který aplikace nemůže upravit. Rozdíl je v tom, že Usage Description pracuje na úrovni zdrojů, zatímco ATT na úrovni identifikátoru zařízení. Klíče NS*UsageDescription byly zavedeny v iOS 6, ATT — v iOS 14.5.

Vývoj klíčů v různých verzích iOS

S každým vydáním iOS Apple přidával nové chráněné zdroje a odpovídající klíče. iOS 6: kontakty, kalendář, připomínky, foto. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: knihovna médií, Siri. iOS 11: NFC. iOS 14: sledování (ATT). iOS 17: přístup ke schránce (vyžaduje dodatečné potvrzení).

Důležité: pokud aplikace používá API zavedené v určité verzi iOS, ale minimální podporovaná verze je nižší, klíč je stále povinný. iOS kontroluje přítomnost klíče před prvním voláním API, bez ohledu na verzi, na které aplikace běží.

Které klíče NS*UsageDescription jsou povinné

Úplný seznam klíčů závisí na tom, jaké funkce aplikace používá. Podívejme se na 14 hlavních klíčů, které jsou nejčastěji vyžadovány v mobilních aplikacích.

Přístup k multimédiím

Klíč NSCameraUsageDescription — povinný při přístupu ke kameře přes AVCaptureDevice nebo UIImagePickerController se zdrojem .camera. Klíč NSMicrophoneUsageDescription — při nahrávání zvuku přes AVAudioRecorder nebo při nahrávání videa se zvukem. Oba klíče jsou často vyžadovány společně, pokud aplikace nahrává video.

Klíč NSPhotoLibraryUsageDescription — při čtení fotografií a videí z knihovny médií uživatele přes PHPicker nebo UIImagePickerController. Klíč NSPhotoLibraryAddUsageDescription — pokud aplikace pouze ukládá fotografie, ale nečte je. První požaduje přístup pro čtení, druhý — pouze pro zápis.

Geolokace a navigace

Klíč NSLocationWhenInUseUsageDescription — přístup ke geolokaci, když je aplikace aktivní (na obrazovce). NSLocationAlwaysAndWhenInUseUsageDescription — přístup vždy (včetně režimu na pozadí). iOS vyžaduje oba klíče, pokud je potřeba trvalý přístup: nejprve WhenInUse, potom Always.

Klíče NSLocationTemporaryUsageDescription a NSLocationPreciseUsageDescription — další klíče pro žádost o dočasný přístup nebo přesnou geolokaci. Přesná poloha vyžaduje samostatné povolení a uživatel může zapnout pouze přibližnou.

Kontakty, kalendář a další údaje

Klíč NSContactsUsageDescription — přístup ke kontaktům uživatele přes CNContactStore. NSCalendarsUsageDescription — přístup ke kalendáři pro čtení a vytváření událostí. NSRemindersUsageDescription — přístup k připomínkám. NSBluetoothAlwaysUsageDescription — přístup k Bluetooth na pozadí (např. pro zařízení BLE).

Klíč NSHealthShareUsageDescription — přístup ke čtení dat HealthKit. NSHealthUpdateUsageDescription — přístup k zápisu dat do HealthKit. Oba jsou povinné, pokud aplikace pracuje v oblasti zdraví. Apple pečlivě kontroluje aplikace používající HealthKit a může je odmítnout, pokud popis použití neodpovídá funkčnosti.

Jak správně formulovat popis

Text v Usage Description by měl být konkrétní, pravdivý a výstižný. Apple poskytuje doporučení pro formulace a moderátoři kontrolují jejich shodu s funkčností.

Struktura dobrého popisu

Dobrý popis se skládá ze tří částí: co přesně aplikace se zdrojem dělá, proč to uživatel potřebuje a jaký přínos má uživatel z poskytnutí přístupu. Příklad: „Pro pořizování profilových fotografií a jejich nahrání do formuláře“. Vyhýbejte se obecným frázím: „Pro zlepšení fungování aplikace“ nevysvětluje, proč je kamera potřeba.

Apple zakazuje zavádějící popisy. Pokud je napsáno „Pro pořizování fotografií“, ale aplikace také nahrává video, může to být považováno za klamání. Moderátor může aplikaci odmítnout nebo požádat o vysvětlení. V iOS 17 Apple přidal automatickou kontrolu: popis musí obsahovat klíčová slova odpovídající požadovanému zdroji.

Lokalizace: popis by měl být přeložen do všech jazyků, které aplikace podporuje. Pokud je aplikace dostupná v 10 jazycích, každý klíč Usage Description musí mít překlady v souborech Localizable.strings nebo InfoPlist.strings. Apple doporučuje používat InfoPlist.strings pro lokalizaci klíčů Info.plist.

Špatné a dobré příklady

• Špatně: „Je vyžadován přístup ke kameře“ — nevysvětluje proč
• Dobře: „Pro skenování QR kódů při platbě“ — konkrétní a jasné
• Špatně: „Pro určení polohy“ — nepřesné
• Dobře: „Pro nalezení nejbližších restaurací na mapě“ — ukazuje hodnotu
• Špatně: „Pro zlepšení služby“ — neinformativní
• Dobře: „Pro nahrání fotografií do recenze produktu“ — konkrétní akce

Lokalizace pomocí InfoPlist.strings

Pro lokalizaci Usage Description není nutné duplikovat Info.plist pro každý jazyk. Vytvořte soubor InfoPlist.strings v každém jazykovém adresáři a uveďte hodnoty klíčů. iOS automaticky použije odpovídající jazyk v dialogu. Xcode podporuje základní lokalizaci pro Info.plist od verze 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Pro skenování QR kódů";
"NSPhotoLibraryUsageDescription" =
    "Pro nahrávání obrázků do profilu";
"NSLocationWhenInUseUsageDescription" =
    "Pro zobrazení nejbližších obchodů na mapě";

Implementace: kód a nastavení

Správná implementace Usage Description zahrnuje přidání klíčů do Info.plist, kontrolu stavu povolení v kódu a zpracování odmítnutí.

Přidávání klíčů přes Xcode

V Xcode otevřete Info.plist, najeďte na řádek a klikněte na „+". Zadejte název klíče (např. NSCameraUsageDescription) a uveďte řetězec popisu. Xcode automaticky doplňuje názvy klíčů, což snižuje riziko překlepů. Po přidání přestavějte projekt a zkontrolujte, že se klíč zobrazuje ve výsledném binárním souboru.

Důležité: klíče rozlišují velká a malá písmena. NSCameraUsageDescription — správně, NSCamerausagedescription — chyba. Nesprávný klíč je ignorován a aplikace spadne při volání API. Používejte kopírování z dokumentace Apple nebo automatické doplňování Xcode, abyste předešli překlepům.

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

Zpracování odmítnutí přístupu

Pokud uživatel odmítl přístup, aplikace by neměla znovu vyvolávat systémový dialog — to není možné. Místo toho zobrazte informační obrazovku s vysvětlením, jak zapnout přístup přes Nastavení, a tlačítko „Otevřít nastavení" (UIApplicationOpenSettingsURLString). Tato praxe zlepšuje uživatelský zážitek a zvyšuje pravděpodobnost, že uživatel přístup zapne.

Nezobrazujte alert s žádostí o zapnutí přístupu ihned po odmítnutí — dejte uživateli možnost pochopit, proč by tuto funkci mohl potřebovat. Lepší je zobrazit vysvětlení při pokusu o použití funkčnosti, která vyžaduje dané povolení. UX Movement (2023) doporučuje zobrazit vysvětlující obrazovku 2-3 relace po odmítnutí.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Přístup k \(feature)",
        message: "Povolte přístup v Nastavení, "
            + "pro použití této funkce",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Otevřít Nastavení",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Nyní ne", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Co se stane, pokud neuvedete Usage Description

Absence povinného klíče Usage Description vede k okamžitému pádu aplikace při prvním volání odpovídajícího API. To není varování Xcode, ale pád za běhu s výjimkou NSInvalidArgumentException a zprávou v konzoli: „This app has crashed because it attempted to access privacy-sensitive data without a usage description".

Chování za běhu bez klíče

iOS kontroluje přítomnost klíče NS*UsageDescription v Info.plist při prvním volání API pro chráněný zdroj. Pokud klíč chybí, systém okamžitě ukončí aplikaci signálem SIGABRT. K tomu dochází i na zařízeních s laděním — Xcode zobrazí výjimku v logu, ale debugger ji nezachytí jako bod přerušení.

K pádu dochází na skutečných zařízeních i simulátoru. Jediný způsob, jak se mu vyhnout, je přidat klíč před voláním API. Statický analyzátor Xcode ne vždy varuje před absencí klíče, zejména pokud je API voláno prostřednictvím SDK třetích stran. TestFlight testeři také uvidí pád, což může vést k negativním recenzím.

Zvláštní situace s iOS 17+: Apple zavedl dodatečnou kontrolu pro přístup ke schránce (UIPasteboard). Pokud aplikace čte schránku bez výslovné akce uživatele, iOS zobrazí varovný banner, i když klíč Usage Description existuje. Pro schránku není vyžadován samostatný klíč, ale Apple doporučuje minimalizovat automatické čtení.

Chyby při revizi App Store

Kromě pádu za běhu může absence klíče být důvodem pro odmítnutí aplikace při moderaci. Apple kontroluje Info.plist ve fázi revize a může odmítnout build, pokud zjistí volání API bez odpovídajících klíčů. Xcode neblokuje archivaci, ale App Store Connect může vrátit chybu při zpracování binárního souboru.

Pokud aplikace nevyužívá zdroj přímo, ale SDK třetí strany to dělá (např. analytické SDK žádá IDFA), vývojář musí stejně přidat odpovídající klíč. Apple kontroluje všechna volání API v binárním souboru, včetně kódu ze statických a dynamických knihoven. Chyba „Missing Info.plist key" je jedním z nejčastějších důvodů odmítnutí aktualizací.