Info.plist: що це таке, обов’язкові ключі та налаштування запуску

Що таке Info.plist

Info.plist — це файл у форматі XML з кореневим елементом dict, який містить пари ключ-значення у вигляді property list. Він знаходиться всередині бандла додатка і читається системою при кожному запуску до виконання коду. Формат plist підтримує рядки, числа, масиви, словники, дати та булеві значення, що дозволяє описувати складні конфігурації.

Apple використовує Info.plist для визначення ідентичності, можливостей та вимог додатка. Зміна деяких ключів вимагає перебудови бандла, оскільки вони впливають на метадані, які перевіряє App Store при завантаженні збірки. Наприклад, зміна CFBundleVersion або CFBundleIdentifier після публікації може порушити процес оновлення додатка, оскільки App Store Connect використовує ці значення для ідентифікації версій.

Базові ключі створюються автоматично при створенні проєкту в Xcode, але більшість налаштувань додаються вручну в міру розвитку функціоналу додатка. Xcode надає графічний редактор Info.plist з випадними списками для стандартних ключів, що знижує ризик помилок. Однак для складних конфігурацій, як-от Scene Manifest або Background Modes, рекомендується редагувати вихідний XML безпосередньо.

Обов’язкові ключі Info.plist

Деякі ключі Info.plist є обов’язковими для публікації в App Store. Їхня відсутність призводить до відхилення збірки на етапі перевірки. Apple автоматично перевіряє ці ключі при завантаженні архіву через Xcode Organizer або Transporter. Розробник повинен переконатися, що всі обов’язкові поля заповнені правильно перед відправкою на рецензію.

Ідентифікатори бандла

Ключ CFBundleIdentifier задає унікальний ідентифікатор додатка в зворотній нотації домену (com.company.appname). Він використовується для підпису коду, Push-сповіщень, CloudKit, App Groups та багатьох інших сервісів Apple. Зміна ідентифікатора після публікації сприймається App Store як новий додаток, і існуючі користувачі не отримають оновлення. Тому ідентифікатор повинен залишатися незмінним протягом усього життєвого циклу додатка.

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

Версія додатка

Ключі CFBundleShortVersionString (відображувана версія) та CFBundleVersion (номер збірки) використовуються App Store Connect та системою для керування оновленнями. Версія вказується у форматі major.minor.patch. Номер збірки повинен збільшуватися з кожною збіркою, завантаженою в App Store Connect, навіть якщо версія додатка не змінюється. Apple використовує CFBundleVersion для визначення, чи є збірка новою або дублікає вже завантажену. Якщо номер збірки збігається з раніше завантаженою, повертається помилка ITMS-90161.

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

Підтримувані орієнтації інтерфейсу

Ключі UISupportedInterfaceOrientations визначають підтримувані орієнтації екрана для iPhone. Для iPad використовується окремий ключ UISupportedInterfaceOrientations~ipad з суфіксом пристрою. Кожна орієнтація задається рядком: UIInterfaceOrientationPortrait, UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationPortraitUpsideDown. Якщо додаток підтримує лише книжкову орієнтацію і не є лише для iPhone, App Store відхилить збірку, якщо для iPad задано лише книжкову орієнтацію.

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

Дозволи та ключі конфіденційності

Починаючи з iOS 10, Apple вимагає опису кожного запитуваного дозволу через ключі з префіксом NS (NeXTStep). Опис відображається користувачеві в системному діалозі при першому запиті доступу до приватних API. Відсутність відповідного NS-ключа при виклику API, яка потребує дозволу, призводить до негайного завершення додатка з винятком, яке фіксується лише в журналах збоїв.

Кожен ключ конфіденційності повинен містити зрозумілий для користувача опис причини запиту. Порожні або шаблонні тексти, наприклад «Для роботи додатка» або «Потрібен доступ», призводять до відхилення App Store. Опис повинен пояснювати конкретну функціональність: «Доступ до камери потрібен для сканування QR-кодів та створення фото профілю.» Рекомендується використовувати локалізовані версії описів через файли InfoPlist.strings для кожної підтримуваної мови.

Відсутність потрібного NS-ключа при виклику API, яка отримує доступ до приватних даних, викликає аварію додатка. Система завершує процес з винятком, яке помітне лише в журналах звітів про аварії з Xcode або Firebase Crashlytics. Користувач бачить лише раптове закриття додатка без будь-якого пояснення. Тому перед додаванням нового функціоналу, що використовує камеру, мікрофон або геолокацію, спочатку потрібно додати відповідний ключ конфіденційності в Info.plist, а потім реалізувати виклик API.

Custom URL Schemes та App Links

Ключ CFBundleURLTypes реєструє кастомні URL-схеми для глибоких посилань в додатку. Це дозволяє відкривати додаток з браузера, електронної пошти або інших додатків по посиланнях виду myapp://profile/123. Кожна схема ідентифікує додаток унікальним чином: якщо два додатки реєструють однакову схему, система показує користувачеві діалог вибору, який використовувати.

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

Для підтримки Universal Links потрібен ключ com.apple.developer.associated-domains в файлі Entitlements, а не в Info.plist. Universal Links працюють лише за наявності налаштованого файлу apple-app-site-association на сервері, який пов’язує домен з додатком. На відміну від кастомних URL-схем, Universal Links не показують діалог підтвердження та не конфліктують з іншими додатками, оскільки використовують HTTPS-посилання замість кастомних схем. Однак вони вимагають домену з дійсним SSL-сертифікатом.

Кастомні схеми можуть конфліктувати зі стандартними схемами iOS. Рекомендується використовувати схеми довжиною не менше 4 символів для мінімізації колізій з іншими додатками. Наприклад, схема «fb» занадто коротка і може конфліктувати. Краще використовувати зворотну нотацію: myapp:// замість app://. Також варто пам’ятати, що якщо додаток видалено, але інший додаток зареєстрував ту ж схему, користувач може отримати неочікувану поведінку при переході за посиланням.

Налаштування запуску та фонові режими

Ключ UIBackgroundModes оголошує фонові можливості додатка. Кожен режим вимагає відповідного опису в Info.plist та підтвердження в можливостях проєкту Xcode. Без зазначення режиму система може примусово завершити фонове завдання через 30 секунд або при нестачі ресурсів.

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

Ключ UIApplicationSupportsMultipleScenes вмикає підтримку багатозадачності на iPad та Mac Catalyst. Без цього ключа додаток не може використовувати SwiftUI ScenePhase або UIKit UISceneDelegate для керування декількома вікнами. На iPadOS користувачі можуть відкривати кілька вікон одного й того ж додатка, перетягувати вміст між ними та використовувати Split View. Якщо додаток не підтримує багатовіконний режим, встановлення цього ключа в false вимикає відповідну функціональність.

Ключ LSRequiresIPhoneOS забороняє встановлення додатка на iPad. Він використовується для додатків лише для iPhone, які не підтримують інтерфейс iPad або не адаптовані для великого екрана. Однак Apple не рекомендує використовувати цей ключ без потреби, оскільки користувачі очікують, що додатки працюватимуть на всіх пристроях під керуванням iOS та iPadOS. Якщо додаток все ще обмежений iPhone, переконайтеся, що ця вимога технічно обґрунтована та зазначена в описі App Store.

Ключ UIViewControllerBasedStatusBarAppearance керує стилем рядка статусу. Якщо встановлено NO, стиль рядка статусу встановлюється глобально через ключ Info.plist UIStatusBarStyle. Якщо YES (типово з iOS 7), кожен ViewController може керувати своїм рядком статусу через перевизначення preferredStatusBarStyle. Для сучасних додатків рекомендується залишити YES, щоб мати різні стилі рядка статусу на різних екранах, наприклад світлий на темному фоні та темний на світлому.

Ключ UIApplicationExitsOnSuspend змушує додаток повністю завершатися при переході в фоновий режим замість припинення. Він використовується рідко, лише для додатків з високими вимогами безпеки: банківські додатки або додатки для роботи з конфіденційними даними. У цьому випадку користувач втрачає можливість швидко повернутися до додатка, і кожен запуск починається з чистого стану. App Store може запитати обґрунтування використання цього ключа під час рецензії.

Ключ NSAppTransportSecurity керує мережевими з’єднаннями додатка. Починаючи з iOS 9, App Transport Security (ATS) блокує всі HTTP-з’єднання за замовчуванням, вимагаючи HTTPS. Для тимчасового дозволу HTTP-запитів до певних доменів використовується словник NSExceptionDomains всередині NSAppTransportSecurity. Для розробки допускається повне вимкнення ATS через NSAllowsArbitraryLoads = true, але Apple вимагає обґрунтування та не пропускає такі збірки без вагомої причини. У продакшн-збірках ATS повинен бути увімкнений для всіх доменів, що взаємодіють з користувацькими даними.