Info.plist: co to jest, obowiązkowe klucze i ustawienia przy uruchamianiu

Co to jest Info.plist

Info.plist to plik w formacie XML z elementem głównym dict, zawierającym pary klucz-wartość w postaci property list. Znajduje się wewnątrz pakietu aplikacji i jest odczytywany przez system przy każdym uruchomieniu przed wykonaniem kodu. Format plist obsługuje ciągi znaków, liczby, tablice, słowniki, daty i wartości logiczne, co pozwala opisywać złożone konfiguracje.

Apple używa Info.plist do określenia tożsamości aplikacji, jej możliwości i wymagań. Zmiana niektórych kluczy wymaga przebudowania pakietu, ponieważ wpływają one na metadane sprawdzane przez App Store podczas przesyłania kompilacji. Na przykład zmiana CFBundleVersion lub CFBundleIdentifier po publikacji może zakłócić proces aktualizacji aplikacji, ponieważ App Store Connect używa tych wartości do identyfikacji wersji.

Podstawowe klucze są tworzone automatycznie przy tworzeniu projektu w Xcode, ale większość ustawień dodaje się ręcznie w miarę rozwoju funkcjonalności aplikacji. Xcode udostępnia graficzny edytor Info.plist z listami rozwijanymi dla standardowych kluczy, co zmniejsza ryzyko literówek. Jednak w przypadku złożonych konfiguracji, takich jak Scene Manifest czy Background Modes, zaleca się edytowanie źródłowego XML bezpośrednio.

Obowiązkowe klucze Info.plist

Niektóre klucze Info.plist są obowiązkowe do publikacji w App Store. Ich brak prowadzi do odrzucenia kompilacji na etapie walidacji. Apple sprawdza te klucze automatycznie podczas przesyłania archiwum przez Xcode Organizer lub Transporter. Deweloper musi upewnić się, że wszystkie obowiązkowe pola są wypełnione poprawnie przed wysłaniem do recenzji.

Identyfikatory pakietu

Klucz CFBundleIdentifier określa unikalny identyfikator aplikacji w notacji odwróconej domeny (com.firma.aplikacja). Jest używany do podpisywania kodu, powiadomień Push, CloudKit, App Groups i wielu innych usług Apple. Zmiana identyfikatora po publikacji jest traktowana przez App Store jako nowa aplikacja, a istniejący użytkownicy nie otrzymają aktualizacji. Dlatego identyfikator powinien być niezmienny przez cały cykl życia aplikacji.

<key>CFBundleIdentifier</key>
<string>com.itsectr.myapp</string>

Wersja aplikacji

Klucze CFBundleShortVersionString (wyświetlana wersja) i CFBundleVersion (numer kompilacji) są używane przez App Store Connect i system do zarządzania aktualizacjami. Wersja jest podawana w formacie major.minor.patch. Numer kompilacji musi rosnąć z każdą kompilacją przesyłaną do App Store Connect, nawet jeśli wersja aplikacji się nie zmienia. Apple używa CFBundleVersion do określenia, czy kompilacja jest nowa, czy duplikuje już przesłaną. W przypadku zgodności numeru kompilacji z wcześniej przesłaną pojawia się błąd ITMS-90161.

<key>CFBundleShortVersionString</key>
<string>1.2.0</string>
<key>CFBundleVersion</key>
<string>42</string>

Obsługiwane orientacje interfejsu

Klucze UISupportedInterfaceOrientations określają obsługiwane orientacje ekranu dla iPhone. Dla iPada używany jest osobny klucz UISupportedInterfaceOrientations~ipad z sufiksem urządzenia. Każda orientacja jest określana ciągiem: UIInterfaceOrientationPortrait, UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationPortraitUpsideDown. Jeśli aplikacja obsługuje tylko orientację pionową, App Store odrzuci kompilację, jeśli nie jest przeznaczona tylko dla iPhone i podano tylko orientację pionową dla iPada.

<key>UISupportedInterfaceOrientations</key>
<array>
    <string>UIInterfaceOrientationPortrait</string>
    <string>UIInterfaceOrientationLandscapeLeft</string>
</array>

Uprawnienia i klucze prywatności

Począwszy od iOS 10, Apple wymaga opisu każdego wymaganego uprawnienia przez klucze z prefiksem NS (NeXTStep). Opis jest wyświetlany użytkownikowi w systemowym oknie dialogowym przy pierwszym żądaniu dostępu do prywatnych API. Brak odpowiedniego klucza NS przy wywołaniu API wymagającego uprawnienia prowadzi do natychmiastowego zakończenia aplikacji z wyjątkiem, który jest rejestrowany tylko w logach crash.

Każdy klucz prywatności musi zawierać zrozumiały dla użytkownika opis powodu żądania. Puste lub szablonowe teksty, takie jak „Do działania aplikacji” lub „Wymagany dostęp”, prowadzą do odrzucenia w App Store. Opis powinien wyjaśniać konkretną funkcjonalność: „Dostęp do kamery jest potrzebny do skanowania kodów QR i tworzenia zdjęć profilowych”. Zaleca się używanie zlokalizowanych wersji opisów przez pliki InfoPlist.strings dla każdego obsługiwanego języka.

Brak wymaganego klucza NS przy wywołaniu API z dostępem do prywatnych danych powoduje crash aplikacji. System kończy proces z wyjątkiem, co jest widoczne tylko w logach crash reports z Xcode lub Firebase Crashlytics. Użytkownik widzi tylko nagłe zamknięcie aplikacji bez żadnego wyjaśnienia. Dlatego przed dodaniem nowej funkcjonalności używającej kamery, mikrofonu lub geolokalizacji należy najpierw dodać odpowiedni klucz prywatności w Info.plist, a następnie zaimplementować wywołanie API.

Custom URL Schemes i App Links

Klucz CFBundleURLTypes rejestruje niestandardowe schematy URL dla głębokich linków w aplikacji. Pozwala to otwierać aplikację z przeglądarki, emaila lub innych aplikacji przez linki postaci mojaaplikacja://profil/123. Każdy schemat identyfikuje aplikację w unikalny sposób: jeśli dwie aplikacje zarejestrują ten sam schemat, system pokazuje użytkownikowi okno wyboru, której użyć.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.itsectr.myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Do obsługi Universal Links wymagany jest klucz com.apple.developer.associated-domains w pliku Entitlements, a nie w Info.plist. Universal Links działają tylko przy skonfigurowanym pliku apple-app-site-association na serwerze, który łączy domenę z aplikacją. W przeciwieństwie do niestandardowych schematów URL, Universal Links nie pokazują okna potwierdzenia i nie kolidują z innymi aplikacjami, ponieważ używają linków HTTPS, a nie niestandardowych schematów. Wymagają jednak domeny z ważnym certyfikatem SSL.

Niestandardowe schematy mogą kolidować ze standardowymi schematami iOS. Zaleca się używanie schematów o długości co najmniej 4 znaków, aby zminimalizować kolizje z innymi aplikacjami. Na przykład schemat „fb” jest zbyt krótki i może powodować konflikty. Lepiej używać odwróconej notacji: mojaaplikacja:// zamiast aplikacja://. Warto też pamiętać, że jeśli aplikacja zostanie usunięta, ale inna aplikacja zarejestruje ten sam schemat, użytkownik może otrzymać nieoczekiwane zachowanie przy przejściu przez link.

Konfiguracja uruchamiania i tryby tła

Klucz UIBackgroundModes deklaruje możliwości tła aplikacji. Każdy tryb wymaga odpowiedniego opisu w Info.plist i potwierdzenia w capabilities projektu Xcode. Bez określenia trybu system może wymusić zakończenie zadania tła po 30 sekundach lub przy braku zasobów.

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>remote-notification</string>
    <string>location</string>
    <string>processing</string>
</array>

Klucz UIApplicationSupportsMultipleScenes włącza obsługę wielozadaniowości na iPad i Mac Catalyst. Bez tego klucza aplikacja nie może używać SwiftUI ScenePhase lub UIKit UISceneDelegate do zarządzania wieloma oknami. Na iPadOS użytkownicy mogą otwierać wiele okien jednej aplikacji, przeciągać zawartość między nimi i używać Split View. Jeśli aplikacja nie obsługuje trybu wielu okien, ustawienie tego klucza na false wyłącza odpowiednią funkcjonalność.

Klucz LSRequiresIPhoneOS zabrania instalacji aplikacji na iPadzie. Jest używany dla aplikacji przeznaczonych tylko dla iPhone, które nie obsługują interfejsu iPada lub nie przeszły adaptacji do dużego ekranu. Jednak Apple nie zaleca używania tego klucza bez potrzeby, ponieważ użytkownicy oczekują, że aplikacje będą działać na wszystkich urządzeniach z iOS i iPadOS. Jeśli aplikacja jest jednak ograniczona do iPhone, należy upewnić się, że wymóg ten jest uzasadniony technicznie i podany w opisie App Store.

Klucz UIViewControllerBasedStatusBarAppearance zarządza stylem paska stanu. Jeśli ustawiony na NO, styl paska stanu jest określany globalnie przez klucz UIStatusBarStyle w Info.plist. Jeśli YES (domyślnie od iOS 7), każdy ViewController może zarządzać swoim paskiem stanu przez nadpisanie preferredStatusBarStyle. W nowoczesnych aplikacjach zaleca się pozostawienie YES, aby mieć różny pasek stanu na różnych ekranach, na przykład jasny na ciemnym tle i ciemny na jasnym.

Klucz UIApplicationExitsOnSuspend powoduje całkowite zakończenie aplikacji przy przejściu do trybu tła zamiast wstrzymania. Jest używany rzadko, tylko dla aplikacji o wysokich wymaganiach bezpieczeństwa: bankowych lub do pracy z poufnymi danymi. W takim przypadku użytkownik traci możliwość szybkiego powrotu do aplikacji, a każde uruchomienie następuje od nowa. App Store może poprosić o uzasadnienie użycia tego klucza podczas recenzji.

Klucz NSAppTransportSecurity zarządza połączeniami sieciowymi aplikacji. Począwszy od iOS 9, App Transport Security (ATS) domyślnie blokuje wszystkie połączenia HTTP, wymagając HTTPS. Do tymczasowego zezwolenia na żądania HTTP do określonych domen używany jest słownik NSExceptionDomains wewnątrz NSAppTransportSecurity. Do rozwoju dopuszczalne jest całkowite wyłączenie ATS przez NSAllowsArbitraryLoads = true, ale Apple wymaga uzasadnienia i nie przepuszcza takich kompilacji bez ważnego powodu. W kompilacji produkcyjnej ATS musi być włączony dla wszystkich domen współpracujących z danymi użytkownika.