Info.plist Usage Description — что это, ключи NS*UsageDescription и настройка

Что такое Info.plist Usage Description?

Info.plist Usage Description — это строковые значения ключей с префиксом NS*UsageDescription, которые определяют текст системного диалога при запросе доступа к защищённым ресурсам iOS. Когда приложение впервые вызывает API, требующее разрешения пользователя (например, AVCaptureDevice для камеры), iOS показывает диалог с этим текстом и кнопками разрешения или отказа.

Текст описания — единственное, что разработчик может контролировать в системном диалоге. Заголовок диалога «Приложение хочет получить доступ к [ресурсу]» генерируется iOS автоматически на основе типа запрашиваемого ресурса. Разработчик не может изменить заголовок, кнопки или внешний вид — только текст объяснения.

Usage Description тесно связан с моделью runtime permissions в iOS. Пользователь предоставляет разрешение на один запрос, которое может быть отозвано позже через Настройки. При повторном запросе диалог не показывается — приложение должно проверять статус разрешения и реагировать соответствующим образом.

Apple настоятельно рекомендует указывать в описании конкретную причину запроса доступа. Например, «Для съёмки фотографий профиля» лучше, чем «Для доступа к камере». Конкретные тексты повышают доверие пользователя и процент предоставленных разрешений. По данным Localytics (2023), кастомные описания увеличивают согласие на 15-25% по сравнению с общими формулировками.

Отличие Usage Description от ATT

Не путайте NS*UsageDescription с ATT (App Tracking Transparency). Usage Description — это запрос доступа к системным ресурсам (камера, геолокация, фото), а ATT — запрос на отслеживание (доступ к IDFA). ATT использует отдельный фреймворк AppTrackingTransparency и ключ NSUserTrackingUsageDescription, который не относится к NS*UsageDescription.

Общее между ними — оба используют системный диалог с текстом, который приложение не может модифицировать. Разница в том, что Usage Description работает на уровне ресурсов, а ATT — на уровне идентификатора устройства. Ключи NS*UsageDescription были введены с iOS 6, ATT — с iOS 14.5.

Эволюция ключей в разных версиях iOS

С каждым выпуском iOS Apple добавляла новые защищённые ресурсы и соответствующие ключи. iOS 6: контакты, календарь, напоминания, фото. iOS 7: микрофон. iOS 8: HomeKit, Health,. iOS 10: медиатека, Siri. iOS 11: NFC. iOS 14: отслеживание (ATT). iOS 17: доступ к буферу обмена (требует дополнительного подтверждения).

Важно: если приложение использует API, появившееся в определённой версии iOS, но минимальная поддерживаемая версия ниже, ключ всё равно обязателен. iOS проверяет наличие ключа перед первым вызовом API, независимо от версии, на которой запущено приложение.

Какие ключи NS*UsageDescription обязательны

Полный список ключей зависит от того, какие функции использует приложение. Рассмотрим 14 основных ключей, которые чаще всего требуются в мобильных приложениях.

Доступ к мультимедиа

Ключ NSCameraUsageDescription — обязателен при доступе к камере через AVCaptureDevice или UIImagePickerController с источником .camera. Ключ NSMicrophoneUsageDescription — при записи аудио через AVAudioRecorder или при съёмке видео со звуком. Оба ключа часто требуются вместе, если приложение снимает видео.

Ключ NSPhotoLibraryUsageDescription — при чтении фото и видео из пользовательской медиатеки через PHPicker или UIImagePickerController. Ключ NSPhotoLibraryAddUsageDescription — если приложение только сохраняет фото, но не читает их. Первый запрашивает доступ на чтение, второй — только на запись.

Геолокация и навигация

Ключ NSLocationWhenInUseUsageDescription — доступ к геолокации, когда приложение активно (на экране). NSLocationAlwaysAndWhenInUseUsageDescription — доступ всегда (включая фоновый режим). iOS требует оба ключа, если нужен всегдашний доступ: сначала WhenInUse, потом Always.

Ключи NSLocationTemporaryUsageDescription и NSLocationPreciseUsageDescription — дополнительные ключи для запроса временного доступа или точной геолокации. Точная локация требует отдельного разрешения, и пользователь может включить только приблизительную.

Контакты, календарь и другие данные

Ключ NSContactsUsageDescription — доступ к контактам пользователя через CNContactStore. NSCalendarsUsageDescription — доступ к календарю для чтения и создания событий. NSRemindersUsageDescription — доступ к напоминаниям. NSBluetoothAlwaysUsageDescription — доступ к Bluetooth в фоне (например, для BLE-устройств).

Ключ NSHealthShareUsageDescription — доступ к чтению данных HealthKit. NSHealthUpdateUsageDescription — доступ к записи данных в HealthKit. Оба обязательны, если приложение работает со здоровьем. Apple тщательно проверяет приложения, использующие HealthKit, и может отклонить, если описание использования не соответствует функционалу.

Как правильно формулировать описание

Текст в Usage Description должен быть конкретным, правдивым и лаконичным. Apple даёт рекомендации по формулировкам, а модераторы проверяют их соответствие функциональности.

Структура хорошего описания

Хорошее описание состоит из трёх частей: что именно делает приложение с ресурсом, зачем это нужно пользователю, и какая выгода пользователю от предоставления доступа. Пример: «Для съёмки фотографий профиля и их загрузки в анкету». Избегайте общих фраз: «Для улучшения работы приложения» не объясняет, зачем нужна камера.

Apple запрещает вводящие в заблуждение описания. Если написано «Для съёмки фото», но приложение также записывает видео, это может быть расценено как обман. Модератор может отклонить приложение или запросить разъяснения. В iOS 17 Apple добавила автоматическую проверку: описание должно содержать ключевые слова, соответствующие запрашиваемому ресурсу.

Локализация: описание должно быть переведено на все языки, которые поддерживает приложение. Если приложение доступно на 10 языках, каждый ключ Usage Description должен иметь переводы в файлах Localizable.strings или в InfoPlist.strings. Apple рекомендует использовать InfoPlist.strings для локализации ключей Info.plist.

Плохие и хорошие примеры

• Плохо: «Нужен доступ к камере» — не объясняет зачем
• Хорошо: «Для сканирования QR-кодов при оплате» — конкретно и понятно
• Плохо: «Для определения местоположения» — расплывчато
• Хорошо: «Для поиска ближайших ресторанов на карте» — показывает ценность
• Плохо: «Для улучшения сервиса» — неинформативно
• Хорошо: «Для загрузки фотографий в отзыв о товаре» — конкретное действие

Локализация через InfoPlist.strings

Для локализации Usage Description не нужно дублировать Info.plist на каждый язык. Создайте файл InfoPlist.strings в каждом языковом каталоге и укажите значения ключей. iOS автоматически подставит нужный язык в диалог. Xcode поддерживает базовую локализацию для Info.plist начиная с версии 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Для сканирования QR-кодов";
"NSPhotoLibraryUsageDescription" =
    "Для загрузки изображений в профиль";
"NSLocationWhenInUseUsageDescription" =
    "Для отображения ближайших магазинов на карте";

Реализация: код и настройки

Правильная реализация Usage Description включает добавление ключей в Info.plist, проверку статуса разрешения в коде и обработку отказа.

Добавление ключей через Xcode

В Xcode откройте Info.plist, наведите на строку и нажмите «+». Введите название ключа (например, NSCameraUsageDescription) и укажите строку описания. Xcode автодополняет имена ключей, что снижает риск опечаток. После добавления пересоберите проект и проверьте, что ключ отображается в итоговом бинарнике.

Важно: ключи регистрозависимы. NSCameraUsageDescription — верно, NSCamerausagedescription — ошибка. Неверный ключ игнорируется, и приложение упадёт при вызове API. Используйте копирование из документации Apple или автодополнение Xcode для исключения опечаток.

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

Обработка отказа в доступе

Если пользователь отказал в доступе, приложение не должно повторно вызывать системный диалог — это невозможно. Вместо этого покажите информационный экран с объяснением, как включить доступ через Настройки, и кнопку «Открыть настройки» (UIApplicationOpenSettingsURLString). Такая практика повышает user experience и вероятность того, что пользователь включит доступ.

Не показывайте алерт с просьбой включить доступ сразу после отказа — дайте пользователю возможность понять, почему ему может понадобиться эта функция. Лучше показать объяснение при попытке использования функциональности, которая требует данного разрешения. UX Movement (2023) рекомендует показывать экран объяснения через 2-3 сессии после отказа.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Доступ к \(feature)",
        message: "Разрешите доступ в Настройках, "
            + "чтобы использовать эту функцию",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Открыть Настройки",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Не сейчас", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Что будет если не указать Usage Description

Отсутствие обязательного ключа Usage Description приводит к немедленному крашу приложения при первом вызове соответствующего API. Это не предупреждение Xcode, а runtime crash с исключениемNSInvalidArgumentException с сообщением в консоль: «This app has crashed because it attempted to access privacy-sensitive data without a usage description».

Runtime-поведение без ключа

iOS проверяет наличие ключа NS*UsageDescription в Info.plist при первом вызове API для защищённого ресурса. Если ключ отсутствует, ОС немедленно завершает приложение с сигналом SIGABRT. Это происходит даже на устройствах с отладкой — Xcode показывает exception в логе, но отладчик его не ловит как точку останова.

Краш воспроизводится на реальных устройствах и симуляторе. Единственный способ избежать — добавить ключ до вызова API. Статический анализатор Xcode не всегда предупреждает об отсутствии ключа, особенно если API вызывается через сторонние SDK. TestFlight тестеры также увидят краш, что может привести к негативным отзывам.

Особая ситуация с iOS 17+: Apple ввела дополнительную проверку для доступа к буферу обмена (UIPasteboard). Если приложение читает буфер обмена без явного действия пользователя, iOS показывает баннер с предупреждением, даже если ключ Usage Description присутствует. Для буфера обмена отдельный ключ не требуется, но Apple рекомендует минимизировать автоматическое чтение.

Ошибки при ревью App Store

Помимо runtime-краша, отсутствие ключа может стать причиной отклонения приложения при модерации. Apple проверяет Info.plist на этапе ревью и может отклонить сборку, если обнаружит вызовы API без соответствующих ключей. Xcode не блокирует архивацию, но App Store Connect может вернуть ошибку при обработке бинарника.

Если приложение не использует ресурс напрямую, но сторонний SDK делает это (например, SDK аналитики запрашивает IDFA), разработчик всё равно должен добавить соответствующий ключ. Apple проверяет все вызовы API в бинарнике, включая код из статических и динамических библиотек. Ошибка «Missing Info.plist key» — одна из самых частых причин отклонения обновлений.