Info.plist Usage Description — was es ist, NS*UsageDescription-Schlüssel und Einrichtung

Was ist Info.plist Usage Description?

Info.plist Usage Description sind Zeichenfolgenwerte von Schlüsseln mit dem Präfix NS*UsageDescription, die den Text des Systemdialogs beim Anfordern des Zugriffs auf geschützte iOS-Ressourcen definieren. Wenn eine App zum ersten Mal eine API aufruft, die eine Benutzerberechtigung erfordert (z.B. AVCaptureDevice für die Kamera), zeigt iOS einen Dialog mit diesem Text und Erlauben/Ablehnen-Schaltflächen an.

Der Beschreibungstext ist das Einzige, was der Entwickler im Systemdialog steuern kann. Der Dialogs Titel „ möchte auf [Ressource] zugreifen“ wird von iOS automatisch basierend auf dem angeforderten Ressourcentyp generiert. Der Entwickler kann weder Titel, Schaltflächen noch Aussehen ändern — nur den erklärenden Text.

Usage Description ist eng mit dem Modell der Laufzeitberechtigungen in iOS verbunden. Der Benutzer erteilt die Berechtigung für eine Anfrage, die später über die Einstellungen widerrufen werden kann. Bei einer erneuten Anfrage wird der Dialog nicht wieder angezeigt — die App muss den Berechtigungsstatus überprüfen und entsprechend reagieren.

Apple empfiehlt dringend, in der Beschreibung einen konkreten Grund für die Zugriffsanfrage anzugeben. Beispielsweise ist „Zum Aufnehmen von Profilfotos“ besser als „Für den Kamerazugriff“. Spezifische Texte erhöhen das Vertrauen der Benutzer und die Zustimmungsrate. Laut Localytics (2023) erhöhen benutzerdefinierte Beschreibungen die Zustimmung um 15–25% im Vergleich zu allgemeinen Formulierungen.

Unterschied zwischen Usage Description und ATT

Verwechseln Sie NS*UsageDescription nicht mit ATT (App Tracking Transparency). Usage Description ist eine Anfrage für den Zugriff auf Systemressourcen (Kamera, Geolokalisierung, Fotos), während ATT eine Anfrage für Tracking (Zugriff auf IDFA) ist. ATT verwendet ein separates Framework AppTrackingTransparency und den Schlüssel NSUserTrackingUsageDescription, der nicht zu NS*UsageDescription gehört.

Gemeinsam haben beide, dass sie einen Systemdialog mit Text verwenden, den die App nicht ändern kann. Der Unterschied besteht darin, dass Usage Description auf Ressourcenebene arbeitet, während ATT auf der Ebene der Gerätekennung arbeitet. NS*UsageDescription-Schlüssel wurden in iOS 6 eingeführt, ATT — in iOS 14.5.

Entwicklung der Schlüssel in verschiedenen iOS-Versionen

Mit jedem iOS-Release fügte Apple neue geschützte Ressourcen und entsprechende Schlüssel hinzu. iOS 6: Kontakte, Kalender, Erinnerungen, Fotos. iOS 7: Mikrofon. iOS 8: HomeKit, Gesundheit. iOS 10: Medienbibliothek, Siri. iOS 11: NFC. iOS 14: Tracking (ATT). iOS 17: Zwischenablage-Zugriff (erfordert zusätzliche Bestätigung).

Wichtig: Wenn die App eine API verwendet, die in einer bestimmten iOS-Version eingeführt wurde, die mindestens unterstützte Version jedoch niedriger ist, ist der Schlüssel trotzdem obligatorisch. iOS überprüft das Vorhandensein des Schlüssels vor dem ersten API-Aufruf, unabhängig davon, auf welcher Version die App läuft.

Welche NS*UsageDescription-Schlüssel sind obligatorisch

Die vollständige Liste der Schlüssel hängt davon ab, welche Funktionen die App verwendet. Lassen Sie uns die 14 wichtigsten Schlüssel durchgehen, die in mobilen Apps am häufigsten benötigt werden.

Medienzugriff

Der Schlüssel NSCameraUsageDescription ist beim Zugriff auf die Kamera über AVCaptureDevice oder UIImagePickerController mit der Quelle .camera obligatorisch. Der Schlüssel NSMicrophoneUsageDescription ist beim Aufnehmen von Audio über AVAudioRecorder oder beim Aufnehmen von Video mit Ton erforderlich. Beide Schlüssel werden oft zusammen benötigt, wenn die App Video aufnimmt.

Der Schlüssel NSPhotoLibraryUsageDescription wird beim Lesen von Fotos und Videos aus der Medienbibliothek des Benutzers über PHPicker oder UIImagePickerController verwendet. Der Schlüssel NSPhotoLibraryAddUsageDescription wird verwendet, wenn die App nur Fotos speichert, aber nicht liest. Der erste fordert Lesezugriff an, der zweite — nur Schreibzugriff.

Geolokalisierung und Navigation

Der Schlüssel NSLocationWhenInUseUsageDescription bietet Zugriff auf die Geolokalisierung, wenn die App aktiv ist (auf dem Bildschirm). NSLocationAlwaysAndWhenInUseUsageDescription bietet dauerhaften Zugriff (einschließlich Hintergrundmodus). iOS benötigt beide Schlüssel, wenn dauerhafter Zugriff erforderlich ist: zuerst WhenInUse, dann Always.

Die Schlüssel NSLocationTemporaryUsageDescription und NSLocationPreciseUsageDescription sind zusätzliche Schlüssel für die Anforderung temporären Zugriffs oder präziser Geolokalisierung. Der genaue Standort erfordert eine separate Berechtigung, und der Benutzer kann nur den ungefähren Standort aktivieren.

Kontakte, Kalender und andere Daten

Der Schlüssel NSContactsUsageDescription bietet Zugriff auf die Kontakte des Benutzers über CNContactStore. NSCalendarsUsageDescription bietet Kalenderzugriff zum Lesen und Erstellen von Ereignissen. NSRemindersUsageDescription bietet Zugriff auf Erinnerungen. NSBluetoothAlwaysUsageDescription bietet Bluetooth-Zugriff im Hintergrund (z.B. für BLE-Geräte).

Der Schlüssel NSHealthShareUsageDescription bietet Zugriff zum Lesen von HealthKit-Daten. NSHealthUpdateUsageDescription bietet Zugriff zum Schreiben von Daten in HealthKit. Beide sind obligatorisch, wenn die App mit Gesundheitsdaten arbeitet. Apple überprüft Apps, die HealthKit verwenden, sorgfältig und kann die App ablehnen, wenn die Nutzungsbeschreibung nicht mit der Funktionalität übereinstimmt.

Wie formuliert man die Beschreibung richtig

Der Text in Usage Description sollte spezifisch, wahrheitsgemäß und prägnant sein. Apple gibt Empfehlungen zur Formulierung, und die Prüfer überprüfen die Übereinstimmung mit der Funktionalität.

Aufbau einer guten Beschreibung

Eine gute Beschreibung besteht aus drei Teilen: was genau die App mit der Ressource macht, warum der Benutzer sie braucht, und welchen Nutzen der Benutzer durch die Gewährung des Zugriffs hat. Beispiel: „Zum Aufnehmen von Profilfotos und Hochladen in Ihr Profil.“ Vermeiden Sie allgemeine Formulierungen: „Zur Verbesserung der App-Leistung“ erklärt nicht, warum die Kamera benötigt wird.

Apple verbietet irreführende Beschreibungen. Wenn dort „Zum Aufnehmen von Fotos“ steht, die App aber auch Video aufnimmt, kann dies als täuschend angesehen werden. Der Prüfer kann die App ablehnen oder Klärung anfordern. In iOS 17 fügte Apple eine automatische Überprüfung hinzu: Die Beschreibung muss Schlüsselwörter enthalten, die der angeforderten Ressource entsprechen.

Lokalisierung: Die Beschreibung muss in alle Sprachen übersetzt werden, die die App unterstützt. Wenn die App in 10 Sprachen verfügbar ist, muss jeder Usage-Description-Schlüssel Übersetzungen in Localizable.strings- oder InfoPlist.strings-Dateien haben. Apple empfiehlt, InfoPlist.strings für die Lokalisierung von Info.plist-Schlüsseln zu verwenden.

Schlechte und gute Beispiele

• Schlecht: „Benötigt Kamerazugriff“ — erklärt nicht warum
• Gut: „Zum Scannen von QR-Codes bei der Zahlung“ — spezifisch und klar
• Schlecht: „Zur Standortbestimmung“ — vage
• Gut: „Zum Finden nahegelegener Restaurants auf der Karte“ — zeigt den Wert
• Schlecht: „Zur Verbesserung des Dienstes“ — nicht informativ
• Gut: „Zum Hochladen von Fotos in eine Produktbewertung“ — spezifische Aktion

Lokalisierung über InfoPlist.strings

Zur Lokalisierung von Usage Description müssen Sie Info.plist nicht für jede Sprache duplizieren. Erstellen Sie eine InfoPlist.strings-Datei in jedem Sprachverzeichnis und geben Sie die Schlüsselwerte an. iOS wird automatisch die richtige Sprache im Dialog verwenden. Xcode unterstützt Basislokalisierung für Info.plist ab Version 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Zum Scannen von QR-Codes";
"NSPhotoLibraryUsageDescription" =
    "Zum Hochladen von Bildern ins Profil";
"NSLocationWhenInUseUsageDescription" =
    "Zum Anzeigen nahegelegener Geschäfte auf der Karte";

Implementierung: Code und Einstellungen

Die korrekte Implementierung von Usage Description umfasst das Hinzufügen von Schlüsseln zu Info.plist, die Überprüfung des Berechtigungsstatus im Code und die Behandlung von Verweigerungen.

Hinzufügen von Schlüsseln über Xcode

Öffnen Sie in Xcode Info.plist, fahren Sie mit der Maus über eine Zeile und klicken Sie auf „+“. Geben Sie den Schlüsselnamen ein (z.B. NSCameraUsageDescription) und geben Sie die Beschreibungszeichenfolge an. Xcode vervollständigt Schlüsselnamen automatisch, was das Tippfehlerrisiko verringert. Nach dem Hinzufügen erstellen Sie das Projekt neu und überprüfen, ob der Schlüssel im endgültigen Binärfile erscheint.

Wichtig: Schlüssel sind case-sensitive. NSCameraUsageDescription ist korrekt, NSCamerausagedescription ist ein Fehler. Ein falscher Schlüssel wird ignoriert, und die App stürzt beim API-Aufruf ab. Verwenden Sie Kopien aus der Apple-Dokumentation oder die Xcode-Autovervollständigung, um Tippfehler zu vermeiden.

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

Behandlung von Zugriffsverweigerung

Wenn der Benutzer den Zugriff verweigert, sollte die App den Systemdialog nicht erneut aufrufen — das ist nicht möglich. Zeigen Sie stattdessen einen Informationsbildschirm, der erklärt, wie der Zugriff über die Einstellungen aktiviert werden kann, mit einer Schaltfläche „Einstellungen öffnen“ (UIApplicationOpenSettingsURLString). Diese Vorgehensweise verbessert die Benutzererfahrung und die Wahrscheinlichkeit, dass der Benutzer den Zugriff aktiviert.

Zeigen Sie nicht sofort nach der Verweigerung einen Alarm, der um die Aktivierung des Zugriffs bittet — geben Sie dem Benutzer Zeit zu verstehen, warum er diese Funktion benötigen könnte. Zeigen Sie die Erklärung besser beim Versuch, die Funktion zu nutzen, die diese Berechtigung erfordert. UX Movement (2023) empfiehlt, den Erklärungsbildschirm 2–3 Sitzungen nach der Verweigerung anzuzeigen.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Zugriff auf \(feature)",
        message: "Allow access in Settings, "
            + "to use this feature",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Open Settings",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Not now", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Was passiert, wenn man Usage Description nicht angibt

Das Fehlen eines obligatorischen Usage-Description-Schlüssels führt zu einem sofortigen App-Absturz beim ersten Aufruf der entsprechenden API. Dies ist keine Xcode-Warnung, sondern ein Laufzeitabsturz mit NSInvalidArgumentException und einer Konsolenmeldung: „Diese App ist abgestürzt, weil sie versucht hat, auf datenschutzsensible Daten ohne eine Nutzungsbeschreibung zuzugreifen.“

Laufzeitverhalten ohne Schlüssel

iOS überprüft das Vorhandensein des NS*UsageDescription-Schlüssels in Info.plist beim ersten API-Aufruf für eine geschützte Ressource. Wenn der Schlüssel fehlt, beendet das Betriebssystem die App sofort mit einem SIGABRT-Signal. Dies geschieht sogar auf Debug-Geräten — Xcode zeigt die Ausnahme im Log an, aber der Debugger fängt sie nicht als Breakpoint.

Der Absturz ist auf echten Geräten und im Simulator reproduzierbar. Die einzige Möglichkeit, ihn zu vermeiden, ist das Hinzufügen des Schlüssels vor dem API-Aufruf. Der statische Analysator von Xcode warnt nicht immer vor fehlenden Schlüsseln, besonders wenn die API über Drittanbieter-SDKs aufgerufen wird. TestFlight-Tester werden den Absturz ebenfalls sehen, was zu negativen Bewertungen führen kann.

Besondere Situation mit iOS 17+: Apple führte eine zusätzliche Überprüfung für den Zugriff auf die Zwischenablage (UIPasteboard) ein. Wenn die App die Zwischenablage ohne explizite Benutzeraktion liest, zeigt iOS ein Warnbanner an, selbst wenn der Usage-Description-Schlüssel vorhanden ist. Die Zwischenablage erfordert keinen separaten Schlüssel, aber Apple empfiehlt, das automatische Lesen zu minimieren.

Fehler bei der App Store-Überprüfung

Neben dem Laufzeitabsturz kann das Fehlen eines Schlüssels zur Ablehnung der App während der Überprüfung führen. Apple überprüft Info.plist in der Überprüfungsphase und kann den Build ablehnen, wenn API-Aufrufe ohne entsprechende Schlüssel erkannt werden. Xcode blockiert die Archivierung nicht, aber App Store Connect kann bei der Verarbeitung des Binärfiles einen Fehler zurückgeben.

Wenn die App die Ressource nicht direkt nutzt, aber ein Drittanbieter-SDK dies tut (z.B. ein Analyse-SDK fordert IDFA an), muss der Entwickler trotzdem den entsprechenden Schlüssel hinzufügen. Apple überprüft alle API-Aufrufe im Binärfile, einschließlich Code aus statischen und dynamischen Bibliotheken. Der Fehler „Fehlender Info.plist-Schlüssel“ ist einer der häufigsten Gründe für die Ablehnung von Updates.