Info.plist Usage Description — wat is het, NS*UsageDescription-sleutels en configuratie

Wat is Info.plist Usage Description?

Info.plist Usage Description — zijn de stringwaarden van sleutels met het voorvoegsel NS*UsageDescription die de tekst bepalen van het systeemdialoogvenster bij het aanvragen van toegang tot beschermde iOS-bronnen. Wanneer een app voor het eerst een API aanroept die toestemming van de gebruiker vereist (bijv. AVCaptureDevice voor de camera), toont iOS een dialoogvenster met deze tekst en knoppen voor toestaan of weigeren.

De beschrijvingstekst is het enige dat de ontwikkelaar kan beheren in het systeemdialoogvenster. De titel van het dialoogvenster “App wil toegang krijgen tot [bron]” wordt automatisch gegenereerd door iOS op basis van het type aangevraagde bron. De ontwikkelaar kan de titel, knoppen of het uiterlijk niet wijzigen — alleen de uitlegtekst.

Usage Description is nauw verbonden met het runtime permissions-model in iOS. De gebruiker verleent toestemming voor een aanvraag, die later via Instellingen kan worden ingetrokken. Bij een herhaalde aanvraag wordt het dialoogvenster niet getoond — de app moet de toestemmingsstatus controleren en passend reageren.

Apple raadt ten zeerste aan om in de beschrijving een specifieke reden voor de toegangsaanvraag te vermelden. Bijvoorbeeld “Voor het maken van profielfoto’s” is beter dan “Voor toegang tot de camera”. Specifieke teksten verhogen het vertrouwen van de gebruiker en het percentage verleende toestemmingen. Volgens gegevens van Localytics (2023) verhogen aangepaste beschrijvingen de toestemming met 15-25% in vergelijking met algemene formuleringen.

Verschil tussen Usage Description en ATT

Verwar NS*UsageDescription niet met ATT (App Tracking Transparency). Usage Description is een aanvraag voor toegang tot systeembronnen (camera, geolocatie, foto), terwijl ATT een aanvraag voor tracking is (toegang tot IDFA). ATT gebruikt een apart framework AppTrackingTransparency en de sleutel NSUserTrackingUsageDescription, die niet bij NS*UsageDescription hoort.

Wat ze gemeen hebben is dat beide gebruikmaken van een systeemdialoogvenster met tekst die de app niet kan wijzigen. Het verschil is dat Usage Description op bronniveau werkt, terwijl ATT op apparaat-id-niveau werkt. NS*UsageDescription-sleutels zijn geïntroduceerd in iOS 6, ATT — in iOS 14.5.

Evolutie van sleutels in verschillende iOS-versies

Met elke iOS-release voegde Apple nieuwe beschermde bronnen en bijbehorende sleutels toe. iOS 6: contacten, agenda, herinneringen, foto. iOS 7: microfoon. iOS 8: HomeKit, Health. iOS 10: mediatheek, Siri. iOS 11: NFC. iOS 14: tracking (ATT). iOS 17: toegang tot klembord (vereist extra bevestiging).

Belangrijk: als een app een API gebruikt die in een bepaalde iOS-versie is geïntroduceerd, maar de minimaal ondersteunde versie lager is, is de sleutel nog steeds verplicht. iOS controleert de aanwezigheid van de sleutel vóór de eerste API-aanroep, ongeacht de versie waarop de app draait.

Welke NS*UsageDescription-sleutels zijn verplicht

De volledige lijst met sleutels hangt af van welke functies de app gebruikt. Laten we de 14 belangrijkste sleutels bekijken die het vaakst nodig zijn in mobiele apps.

Toegang tot multimedia

Sleutel NSCameraUsageDescription — verplicht bij toegang tot de camera via AVCaptureDevice of UIImagePickerController met bron .camera. Sleutel NSMicrophoneUsageDescription — bij het opnemen van audio via AVAudioRecorder of bij het opnemen van video met geluid. Beide sleutels zijn vaak samen nodig als de app video opneemt.

Sleutel NSPhotoLibraryUsageDescription — bij het lezen van foto’s en video’s uit de mediatheek van de gebruiker via PHPicker of UIImagePickerController. Sleutel NSPhotoLibraryAddUsageDescription — als de app alleen foto’s opslaat maar ze niet leest. De eerste vraagt leestoegang aan, de tweede — alleen schrijftoegang.

Geolocatie en navigatie

Sleutel NSLocationWhenInUseUsageDescription — toegang tot geolocatie wanneer de app actief is (op het scherm). NSLocationAlwaysAndWhenInUseUsageDescription — altijd toegang (inclusief achtergrond). iOS vereist beide sleutels als altijd toegang nodig is: eerst WhenInUse, dan Always.

Sleutels NSLocationTemporaryUsageDescription en NSLocationPreciseUsageDescription — extra sleutels voor het aanvragen van tijdelijke toegang of nauwkeurige geolocatie. Nauwkeurige locatie vereist aparte toestemming en de gebruiker kan alleen bij benadering inschakelen.

Contacten, agenda en andere gegevens

Sleutel NSContactsUsageDescription — toegang tot contacten van de gebruiker via CNContactStore. NSCalendarsUsageDescription — toegang tot de agenda voor het lezen en maken van evenementen. NSRemindersUsageDescription — toegang tot herinneringen. NSBluetoothAlwaysUsageDescription — toegang tot Bluetooth op de achtergrond (bijv. voor BLE-apparaten).

Sleutel NSHealthShareUsageDescription — toegang tot het lezen van HealthKit-gegevens. NSHealthUpdateUsageDescription — toegang tot het schrijven van gegevens naar HealthKit. Beide zijn verplicht als de app actief is op het gebied van gezondheid. Apple controleert apps die HealthKit gebruiken nauwkeurig en kan ze afwijzen als de gebruiksbeschrijving niet overeenkomt met de functionaliteit.

Hoe formuleert u een correcte beschrijving

De tekst in Usage Description moet specifiek, waarheidsgetrouw en beknopt zijn. Apple geeft aanbevelingen voor formuleringen en moderators controleren of ze overeenkomen met de functionaliteit.

Structuur van een goede beschrijving

Een goede beschrijving bestaat uit drie delen: wat de app precies met de bron doet, waarom de gebruiker dit nodig heeft en welk voordeel de gebruiker heeft bij het verlenen van toegang. Voorbeeld: “Voor het maken van profielfoto’s en het uploaden ervan naar het formulier”. Vermijd algemene zinnen: “Ter verbetering van de app” legt niet uit waarom de camera nodig is.

Apple verbiedt misleidende beschrijvingen. Als er “Voor het maken van foto’s” staat maar de app neemt ook video op, kan dit als misleidend worden beschouwd. De moderator kan de app afwijzen of om opheldering vragen. In iOS 17 heeft Apple automatische controle toegevoegd: de beschrijving moet trefwoorden bevatten die overeenkomen met de aangevraagde bron.

Lokalisatie: de beschrijving moet worden vertaald naar alle talen die de app ondersteunt. Als de app in 10 talen beschikbaar is, moet elke Usage Description-sleutel vertalingen hebben in Localizable.strings of InfoPlist.strings-bestanden. Apple beveelt het gebruik van InfoPlist.strings aan voor lokalisatie van Info.plist-sleutels.

Slechte en goede voorbeelden

• Slecht: “Toegang tot camera vereist” — legt niet uit waarom
• Goed: “Voor het scannen van QR-codes bij betaling” — specifiek en duidelijk
• Slecht: “Voor het bepalen van de locatie” — vaag
• Goed: “Voor het vinden van dichtstbijzijnde restaurants op de kaart” — toont waarde
• Slecht: “Voor het verbeteren van de service” — niet informatief
• Goed: “Voor het uploaden van foto’s in een productrecensie” — specifieke actie

Lokalisatie via InfoPlist.strings

Voor lokalisatie van Usage Description hoeft Info.plist niet voor elke taal te worden gedupliceerd. Maak een InfoPlist.strings-bestand in elke taalmap en geef de sleutelwaarden op. iOS gebruikt automatisch de juiste taal in het dialoogvenster. Xcode ondersteunt basislokalisatie voor Info.plist vanaf versie 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Voor het scannen van QR-codes";
"NSPhotoLibraryUsageDescription" =
    "Voor het uploaden van afbeeldingen naar het profiel";
"NSLocationWhenInUseUsageDescription" =
    "Voor het tonen van dichtstbijzijnde winkels op de kaart";

Implementatie: code en instellingen

Correcte implementatie van Usage Description omvat het toevoegen van sleutels aan Info.plist, het controleren van de toestemmingsstatus in code en het afhandelen van weigering.

Sleutels toevoegen via Xcode

Open in Xcode Info.plist, ga op een regel staan en klik op “+”. Voer de sleutelnaam in (bijv. NSCameraUsageDescription) en geef de beschrijvingsstring op. Xcode vult sleutelnamen automatisch aan, wat het risico op typefouten vermindert. Bouw het project opnieuw en controleer of de sleutel in het uiteindelijke binaire bestand wordt weergegeven.

Belangrijk: sleutels zijn hoofdlettergevoelig. NSCameraUsageDescription — correct, NSCamerausagedescription — fout. Een onjuiste sleutel wordt genegeerd en de app crasht bij API-aanroep. Gebruik kopiëren uit Apple-documentatie of Xcode-autocompletie om typefouten te voorkomen.

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

Afhandeling van toegangsweigering

Als de gebruiker de toegang heeft geweigerd, mag de app het systeemdialoogvenster niet opnieuw aanroepen — dat is onmogelijk. Toon in plaats daarvan een informatiescherm met uitleg over hoe toegang in te schakelen via Instellingen en een knop “Open instellingen” (UIApplicationOpenSettingsURLString). Deze praktijk verbetert de gebruikerservaring en vergroot de kans dat de gebruiker toegang inschakelt.

Toon niet direct na weigering een alert met het verzoek om toegang in te schakelen — geef de gebruiker de kans om te begrijpen waarom deze functie nodig kan zijn. Het is beter om uitleg te tonen bij een poging om functionaliteit te gebruiken die de betreffende toestemming vereist. UX Movement (2023) raadt aan om het uitlegscherm 2-3 sessies na weigering te tonen.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Toegang tot \(feature)",
        message: "Sta toegang toe in Instellingen, "
            + "om deze functie te gebruiken",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Open Instellingen",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Niet nu", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Wat gebeurt er als u geen Usage Description toevoegt

Het ontbreken van een verplichte Usage Description-sleutel leidt tot een onmiddellijke crash van de app bij de eerste aanroep van de bijbehorende API. Dit is geen Xcode-waarschuwing, maar een runtime crash met de uitzondering NSInvalidArgumentException en het consolebericht: “This app has crashed because it attempted to access privacy-sensitive data without a usage description”.

Runtime-gedrag zonder sleutel

iOS controleert de aanwezigheid van de NS*UsageDescription-sleutel in Info.plist bij de eerste API-aanroep voor een beschermde bron. Als de sleutel ontbreekt, beëindigt het systeem de app onmiddellijk met signaal SIGABRT. Dit gebeurt zelfs op apparaten met debugging — Xcode toont de uitzondering in de log, maar de debugger vangt het niet als breekpunt.

De crash treedt op op echte apparaten en de simulator. De enige manier om dit te voorkomen is de sleutel toevoegen vóór de API-aanroep. De statische analyser van Xcode waarschuwt niet altijd voor het ontbreken van een sleutel, vooral als de API via SDK’s van derden wordt aangeroepen. TestFlight-testers zullen de crash ook zien, wat kan leiden tot negatieve recensies.

Een speciale situatie met iOS 17+: Apple heeft een extra controle toegevoegd voor toegang tot het klembord (UIPasteboard). Als de app het klembord leest zonder expliciete gebruikersactie, toont iOS een waarschuwingsbanner, zelfs als de Usage Description-sleutel aanwezig is. Voor het klembord is geen aparte sleutel vereist, maar Apple raadt aan om automatisch lezen te minimaliseren.

Fouten bij App Store-beoordeling

Naast de runtime-crash kan het ontbreken van een sleutel een reden zijn voor afwijzing van de app tijdens moderatie. Apple controleert Info.plist in de beoordelingsfase en kan de build afwijzen als het API-aanroepen zonder bijbehorende sleutels detecteert. Xcode blokkeert archivering niet, maar App Store Connect kan een fout retourneren bij verwerking van het binaire bestand.

Als de app de bron niet direct gebruikt, maar een SDK van derden doet dit (bijv. een analytische SDK vraagt IDFA), moet de ontwikkelaar alsnog de bijbehorende sleutel toevoegen. Apple controleert alle API-aanroepen in het binaire bestand, inclusief code uit statische en dynamische bibliotheken. De fout “Missing Info.plist key” is een van de meest voorkomende redenen voor afwijzing van updates.