Info.plist Usage Description — What It Is, NS*UsageDescription Keys and Setup

What Is Info.plist Usage Description?

Info.plist Usage Description is string values of keys with the NS*UsageDescription prefix that define the text of the system dialog when requesting access to protected iOS resources. When an app first calls an API that requires user permission (e.g., AVCaptureDevice for the camera), iOS shows a dialog with this text and allow/deny buttons.

The description text is the only thing the developer can control in the system dialog. The dialog title “ Would Like to Access [Resource]” is generated by iOS automatically based on the requested resource type. The developer cannot change the title, buttons, or appearance — only the explanation text.

Usage Description is closely tied to the runtime permissions model in iOS. The user grants permission for one request, which can be revoked later via Settings. On a subsequent request, the dialog is not shown again — the app must check the permission status and respond accordingly.

Apple strongly recommends specifying a concrete reason for the access request in the description. For example, “To take profile photos” is better than “To access the camera.” Specific texts increase user trust and the grant rate. According to Localytics (2023), custom descriptions increase consent by 15–25% compared to generic wording.

Usage Description vs. ATT

Do not confuse NS*UsageDescription with ATT (App Tracking Transparency). Usage Description is a request for access to system resources (camera, geolocation, photos), while ATT is a request for tracking (access to IDFA). ATT uses a separate framework AppTrackingTransparency and the NSUserTrackingUsageDescription key, which is not part of NS*UsageDescription.

What they have in common is that both use a system dialog with text that the app cannot modify. The difference is that Usage Description operates at the resource level, while ATT operates at the device identifier level. NS*UsageDescription keys were introduced in iOS 6, ATT — in iOS 14.5.

Evolution of Keys Across iOS Versions

With each iOS release, Apple added new protected resources and corresponding keys. iOS 6: contacts, calendar, reminders, photos. iOS 7: microphone. iOS 8: HomeKit, Health. iOS 10: media library, Siri. iOS 11: NFC. iOS 14: tracking (ATT). iOS 17: clipboard access (requires additional confirmation).

Important: if the app uses an API introduced in a specific iOS version but the minimum supported version is lower, the key is still mandatory. iOS checks for the key before the first API call, regardless of the version the app is running on.

Which NS*UsageDescription Keys Are Mandatory

The full list of keys depends on which features the app uses. Let's review the 14 main keys most commonly required in mobile apps.

Media Access

The NSCameraUsageDescription key is mandatory when accessing the camera via AVCaptureDevice or UIImagePickerController with a .camera source. The NSMicrophoneUsageDescription key is required when recording audio via AVAudioRecorder or shooting video with sound. Both keys are often needed together if the app records video.

The NSPhotoLibraryUsageDescription key is used when reading photos and videos from the user's media library via PHPicker or UIImagePickerController. The NSPhotoLibraryAddUsageDescription key is used if the app only saves photos but does not read them. The first requests read access, the second — write-only access.

Geolocation and Navigation

The NSLocationWhenInUseUsageDescription key provides geolocation access when the app is active (on screen). NSLocationAlwaysAndWhenInUseUsageDescription provides always-on access (including background mode). iOS requires both keys if always-on access is needed: first WhenInUse, then Always.

The NSLocationTemporaryUsageDescription and NSLocationPreciseUsageDescription keys are additional keys for requesting temporary access or precise geolocation. Precise location requires separate permission, and the user can enable only approximate location.

Contacts, Calendar, and Other Data

The NSContactsUsageDescription key provides access to the user's contacts via CNContactStore. NSCalendarsUsageDescription provides calendar access for reading and creating events. NSRemindersUsageDescription provides access to reminders. NSBluetoothAlwaysUsageDescription provides Bluetooth access in the background (e.g., for BLE devices).

The NSHealthShareUsageDescription key provides access to reading HealthKit data. NSHealthUpdateUsageDescription provides access to writing data to HealthKit. Both are required if the app works with health data. Apple carefully reviews apps using HealthKit and may reject the app if the usage description does not match the functionality.

How to Properly Phrase the Description

The text in Usage Description should be specific, truthful, and concise. Apple provides recommendations on phrasing, and reviewers check that they match the functionality.

Structure of a Good Description

A good description consists of three parts: what exactly the app does with the resource, why the user needs it, and what benefit the user gets from granting access. Example: “To take profile photos and upload them to your profile.” Avoid generic phrases: “To improve app performance” does not explain why the camera is needed.

Apple prohibits misleading descriptions. If it says “To take photos” but the app also records video, this may be considered deceptive. The reviewer may reject the app or request clarification. In iOS 17, Apple added automatic validation: the description must contain keywords corresponding to the requested resource.

Localization: the description must be translated into all languages that the app supports. If the app is available in 10 languages, each Usage Description key must have translations in Localizable.strings or InfoPlist.strings files. Apple recommends using InfoPlist.strings for localizing Info.plist keys.

Bad and Good Examples

• Bad: “Needs camera access” — does not explain why
• Good: “To scan QR codes at checkout” — specific and clear
• Bad: “To determine location” — vague
• Good: “To find nearby restaurants on the map” — shows value
• Bad: “To improve service” — uninformative
• Good: “To upload photos to a product review” — specific action

Localization via InfoPlist.strings

To localize Usage Description, you do not need to duplicate Info.plist for each language. Create an InfoPlist.strings file in each language directory and specify the key values. iOS will automatically substitute the correct language in the dialog. Xcode supports base localization for Info.plist starting from version 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "To scan QR codes";
"NSPhotoLibraryUsageDescription" =
    "To upload images to profile";
"NSLocationWhenInUseUsageDescription" =
    "To display nearby stores on the map";

Implementation: Code and Settings

Proper implementation of Usage Description includes adding keys to Info.plist, checking permission status in code, and handling denial.

Adding Keys via Xcode

In Xcode, open Info.plist, hover over a row and click “+”. Enter the key name (e.g., NSCameraUsageDescription) and specify the description string. Xcode autocompletes key names, reducing the risk of typos. After adding, rebuild the project and verify that the key appears in the final binary.

Important: keys are case-sensitive. NSCameraUsageDescription is correct, NSCamerausagedescription is an error. An incorrect key is ignored, and the app will crash when calling the API. Use copy from Apple documentation or Xcode autocomplete to avoid typos.

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

Handling Access Denial

If the user denies access, the app should not call the system dialog again — it is not possible. Instead, show an information screen explaining how to enable access through Settings, with a “Open Settings” button (UIApplicationOpenSettingsURLString). This practice improves user experience and the likelihood that the user will enable access.

Do not show an alert asking to enable access immediately after denial — give the user time to understand why they might need this feature. It is better to show the explanation when attempting to use the functionality that requires this permission. UX Movement (2023) recommends showing the explanation screen 2–3 sessions after denial.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Access to \(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)
}

What Happens If You Don't Specify Usage Description

The absence of a mandatory Usage Description key causes an immediate app crash on the first call to the corresponding API. This is not an Xcode warning but a runtime crash with NSInvalidArgumentException and a console message: “This app has crashed because it attempted to access privacy-sensitive data without a usage description.”

Runtime Behavior Without the Key

iOS checks for the NS*UsageDescription key in Info.plist on the first API call for a protected resource. If the key is missing, the OS immediately terminates the app with a SIGABRT signal. This happens even on debug devices — Xcode shows the exception in the log, but the debugger does not catch it as a breakpoint.

The crash reproduces on real devices and the simulator. The only way to avoid it is to add the key before calling the API. Xcode's static analyzer does not always warn about missing keys, especially if the API is called through third-party SDKs. TestFlight testers will also see the crash, which may lead to negative reviews.

Special situation with iOS 17+: Apple introduced an additional check for clipboard access (UIPasteboard). If the app reads the clipboard without explicit user action, iOS shows a warning banner, even if the Usage Description key is present. Clipboard does not require a separate key, but Apple recommends minimizing automatic reading.

App Store Review Errors

In addition to runtime crashes, the absence of a key may cause app rejection during review. Apple checks Info.plist at the review stage and may reject the build if it detects API calls without corresponding keys. Xcode does not block archiving, but App Store Connect may return an error when processing the binary.

If the app does not use the resource directly but a third-party SDK does (e.g., an analytics SDK requests IDFA), the developer must still add the corresponding key. Apple checks all API calls in the binary, including code from static and dynamic libraries. The error “Missing Info.plist key” is one of the most common reasons for update rejection.