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). Тази практика подобрява потребителското изживяване и увеличава вероятността потребителят да включи достъпа.

Не показвайте alert с искане за включване на достъпа веднага след отказа — дайте на потребителя възможност да разбере защо може да има нужда от тази функция. По-добре е да покажете обяснение при опит за използване на функционалността, която изисква даденото разрешение. 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, а срив по време на изпълнение с изключение NSInvalidArgumentException и съобщение в конзолата: “This app has crashed because it attempted to access privacy-sensitive data without a usage description”.

Поведение по време на изпълнение без ключ

iOS проверява наличието на ключа NS*UsageDescription в Info.plist при първото извикване на API за защитен ресурс. Ако ключът липсва, системата незабавно прекратява приложението с сигнал SIGABRT. Това се случва дори на устройства за отстраняване на грешки — Xcode показва изключението в лога, но дебъгерът не го хваща като точка на прекъсване.

Сривът се възпроизвежда на реални устройства и симулатор. Единственият начин да го избегнете е да добавите ключа преди извикването на API. Статичният анализатор на Xcode не винаги предупреждава за липсата на ключ, особено ако API се извиква чрез SDK на трети страни. TestFlight тестерите също ще видят срива, което може да доведе до отрицателни отзиви.

Специална ситуация с iOS 17+: Apple въведе допълнителна проверка за достъп до клипборда (UIPasteboard). Ако приложението чете клипборда без изрично действие на потребителя, iOS показва предупредителен банер, дори ако ключът Usage Description присъства. За клипборда не се изисква отделен ключ, но Apple препоръчва минимизиране на автоматичното четене.

Грешки при ревю на App Store

Освен срива по време на изпълнение, липсата на ключ може да бъде причина за отхвърляне на приложението при модериране. Apple проверява Info.plist на етапа на ревю и може да отхвърли билда, ако открие извиквания на API без съответните ключове. Xcode не блокира архивирането, но App Store Connect може да върне грешка при обработката на двоичния файл.

Ако приложението не използва ресурса директно, но SDK на трета страна го прави (напр. аналитично SDK иска IDFA), разработчикът все пак трябва да добави съответния ключ. Apple проверява всички извиквания на API в двоичния файл, включително код от статични и динамични библиотеки. Грешката “Missing Info.plist key” е една от най-честите причини за отхвърляне на актуализации.