Info.plist Usage Description — co to jest, klucze NS*UsageDescription i konfiguracja

Co to jest Info.plist Usage Description?

Info.plist Usage Description — to wartości ciągów kluczy z prefiksem NS*UsageDescription, które określają tekst systemowego okna dialogowego przy żądaniu dostępu do chronionych zasobów iOS. Gdy aplikacja po raz pierwszy wywołuje API wymagające zgody użytkownika (np. AVCaptureDevice dla aparatu), iOS wyświetla okno dialogowe z tym tekstem oraz przyciskami zezwolenia lub odmowy.

Tekst opisu to jedyne, co deweloper może kontrolować w systemowym oknie dialogowym. Tytuł okna dialogowego „Aplikacja chce uzyskać dostęp do [zasobu]” jest generowany automatycznie przez iOS na podstawie typu żądanego zasobu. Deweloper nie może zmienić tytułu, przycisków ani wyglądu — tylko tekst wyjaśnienia.

Usage Description jest ściśle związany z modelem runtime permissions w iOS. Użytkownik udziela zezwolenia na jedno żądanie, które może zostać później cofnięte przez Ustawienia. Przy ponownym żądaniu okno dialogowe nie jest wyświetlane — aplikacja musi sprawdzać status zezwolenia i odpowiednio reagować.

Apple zdecydowanie zaleca podanie w opisie konkretnego powodu żądania dostępu. Na przykład „Do robienia zdjęć profilowych” jest lepsze niż „Aby uzyskać dostęp do aparatu”. Konkretne teksty zwiększają zaufanie użytkownika i odsetek udzielonych zezwoleń. Według danych Localytics (2023), niestandardowe opisy zwiększają zgodę o 15-25% w porównaniu z ogólnymi sformułowaniami.

Różnica między Usage Description a ATT

Nie myl NS*UsageDescription z ATT (App Tracking Transparency). Usage Description to żądanie dostępu do zasobów systemowych (aparat, geolokalizacja, zdjęcia), a ATT to żądanie śledzenia (dostęp do IDFA). ATT używa oddzielnego frameworka AppTrackingTransparency i klucza NSUserTrackingUsageDescription, który nie należy do NS*UsageDescription.

Łączy je to, że oba używają systemowego okna dialogowego z tekstem, którego aplikacja nie może modyfikować. Różnica polega na tym, że Usage Description działa na poziomie zasobów, a ATT na poziomie identyfikatora urządzenia. Klucze NS*UsageDescription zostały wprowadzone w iOS 6, ATT — w iOS 14.5.

Ewolucja kluczy w różnych wersjach iOS

Z każdą wersją iOS Apple dodawała nowe chronione zasoby i odpowiednie klucze. iOS 6: kontakty, kalendarz, przypomnienia, zdjęcia. iOS 7: mikrofon. iOS 8: HomeKit, Health. iOS 10: biblioteka multimediów, Siri. iOS 11: NFC. iOS 14: śledzenie (ATT). iOS 17: dostęp do schowka (wymaga dodatkowego potwierdzenia).

Warto wiedzieć: jeśli aplikacja używa API wprowadzonego w określonej wersji iOS, ale minimalna obsługiwana wersja jest niższa, klucz i tak jest obowiązkowy. iOS sprawdza obecność klucza przed pierwszym wywołaniem API, niezależnie od wersji, na której działa aplikacja.

Które klucze NS*UsageDescription są obowiązkowe

Pełna lista kluczy zależy od tego, jakie funkcje wykorzystuje aplikacja. Omówimy 14 głównych kluczy, które najczęściej są wymagane w aplikacjach mobilnych.

Dostęp do multimediów

Klucz NSCameraUsageDescription — obowiązkowy przy dostępie do aparatu przez AVCaptureDevice lub UIImagePickerController ze źródłem .camera. Klucz NSMicrophoneUsageDescription — przy nagrywaniu dźwięku przez AVAudioRecorder lub przy nagrywaniu wideo z dźwiękiem. Oba klucze są często wymagane razem, jeśli aplikacja nagrywa wideo.

Klucz NSPhotoLibraryUsageDescription — przy odczytywaniu zdjęć i wideo z biblioteki multimediów użytkownika przez PHPicker lub UIImagePickerController. Klucz NSPhotoLibraryAddUsageDescription — jeśli aplikacja tylko zapisuje zdjęcia, ale ich nie odczytuje. Pierwszy żąda dostępu do odczytu, drugi — tylko do zapisu.

Geolokalizacja i nawigacja

Klucz NSLocationWhenInUseUsageDescription — dostęp do geolokalizacji, gdy aplikacja jest aktywna (na ekranie). NSLocationAlwaysAndWhenInUseUsageDescription — dostęp zawsze (w tym w tle). iOS wymaga obu kluczy, jeśli potrzebny jest stały dostęp: najpierw WhenInUse, potem Always.

Klucze NSLocationTemporaryUsageDescription i NSLocationPreciseUsageDescription — dodatkowe klucze do żądania tymczasowego dostępu lub dokładnej geolokalizacji. Dokładna lokalizacja wymaga osobnego zezwolenia, a użytkownik może włączyć tylko przybliżoną.

Kontakty, kalendarz i inne dane

Klucz NSContactsUsageDescription — dostęp do kontaktów użytkownika przez CNContactStore. NSCalendarsUsageDescription — dostęp do kalendarza w celu odczytu i tworzenia wydarzeń. NSRemindersUsageDescription — dostęp do przypomnień. NSBluetoothAlwaysUsageDescription — dostęp do Bluetooth w tle (np. dla urządzeń BLE).

Klucz NSHealthShareUsageDescription — dostęp do odczytu danych HealthKit. NSHealthUpdateUsageDescription — dostęp do zapisu danych w HealthKit. Oba są obowiązkowe, jeśli aplikacja działa w obszarze zdrowia. Apple dokładnie sprawdza aplikacje korzystające z HealthKit i może odrzucić je, jeśli opis użycia nie odpowiada funkcjonalności.

Jak poprawnie formułować opis

Tekst w Usage Description powinien być konkretny, zgodny z prawdą i zwięzły. Apple podaje zalecenia dotyczące sformułowań, a moderatorzy sprawdzają ich zgodność z funkcjonalnością.

Struktura dobrego opisu

Dobry opis składa się z trzech części: co dokładnie aplikacja robi z zasobem, dlaczego jest to potrzebne użytkownikowi i jaka korzyść dla użytkownika z udzielenia dostępu. Przykład: „Do robienia zdjęć profilowych i ich przesyłania do ankiety". Unikaj ogólników: „W celu ulepszenia działania aplikacji" nie wyjaśnia, po co potrzebny jest aparat.

Apple zabrania wprowadzających w błąd opisów. Jeśli napisano „Do robienia zdjęć", ale aplikacja nagrywa również wideo, może to zostać uznane za oszustwo. Moderator może odrzucić aplikację lub zażądać wyjaśnień. W iOS 17 Apple dodał automatyczne sprawdzanie: opis musi zawierać słowa kluczowe odpowiadające żądanemu zasobowi.

Lokalizacja: opis powinien być przetłumaczony na wszystkie języki obsługiwane przez aplikację. Jeśli aplikacja jest dostępna w 10 językach, każdy klucz Usage Description musi mieć tłumaczenia w plikach Localizable.strings lub InfoPlist.strings. Apple zaleca używanie InfoPlist.strings do lokalizacji kluczy Info.plist.

Złe i dobre przykłady

• Źle: „Wymagany dostęp do aparatu" — nie wyjaśnia po co
• Dobrze: „Do skanowania kodów QR przy płatności" — konkretnie i zrozumiale
• Źle: „W celu określenia lokalizacji" — nieprecyzyjnie
• Dobrze: „Do wyszukiwania najbliższych restauracji na mapie" — pokazuje wartość
• Źle: „W celu ulepszenia usługi" — nieinformacyjnie
• Dobrze: „Do przesyłania zdjęć w opinii o produkcie" — konkretne działanie

Lokalizacja przez InfoPlist.strings

Do lokalizacji Usage Description nie trzeba powielać Info.plist na każdy język. Utwórz plik InfoPlist.strings w każdym katalogu językowym i podaj wartości kluczy. iOS automatycznie podstawi odpowiedni język w oknie dialogowym. Xcode obsługuje lokalizację podstawową dla Info.plist od wersji 14.

<!-- InfoPlist.strings (Russian) -->
"NSCameraUsageDescription" =
    "Do skanowania kodów QR";
"NSPhotoLibraryUsageDescription" =
    "Do przesyłania zdjęć do profilu";
"NSLocationWhenInUseUsageDescription" =
    "Do wyświetlania najbliższych sklepów na mapie";

Implementacja: kod i ustawienia

Poprawna implementacja Usage Description obejmuje dodanie kluczy do Info.plist, sprawdzenie statusu zezwolenia w kodzie i obsługę odmowy.

Dodawanie kluczy przez Xcode

W Xcode otwórz Info.plist, najedź na wiersz i kliknij „+". Wprowadź nazwę klucza (np. NSCameraUsageDescription) i podaj ciąg opisu. Xcode automatycznie uzupełnia nazwy kluczy, co zmniejsza ryzyko literówek. Po dodaniu przebuduj projekt i sprawdź, czy klucz wyświetla się w końcowym pliku binarnym.

Ważne: klucze są rozróżniane pod względem wielkości liter. NSCameraUsageDescription — poprawnie, NSCamerausagedescription — błąd. Nieprawidłowy klucz jest ignorowany, a aplikacja ulegnie awarii przy wywołaniu API. Używaj kopiowania z dokumentacji Apple lub autouzupełniania Xcode, aby uniknąć literówek.

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

Obsługa odmowy dostępu

Jeśli użytkownik odmówił dostępu, aplikacja nie powinna ponownie wywoływać systemowego okna dialogowego — jest to niemożliwe. Zamiast tego wyświetl ekran informacyjny z wyjaśnieniem, jak włączyć dostęp przez Ustawienia, oraz przycisk „Otwórz ustawienia" (UIApplicationOpenSettingsURLString). Taka praktyka poprawia user experience i zwiększa prawdopodobieństwo, że użytkownik włączy dostęp.

Nie wyświetlaj alertu z prośbą o włączenie dostępu natychmiast po odmowie — daj użytkownikowi możliwość zrozumienia, dlaczego może potrzebować tej funkcji. Lepiej pokazać wyjaśnienie przy próbie użycia funkcjonalności wymagającej danego zezwolenia. UX Movement (2023) zaleca pokazanie ekranu wyjaśnienia po 2-3 sesjach od odmowy.

func showSettingsAlert(for feature: String) {
    let alert = UIAlertController(
        title: "Dostęp do \(feature)",
        message: "Zezwól na dostęp w Ustawieniach, "
            + "aby korzystać z tej funkcji",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(
        title: "Otwórz Ustawienia",
        style: .default
    ) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })
    alert.addAction(UIAlertAction(
        title: "Nie teraz", style: .cancel
    ))
    UIApplication.shared.keyWindow?.rootViewController?.present(alert, animated: true)
}

Co się stanie, jeśli nie podasz Usage Description

Brak obowiązkowego klucza Usage Description prowadzi do natychmiastowego crasha aplikacji przy pierwszym wywołaniu odpowiedniego API. To nie ostrzeżenie Xcode, a runtime crash z wyjątkiem NSInvalidArgumentException z komunikatem w konsoli: „This app has crashed because it attempted to access privacy-sensitive data without a usage description".

Zachowanie w czasie wykonania bez klucza

iOS sprawdza obecność klucza NS*UsageDescription w Info.plist przy pierwszym wywołaniu API dla chronionego zasobu. Jeśli klucz jest nieobecny, system natychmiast kończy aplikację sygnałem SIGABRT. Dzieje się tak nawet na urządzeniach z debuggingiem — Xcode pokazuje wyjątek w logu, ale debugger nie łapie go jako punktu przerwania.

Crash występuje na rzeczywistych urządzeniach i symulatorze. Jedynym sposobem uniknięcia go jest dodanie klucza przed wywołaniem API. Statyczny analizator Xcode nie zawsze ostrzega o braku klucza, zwłaszcza jeśli API jest wywoływane przez SDK firm trzecich. TestFlight testerzy również zobaczą crash, co może prowadzić do negatywnych opinii.

Szczególna sytuacja z iOS 17+: Apple wprowadził dodatkowe sprawdzenie dla dostępu do schowka (UIPasteboard). Jeśli aplikacja odczytuje schowek bez wyraźnego działania użytkownika, iOS wyświetla baner z ostrzeżeniem, nawet jeśli klucz Usage Description jest obecny. Dla schowka nie jest wymagany osobny klucz, ale Apple zaleca minimalizowanie automatycznego odczytu.

Błędy przy recenzji App Store

Oprócz crasha w czasie wykonania, brak klucza może być powodem odrzucenia aplikacji podczas moderacji. Apple sprawdza Info.plist na etapie recenzji i może odrzucić build, jeśli wykryje wywołania API bez odpowiednich kluczy. Xcode nie blokuje archiwizacji, ale App Store Connect może zwrócić błąd podczas przetwarzania pliku binarnego.

Jeśli aplikacja nie używa zasobu bezpośrednio, ale robi to SDK firmy trzeciej (np. SDK analityczne żąda IDFA), deweloper i tak musi dodać odpowiedni klucz. Apple sprawdza wszystkie wywołania API w pliku binarnym, w tym kod z bibliotek statycznych i dynamicznych. Błąd „Missing Info.plist key" to jedna z najczęstszych przyczyn odrzucania aktualizacji.