Info.plist Usage Description — vad är det, NS*UsageDescription-nycklar och konfiguration

Vad är Info.plist Usage Description?

Info.plist Usage Description är strängvärdena för nycklar med prefixet NS*UsageDescription som bestämmer texten i systemdialogrutan vid begäran om åtkomst till skyddade iOS-resurser. När en app första gången anropar ett API som kräver användarens tillstånd (t.ex. AVCaptureDevice för kameran) visar iOS en dialogruta med denna text och knappar för att tillåta eller neka.

Beskrivningstexten är det enda som utvecklaren kan kontrollera i systemdialogrutan. Dialogrutans titel “Appen vill få åtkomst till [resurs]” genereras automatiskt av iOS baserat på typen av begärd resurs. Utvecklaren kan inte ändra titel, knappar eller utseende — endast förklaringstexten.

Usage Description är nära kopplat till modellen runtime permissions i iOS. Användaren ger tillstånd för en begäran, som senare kan återkallas via Inställningar. Vid en upprepad begäran visas inte dialogrutan — appen måste kontrollera tillståndsstatus och reagera därefter.

Apple rekommenderar starkt att du i beskrivningen anger en specifik orsak till åtkomstbegäran. Till exempel “För att ta profilbilder” är bättre än “För åtkomst till kameran”. Specifika texter ökar användarens förtroende och andelen beviljade tillstånd. Enligt uppgifter från Localytics (2023) ökar anpassade beskrivningar samtycket med 15-25% jämfört med allmänna formuleringar.

Skillnad mellan Usage Description och ATT

Förväxla inte NS*UsageDescription med ATT (App Tracking Transparency). Usage Description är en begäran om åtkomst till systemresurser (kamera, geoplats, foto), medan ATT är en begäran om spårning (åtkomst till IDFA). ATT använder ett separat ramverk AppTrackingTransparency och nyckeln NSUserTrackingUsageDescription, som inte tillhör NS*UsageDescription.

Gemensamt för dem är att båda använder en systemdialogruta med text som appen inte kan ändra. Skillnaden är att Usage Description fungerar på resursnivå, medan ATT fungerar på enhetsidentifieringsnivå. NS*UsageDescription-nycklar infördes i iOS 6, ATT — i iOS 14.5.

Utveckling av nycklar i olika iOS-versioner

Med varje iOS-utgåva lade Apple till nya skyddade resurser och motsvarande nycklar. iOS 6: kontakter, kalender, påminnelser, foto. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: mediabibliotek, Siri. iOS 11: NFC. iOS 14: spårning (ATT). iOS 17: åtkomst till urklipp (kräver ytterligare bekräftelse).

Viktigt: om en app använder ett API som infördes i en specifik iOS-version, men den lägsta version som stöds är lägre, är nyckeln ändå obligatorisk. iOS kontrollerar att nyckeln finns före det första API-anropet, oavsett vilken version appen körs på.

Vilka NS*UsageDescription-nycklar är obligatoriska

Den fullständiga listan över nycklar beror på vilka funktioner appen använder. Låt oss titta på de 14 viktigaste nycklarna som oftast behövs i mobilappar.

Åtkomst till multimedia

Nyckeln NSCameraUsageDescription — obligatorisk vid åtkomst till kameran via AVCaptureDevice eller UIImagePickerController med källan .camera. Nyckeln NSMicrophoneUsageDescription — vid inspelning av ljud via AVAudioRecorder eller vid inspelning av video med ljud. Båda nycklarna behövs ofta tillsammans om appen spelar in video.

Nyckeln NSPhotoLibraryUsageDescription — vid läsning av foton och videor från användarens mediabibliotek via PHPicker eller UIImagePickerController. Nyckeln NSPhotoLibraryAddUsageDescription — om appen bara sparar foton men inte läser dem. Den första begär läsåtkomst, den andra — endast skrivåtkomst.

Geoplats och navigering

Nyckeln NSLocationWhenInUseUsageDescription — åtkomst till geoplats när appen är aktiv (på skärmen). NSLocationAlwaysAndWhenInUseUsageDescription — alltid åtkomst (inklusive bakgrundsläge). iOS kräver båda nycklarna om alltid åtkomst behövs: först WhenInUse, sedan Always.

Nycklarna NSLocationTemporaryUsageDescription och NSLocationPreciseUsageDescription — extra nycklar för att begära tillfällig åtkomst eller exakt geoplats. Exakt plats kräver separat tillstånd och användaren kan bara aktivera ungefärlig.

Kontakter, kalender och annan data

Nyckeln NSContactsUsageDescription — åtkomst till användarens kontakter via CNContactStore. NSCalendarsUsageDescription — åtkomst till kalendern för att läsa och skapa händelser. NSRemindersUsageDescription — åtkomst till påminnelser. NSBluetoothAlwaysUsageDescription — åtkomst till Bluetooth i bakgrunden (t.ex. för BLE-enheter).

Nyckeln NSHealthShareUsageDescription — åtkomst till att läsa HealthKit-data. NSHealthUpdateUsageDescription — åtkomst till att skriva data till HealthKit. Båda är obligatoriska om appen arbetar inom hälsområdet. Apple kontrollerar noga appar som använder HealthKit och kan avvisa dem om användningsbeskrivningen inte motsvarar funktionaliteten.

Hur formulerar man en korrekt beskrivning

Texten i Usage Description bör vara specifik, sanningsenlig och koncis. Apple ger rekommendationer för formuleringar och moderatorer kontrollerar att de överensstämmer med funktionaliteten.

Struktur för en bra beskrivning

En bra beskrivning består av tre delar: vad appen exakt gör med resursen, varför användaren behöver detta och vilken nytta användaren har av att ge åtkomst. Exempel: “För att ta profilbilder och ladda upp dem till formuläret”. Undvik allmänna fraser: “För att förbättra appens funktion” förklarar inte varför kameran behövs.

Apple förbjuder vilseledande beskrivningar. Om det står “För att ta foton” men appen även spelar in video kan detta betraktas som bedrägeri. Moderatorn kan avvisa appen eller begära förtydligande. I iOS 17 lade Apple till automatisk kontroll: beskrivningen måste innehålla sökord som motsvarar den begärda resursen.

Lokalisering: beskrivningen bör översättas till alla språk som appen stödjer. Om appen är tillgänglig på 10 språk måste varje Usage Description-nyckel ha översättningar i filerna Localizable.strings eller InfoPlist.strings. Apple rekommenderar att använda InfoPlist.strings för lokalisering av Info.plist-nycklar.

Dåliga och bra exempel

• Dåligt: “Åtkomst till kamera krävs” — förklarar inte varför
• Bra: “För att skanna QR-koder vid betalning” — specifikt och tydligt
• Dåligt: “För att bestämma plats” — vagt
• Bra: “För att hitta närmaste restauranger på kartan” — visar värde
• Dåligt: “För att förbättra tjänsten” — inte informativt
• Bra: “För att ladda upp foton i en produktrecension” — specifik handling

Lokalisering via InfoPlist.strings

För lokalisering av Usage Description behöver du inte duplicera Info.plist för varje språk. Skapa en InfoPlist.strings-fil i varje språkkatalog och ange nyckelvärdena. iOS använder automatiskt rätt språk i dialogrutan. Xcode stöder grundlokalisering för Info.plist från och med version 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "För att skanna QR-koder";
"NSPhotoLibraryUsageDescription" =
    "För att ladda upp bilder till profilen";
"NSLocationWhenInUseUsageDescription" =
    "För att visa närliggande butiker på kartan";

Implementering: kod och inställningar

Korrekt implementering av Usage Description innefattar att lägga till nycklar i Info.plist, kontrollera tillståndsstatus i koden och hantera avslag.

Lägga till nycklar via Xcode

Öppna Info.plist i Xcode, hovra över en rad och klicka på “+”. Ange nyckelns namn (t.ex. NSCameraUsageDescription) och ange beskrivningssträngen. Xcode fyller automatiskt i nyckelnamn, vilket minskar risken för stavfel. Efter tilläggning, bygg om projektet och kontrollera att nyckeln visas i den slutgiltiga binärfilen.

Viktigt: nycklar är skiftlägeskänsliga. NSCameraUsageDescription — korrekt, NSCamerausagedescription — fel. En felaktig nyckel ignoreras och appen kraschar vid API-anrop. Använd kopiering från Apples dokumentation eller Xcode-autokomplettering för att undvika stavfel.

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

Hantering av avslag

Om användaren har nekat åtkomst bör appen inte anropa systemdialogrutan igen — det är omöjligt. Visa istället en informationsskärm med en förklaring om hur man aktiverar åtkomst via Inställningar och en knapp “Öppna inställningar” (UIApplicationOpenSettingsURLString). Denna praxis förbättrar användarupplevelsen och ökar sannolikheten att användaren aktiverar åtkomst.

Visa inte en varning med begäran om att aktivera åtkomst omedelbart efter avslag — ge användaren möjlighet att förstå varför de kan behöva denna funktion. Det är bättre att visa en förklaring när användaren försöker använda funktionalitet som kräver det aktuella tillståndet. UX Movement (2023) rekommenderar att visa förklaringsskärmen 2-3 sessioner efter avslag.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Åtkomst till \(feature)",
        message: "Tillåt åtkomst i Inställningar, "
            + "för att använda den här funktionen",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Öppna Inställningar",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Inte nu", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Vad händer om du inte anger Usage Description

Avsaknaden av en obligatorisk Usage Description-nyckel leder till en omedelbar krasch av appen vid det första anropet av motsvarande API. Detta är inte en Xcode-varning, utan en runtime-krasch med undantaget NSInvalidArgumentException och konsolmeddelandet: “This app has crashed because it attempted to access privacy-sensitive data without a usage description”.

Runtime-beteende utan nyckel

iOS kontrollerar förekomsten av NS*UsageDescription-nyckeln i Info.plist vid det första API-anropet för en skyddad resurs. Om nyckeln saknas avslutar systemet omedelbart appen med signalen SIGABRT. Detta händer även på enheter med felsökning — Xcode visar undantaget i loggen, men felsökaren fångar det inte som en brytpunkt.

Kraschen inträffar på riktiga enheter och simulatorn. Det enda sättet att undvika den är att lägga till nyckeln före API-anropet. Xcodes statiska analysator varnar inte alltid för avsaknaden av en nyckel, särskilt om API anropas via tredjeparts-SDK:er. TestFlight-testare kommer också att se kraschen, vilket kan leda till negativa recensioner.

En speciell situation med iOS 17+: Apple införde en extra kontroll för åtkomst till urklipp (UIPasteboard). Om appen läser urklipp utan uttrycklig användaråtgärd visar iOS en varningsbanner, även om Usage Description-nyckeln finns. För urklipp krävs ingen separat nyckel, men Apple rekommenderar att minimera automatisk läsning.

Fel vid App Store-granskning

Förutom runtime-kraschen kan avsaknaden av en nyckel vara en anledning till att appen avvisas vid moderering. Apple kontrollerar Info.plist i granskningsfasen och kan avvisa bygget om det upptäcker API-anrop utan motsvarande nycklar. Xcode blockerar inte arkivering, men App Store Connect kan returnera ett fel vid behandling av binärfilen.

Om appen inte använder resursen direkt, men en tredjeparts-SDK gör det (t.ex. ett analys-SDK begär IDFA), måste utvecklaren ändå lägga till motsvarande nyckel. Apple kontrollerar alla API-anrop i binärfilen, inklusive kod från statiska och dynamiska bibliotek. Felet “Missing Info.plist key” är en av de vanligaste orsakerna till avvisning av uppdateringar.