Info.plist: چیست، کلیدهای اجباری و تنظیمات راه‌اندازی

Info.plist چیست

Info.plist فایلی در قالب XML با عنصر ریشه dict است که شامل جفت‌های کلید-مقدار به صورت property list می‌باشد. این فایل در داخل باندل برنامه قرار دارد و در هر بار راه‌اندازی قبل از اجرای کد توسط سیستم خوانده می‌شود. قالب plist از رشته‌ها، اعداد، آرایه‌ها، فرهنگ لغت‌ها، تاریخ‌ها و مقادیر بولی پشتیبانی می‌کند که امکان توصیف پیکربندی‌های پیچیده را فراهم می‌کند.

اپل از Info.plist برای تعیین هویت برنامه، قابلیت‌ها و الزامات آن استفاده می‌کند. تغییر برخی کلیدها نیاز به بازسازی باندل دارد، زیرا آنها روی فراداده‌هایی تأثیر می‌گذارند که در هنگام بارگذاری ساخت توسط App Store بررسی می‌شوند. به عنوان مثال، تغییر CFBundleVersion یا CFBundleIdentifier پس از انتشار می‌تواند فرآیند به‌روزرسانی برنامه را مختل کند، زیرا App Store Connect از این مقادیر برای شناسایی نسخه‌ها استفاده می‌کند.

کلیدهای پایه به طور خودکار هنگام ایجاد پروژه در Xcode ایجاد می‌شوند، اما بیشتر تنظیمات با توسعه قابلیت‌های برنامه به صورت دستی اضافه می‌شوند. Xcode یک ویرایشگر گرافیکی Info.plist با لیست‌های کشویی برای کلیدهای استاندارد ارائه می‌دهد که خطر اشتباهات تایپی را کاهش می‌دهد. با این حال، برای پیکربندی‌های پیچیده مانند Scene Manifest یا Background Modes، توصیه می‌شود XML منبع را مستقیماً ویرایش کنید.

کلیدهای اجباری Info.plist

برخی از کلیدهای Info.plist برای انتشار در App Store اجباری هستند. عدم وجود آنها منجر به رد ساخت در مرحله اعتبارسنجی می‌شود. اپل این کلیدها را به طور خودکار هنگام بارگذاری آرشیو از طریق Xcode Organizer یا Transporter بررسی می‌کند. توسعه‌دهنده باید مطمئن شود که تمام فیلدهای اجباری قبل از ارسال برای بررسی به درستی پر شده‌اند.

شناسه‌های باندل

کلید CFBundleIdentifier یک شناسه منحصر به فرد برای برنامه به صورت نماد معکوس دامنه (com.company.appname) تعیین می‌کند. این شناسه برای امضای کد، اعلان‌های Push، CloudKit، App Groups و بسیاری از سرویس‌های دیگر اپل استفاده می‌شود. تغییر شناسه پس از انتشار توسط App Store به عنوان یک برنامه جدید تلقی می‌شود و کاربران موجود به‌روزرسانی دریافت نمی‌کنند. بنابراین شناسه باید در طول کل چرخه عمر برنامه بدون تغییر باقی بماند.

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

نسخه برنامه

کلیدهای CFBundleShortVersionString (نسخه نمایشی) و CFBundleVersion (شماره ساخت) توسط App Store Connect و سیستم برای مدیریت به‌روزرسانی‌ها استفاده می‌شوند. نسخه در قالب major.minor.patch مشخص می‌شود. شماره ساخت باید با هر ساخت بارگذاری شده در App Store Connect افزایش یابد، حتی اگر نسخه برنامه تغییر نکند. اپل از 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. اگر برنامه فقط جهت عمودی را پشتیبانی کند، App Store ساخت را رد می‌کند، مگر اینکه فقط مخصوص iPhone باشد و فقط عمودی برای iPad مشخص شده باشد.

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

مجوزها و کلیدهای حریم خصوصی

از iOS 10 به بعد، اپل توضیح هر مجوز درخواستی را از طریق کلیدهای با پیشوند NS (NeXTStep) الزامی می‌کند. توضیح در اولین درخواست دسترسی به APIهای خصوصی در دیالوگ سیستمی به کاربر نمایش داده می‌شود. عدم وجود کلید NS مربوطه هنگام فراخوانی API که نیاز به مجوز دارد، منجر به خاتمه فوری برنامه با یک استثنا می‌شود که فقط در لاگ‌های crash ثبت می‌شود.

هر کلید حریم خصوصی باید حاوی توضیح قابل فهم برای کاربر درباره دلیل درخواست باشد. متن‌های خالی یا قالبی مانند «برای کار کردن برنامه» یا «دسترسی لازم است» منجر به رد شدن در App Store می‌شود. توضیح باید عملکرد خاص را توضیح دهد: «دسترسی به دوربین برای اسکن کدهای QR و ایجاد عکس پروفایل نیاز است». توصیه می‌شود از نسخه‌های محلی‌سازی شده توضیحات از طریق فایل‌های InfoPlist.strings برای هر زبان پشتیبانی شده استفاده کنید.

عدم وجود کلید NS مورد نیاز هنگام فراخوانی API با دسترسی به داده‌های خصوصی باعث crash برنامه می‌شود. سیستم فرآیند را با یک استثنا خاتمه می‌دهد که فقط در لاگ‌های crash reports از Xcode یا Firebase Crashlytics قابل مشاهده است. کاربر فقط بسته شدن ناگهانی برنامه را بدون هیچ توضیحی می‌بیند. بنابراین قبل از افزودن قابلیت جدیدی که از دوربین، میکروفون یا موقعیت جغرافیایی استفاده می‌کند، ابتدا باید کلید حریم خصوصی مربوطه را در Info.plist اضافه کرده و سپس فراخوانی API را پیاده‌سازی کنید.

طرح‌های URL سفارشی و 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 و تأیید در capabilities پروژه 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 پشتیبانی نمی‌کنند یا با صفحه بزرگ سازگار نشده‌اند استفاده می‌شود. با این حال، اپل استفاده از این کلید را بدون نیاز توصیه نمی‌کند، زیرا کاربران انتظار دارند برنامه‌ها در تمام دستگاه‌های iOS و iPadOS کار کنند. اگر برنامه همچنان محدود به iPhone است، باید اطمینان حاصل کنید که این الزام از نظر فنی موجه است و در توضیحات App Store ذکر شده است.

کلید UIViewControllerBasedStatusBarAppearance سبک نوار وضعیت را کنترل می‌کند. اگر روی NO تنظیم شود، سبک نوار وضعیت به صورت سراسری از طریق کلید UIStatusBarStyle در Info.plist تعیین می‌شود. اگر YES (پیش‌فرض از iOS 7)، هر ViewController می‌تواند نوار وضعیت خود را از طریق بازنویسی preferredStatusBarStyle مدیریت کند. برای برنامه‌های مدرن توصیه می‌شود YES باقی بماند تا نوار وضعیت متفاوتی در صفحات مختلف داشته باشید،例えば روشن در پس‌زمینه تیره و تیره در پس‌زمینه روشن.

کلید UIApplicationExitsOnSuspend باعث می‌شود برنامه هنگام انتقال به حالت پس‌زمینه به جای تعلیق، کاملاً خاتمه یابد. به ندرت استفاده می‌شود، فقط برای برنامه‌هایی با الزامات امنیتی بالا: برنامه‌های بانکی یا برنامه‌های کار با داده‌های محرمانه. در این حالت کاربر توانایی بازگشت سریع به برنامه را از دست می‌دهد و هر راه‌اندازی از حالت خالص انجام می‌شود. App Store ممکن است در هنگام بررسی دلیل استفاده از این کلید را درخواست کند.

کلید NSAppTransportSecurity اتصالات شبکه برنامه را مدیریت می‌کند. از iOS 9 به بعد، App Transport Security (ATS) به طور پیش‌فرض تمام اتصالات HTTP را مسدود کرده و HTTPS را الزامی می‌کند. برای اجازه موقت درخواست‌های HTTP به دامنه‌های خاص، از فرهنگ لغت NSExceptionDomains در داخل NSAppTransportSecurity استفاده می‌شود. برای توسعه، غیرفعال کردن کامل ATS از طریق NSAllowsArbitraryLoads = true مجاز است، اما اپل نیاز به توجیه دارد و چنین ساخت‌هایی را بدون دلیل موجه عبور نمی‌دهد. در ساخت تولیدی، ATS باید برای تمام دامنه‌هایی که با داده‌های کاربر تعامل دارند فعال باشد.