Info.plist: cos’è, chiavi obbligatorie e configurazione di avvio

Cos’è Info.plist

Info.plist è un file in formato XML con elemento radice dict contenente coppie chiave-valore sotto forma di property list. Si trova all’interno del bundle dell’applicazione e viene letto dal sistema a ogni avvio prima dell’esecuzione del codice. Il formato plist supporta stringhe, numeri, array, dizionari, date e valori booleani, consentendo di descrivere configurazioni complesse.

Apple utilizza Info.plist per definire l’identità, le capacità e i requisiti dell’applicazione. La modifica di alcune chiavi richiede la ricostruzione del bundle, poiché influenzano i metadati controllati dall’App Store durante il caricamento di un build. Ad esempio, modificare CFBundleVersion o CFBundleIdentifier dopo la pubblicazione potrebbe interrompere il processo di aggiornamento dell’app, poiché App Store Connect utilizza questi valori per identificare le versioni.

Le chiavi di base vengono create automaticamente alla creazione di un progetto in Xcode, ma la maggior parte delle impostazioni vengono aggiunte manualmente man mano che la funzionalità dell’app evolve. Xcode fornisce un editor grafico di Info.plist con elenchi a discesa per le chiavi standard, riducendo il rischio di errori di battitura. Tuttavia, per configurazioni complesse come Scene Manifest o Background Modes, si consiglia di modificare direttamente il XML originale.

Chiavi obbligatorie di Info.plist

Alcune chiavi di Info.plist sono obbligatorie per pubblicare sull’App Store. La loro assenza porta al rifiuto del build nella fase di validazione. Apple controlla automaticamente queste chiavi durante il caricamento di un archivio tramite Xcode Organizer o Transporter. Lo sviluppatore deve assicurarsi che tutti i campi obbligatori siano compilati correttamente prima di inviare per la revisione.

Identificatori del bundle

La chiave CFBundleIdentifier imposta un identificatore univoco dell’applicazione in notazione di dominio inverso (com.company.appname). Viene utilizzata per la firma del codice, le notifiche push, CloudKit, App Groups e molti altri servizi Apple. La modifica dell’identificatore dopo la pubblicazione viene considerata dall’App Store come una nuova applicazione e gli utenti esistenti non riceveranno l’aggiornamento. Pertanto, l’identificatore deve rimanere invariato per l’intero ciclo di vita dell’applicazione.

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

Versione dell’applicazione

Le chiavi CFBundleShortVersionString (versione visualizzata) e CFBundleVersion (numero di build) vengono utilizzate da App Store Connect e dal sistema per gestire gli aggiornamenti. La versione viene specificata nel formato major.minor.patch. Il numero di build deve aumentare con ogni build caricato su App Store Connect, anche se la versione dell’app non cambia. Apple utilizza CFBundleVersion per determinare se un build è nuovo o duplica uno già caricato. Se il numero di build corrisponde a uno già caricato, viene restituito l’errore ITMS-90161.

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

Orientamenti dell’interfaccia supportati

Le chiavi UISupportedInterfaceOrientations definiscono le orientazioni dello schermo supportate per iPhone. Per iPad viene utilizzata una chiave separata UISupportedInterfaceOrientations~ipad con il suffisso del dispositivo. Ogni orientamento viene specificato come stringa: UIInterfaceOrientationPortrait, UIInterfaceOrientationLandscapeLeft, UIInterfaceOrientationLandscapeRight, UIInterfaceOrientationPortraitUpsideDown. Se un’app supporta solo l’orientamento verticale e non è solo per iPhone, l’App Store rifiuterà il build se è specificato solo il verticale per iPad.

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

Permessi e chiavi privacy

Da iOS 10, Apple richiede una descrizione per ogni permesso richiesto tramite chiavi con il prefisso NS (NeXTStep). La descrizione viene mostrata all’utente in un dialogo di sistema al primo tentativo di accesso alle API private. L’assenza della chiave NS corrispondente quando si chiama un’API che richiede un permesso causa l’arresto immediato dell’applicazione con un’eccezione registrata solo nei log di crash.

Ogni chiave privacy deve contenere una descrizione comprensibile per l’utente del motivo della richiesta. Testi vuoti o generici, come “Per il funzionamento dell’app” o “Accesso necessario”, portano al rifiuto dell’App Store. La descrizione deve spiegare la funzionalità specifica: “L’accesso alla fotocamera è necessario per scansionare i codici QR e creare foto del profilo.” Si consiglia di utilizzare versioni localizzate delle descrizioni tramite file InfoPlist.strings per ogni lingua supportata.

L’assenza della chiave NS necessaria quando si chiama un’API che accede a dati privati causa un crash dell’applicazione. Il sistema termina il processo con un’eccezione, visibile solo nei log dei report di crash di Xcode o Firebase Crashlytics. L’utente vede solo una chiusura improvvisa dell’app senza alcuna spiegazione. Pertanto, prima di aggiungere nuove funzionalità che utilizzano fotocamera, microfono o geolocalizzazione, è necessario prima aggiungere la chiave privacy corrispondente in Info.plist e poi implementare la chiamata API.

Custom URL Schemes e App Links

La chiave CFBundleURLTypes registra schemi URL personalizzati per i collegamenti profondi nell’applicazione. Ciò consente di aprire l’app dal browser, dall’email o da altre applicazioni tramite link come myapp://profile/123. Ogni schema identifica l’applicazione in modo univoco: se due app registrano lo stesso schema, il sistema mostra all’utente un dialogo per scegliere quale utilizzare.

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

Per supportare gli Universal Links, è necessaria la chiave com.apple.developer.associated-domains nel file Entitlements, non in Info.plist. Gli Universal Links funzionano solo se esiste un file apple-app-site-association configurato sul server che collega il dominio all’applicazione. A differenza degli schemi URL personalizzati, gli Universal Links non mostrano un dialogo di conferma e non entrano in conflitto con altre applicazioni, poiché utilizzano link HTTPS invece di schemi personalizzati. Tuttavia, richiedono un dominio con un certificato SSL valido.

Gli schemi personalizzati possono entrare in conflitto con gli schemi standard di iOS. Si consiglia di utilizzare schemi di almeno 4 caratteri per ridurre al minimo le collisioni con altre app. Ad esempio, lo schema “fb” è troppo corto e può causare conflitti. È meglio utilizzare la notazione inversa: myapp:// invece di app://. Inoltre, se l’app viene eliminata ma un’altra app ha registrato lo stesso schema, l’utente potrebbe riscontrare un comportamento imprevisto durante la navigazione tramite un link.

Configurazione di avvio e modalità background

La chiave UIBackgroundModes dichiara le capacità in background dell’applicazione. Ogni modalità richiede una descrizione corrispondente in Info.plist e la conferma nelle capacità del progetto Xcode. Senza specificare una modalità, il sistema può terminare forzatamente l’attività in background dopo 30 secondi o in caso di carenza di risorse.

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

La chiave UIApplicationSupportsMultipleScenes abilita il supporto al multitasking su iPad e Mac Catalyst. Senza questa chiave, l’applicazione non può utilizzare SwiftUI ScenePhase o UIKit UISceneDelegate per gestire più finestre. Su iPadOS, gli utenti possono aprire più finestre della stessa app, trascinare contenuti tra di esse e utilizzare Split View. Se l’applicazione non supporta la modalità multi-finestra, impostare questa chiave su false disabilita la funzionalità corrispondente.

La chiave LSRequiresIPhoneOS impedisce l’installazione dell’app su iPad. Viene utilizzata per app solo iPhone che non supportano l’interfaccia iPad o non sono state adattate per uno schermo grande. Tuttavia, Apple non raccomanda di utilizzare questa chiave inutilmente, poiché gli utenti si aspettano che le app funzionino su tutti i dispositivi con iOS e iPadOS. Se l’app è ancora limitata a iPhone, assicurati che questo requisito sia tecnicamente giustificato e indicato nella descrizione dell’App Store.

La chiave UIViewControllerBasedStatusBarAppearance controlla lo stile della barra di stato. Se impostata su NO, lo stile della barra di stato viene impostato globalmente tramite la chiave Info.plist UIStatusBarStyle. Se YES (predefinito da iOS 7), ogni ViewController può gestire la propria barra di stato sovrascrivendo preferredStatusBarStyle. Per le app moderne, si consiglia di mantenere YES per avere diversi stili di barra di stato su schermi diversi, ad esempio chiaro su sfondo scuro e scuro su sfondo chiaro.

La chiave UIApplicationExitsOnSuspend forza l’app a terminare completamente quando entra in background invece di sospendersi. Viene usata raramente, solo per app con elevati requisiti di sicurezza: app bancarie o app che gestiscono dati riservati. In questo caso, l’utente perde la possibilità di tornare rapidamente all’app e ogni avvio parte da uno stato pulito. L’App Store può richiedere una giustificazione per l’uso di questa chiave durante la revisione.

La chiave NSAppTransportSecurity gestisce le connessioni di rete dell’app. Da iOS 9, App Transport Security (ATS) blocca tutte le connessioni HTTP per impostazione predefinita, richiedendo HTTPS. Per consentire temporaneamente richieste HTTP a domini specifici, viene utilizzato il dizionario NSExceptionDomains all’interno di NSAppTransportSecurity. Per lo sviluppo, la disattivazione completa di ATS tramite NSAllowsArbitraryLoads = true è consentita, ma Apple richiede una giustificazione e non permette tali build senza un valido motivo. Nei build di produzione, ATS deve essere abilitato per tutti i domini che gestiscono dati utente.