AndroidManifest.xml — cos'è, componenti principali e configurazione del manifest

Cos'è AndroidManifest.xml

AndroidManifest.xml è il file di configurazione principale in formato XML che ogni progetto Android deve avere nella directory app/src/main. Il sistema Android lo analizza prima di eseguire qualsiasi codice dell'app — durante l'analisi dell'APK all'installazione. Se il manifest contiene un errore di sintassi o manca una dichiarazione obbligatoria, l'installazione viene interrotta con un messaggio di errore.

Il file contiene una dichiarazione completa dell'app: un elenco di tutti i componenti (Activity, Service, BroadcastReceiver, ContentProvider), autorizzazioni richieste, versione minima dell'SDK, requisiti hardware e configurazione di temi e stili. Ogni componente che può essere invocato dal sistema o da altre app deve essere dichiarato esplicitamente nel manifest. Questo è un requisito di sicurezza: senza una dichiarazione esplicita, il componente non è disponibile per l'invocazione.

Senza un manifest configurato correttamente, l'app non può essere installata tramite Google Play o sideloading. Il sistema controlla il manifest durante l'analisi dell'APK e rifiuta l'installazione in caso di errori. Google Play analizza anche il manifest alla ricerca di configurazioni non sicure: se exported=true su un componente senza intent-filter, viene emesso un avviso; e se mancano autorizzazioni obbligatorie per targetSdk 34+, la pubblicazione viene bloccata. Pertanto, comprendere la struttura del manifest è un'abilità obbligatoria per gli sviluppatori Android.

Componenti dell'app nel manifest

Ogni componente di un'app Android deve essere esplicitamente registrato nel manifest. Questo è un requisito obbligatorio della piattaforma per tutti e quattro i tipi di componente. Senza registrazione, il componente non può essere creato dal sistema e tentare di avviarlo causerà un'ActivityNotFoundException o un'eccezione simile. I componenti vengono registrati all'interno del tag application in un ordine che non influisce sul loro funzionamento.

Activity

Il tag activity registra una schermata dell'app. L'attributo exported determina se altre app possono avviare questa Activity. A partire da Android 12, l'assenza di exported in presenza di intent-filter causa un errore di compilazione — questo è un requisito di sicurezza. Il punto di ingresso viene impostato tramite intent-filter con action MAIN e category LAUNCHER. Ogni Activity deve avere un android:name univoco che corrisponda al nome completo o relativo della classe.

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Service

Il tag service definisce un servizio in background. A partire da Android 8, i servizi in background hanno limitazioni severe: un foreground service richiede una notifica obbligatoria visibile all'utente con un'icona, e un bound service vive solo finché un client è legato ad esso. I servizi eseguiti in background senza notifica vengono terminati automaticamente dal sistema entro pochi minuti dal passaggio dell'app in background. Per attività di lunga durata, utilizza WorkManager invece di Service.

<service
    android:name=".SyncService"
    android:exported="false"
    android:foregroundServiceType="dataSync" />

BroadcastReceiver

Il tag receiver dichiara un ricevitore di messaggi broadcast di sistema o personalizzati. A partire da Android 8, la maggior parte dei broadcast impliciti non vengono più consegnati ai ricevitori dichiarati staticamente nel manifest. Si consiglia invece di registrare i ricevitori dinamicamente tramite Context.registerReceiver nel codice. Le eccezioni includono alcuni broadcast di sistema come BOOT_COMPLETED, che richiedono ancora la registrazione statica nel manifest.

<receiver
    android:name=".ConnectivityReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
</receiver>

Autorizzazioni in Android

Ogni autorizzazione pericolosa in Android richiede una dichiarazione nel manifest tramite il tag uses-permission. A partire da Android 6, le autorizzazioni pericolose vengono richieste in fase di esecuzione tramite un dialogo con l'utente, ma la dichiarazione nel manifest rimane obbligatoria. Senza di essa, il metodo requestPermissions genera una SecurityException. Le autorizzazioni di livello normale come INTERNET e ACCESS_NETWORK_STATE vengono concesse automaticamente all'installazione.

Il tag uses-permission-sdk-23 specifica le autorizzazioni necessarie solo su Android 6.0+. Ciò consente di mantenere la compatibilità con le versioni precedenti senza richiedere autorizzazioni inesistenti. Ad esempio, POST_NOTIFICATIONS è disponibile solo su Android 13+, quindi deve essere specificato tramite uses-permission-sdk-33 per evitare un errore di autorizzazione sconosciuta sui dispositivi più vecchi. L'attributo maxSdkVersion in uses-permission consente di revocare automaticamente le autorizzazioni non necessarie durante l'aggiornamento dell'app su versioni Android più recenti.

Le autorizzazioni di livello normale (INTERNET, ACCESS_NETWORK_STATE) vengono concesse automaticamente all'installazione e non richiedono una richiesta in fase di esecuzione. Anch'esse vengono dichiarate tramite uses-permission ma non vengono mostrate all'utente in un dialogo. Per controllare l'accesso ai componenti dell'app da altre applicazioni, viene utilizzato il meccanismo dei componenti protetti da autorizzazione: è possibile specificare un'autorizzazione personalizzata a livello di Activity o Service, che verrà verificata dal sistema quando il componente viene chiamato dall'esterno. Ciò fornisce un ulteriore livello di sicurezza per la comunicazione tra processi.

Intent Filters e deep link

Il tag intent-filter nel manifest dichiara quali intent impliciti un componente può gestire. Questo è il meccanismo attraverso il quale Android collega le azioni di sistema o personalizzate all'app. Un intent filter è composto da tre elementi: action, category e data. Tutti e tre possono essere combinati per una descrizione precisa di quali intent il componente deve ricevere. Il sistema seleziona il componente appropriato in base al filtro più specifico.

<activity android:name=".DeepLinkActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="itsectr.com"
            android:pathPrefix="/app" />
    </intent-filter>
</activity>

L'attributo autoVerify abilita la verifica di Android App Links: il sistema contatta il server per confermare la proprietà del dominio. Senza verifica, i deep link funzionano tramite il dialogo di scelta standard in cui l'utente seleziona con quale app aprire il link. Dopo la verifica riuscita, i link si aprono direttamente nell'app senza dialogo. Google Search Console utilizza anche autoVerify per indicizzare i deep link e mostrarli nei risultati di ricerca.

I filtri con action.VIEW e le categorie DEFAULT e BROWSABLE gestiscono i link da browser, email e altre app. Questo è il meccanismo principale per implementare i deep link in Android. Per supportare schemi URL personalizzati come myapp://, è sufficiente specificare lo scheme senza host. Tuttavia, Google consiglia di utilizzare deep link HTTPS invece di schemi personalizzati perché sono più sicuri e non richiedono autorizzazioni aggiuntive. Gli schemi personalizzati possono essere intercettati da qualsiasi app che registri lo stesso schema.

Attributi dell'app e metadati

Il tag radice manifest contiene attributi di pacchetto, versione e SDK. Il tag application memorizza le impostazioni globali: tema, icona, etichetta e flag di debug. Gli attributi di manifest definiscono il versionamento a livello di pacchetto, mentre gli attributi di application determinano l'aspetto e il comportamento generale dell'app. I valori possono essere riferimenti a risorse tramite la sintassi @ o valori letterali stringa.

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.itsectr.myapp"

    <uses-sdk
        android:minSdkVersion="24"
        android:targetSdkVersion="34" />

    <application
        android:label="MyApp"
        android:icon="@mipmap/ic_launcher"
        android:theme="@style/Theme.MyApp"
        android:supportsRtl="true"
        android:allowBackup="true">
        <!--  Componenti dell'app  -->
    </application>
</manifest>

Il tag meta-data all'interno di application consente di memorizzare coppie chiave-valore arbitrarie. Ciò è utile per configurare librerie di terze parti: chiavi API, URL di endpoint e flag di funzionalità. I dati da meta-data sono accessibili tramite PackageManager.getApplicationInfo().metaData in fase di esecuzione. Ad esempio, Firebase e Google Maps utilizzano meta-data per passare chiavi di accesso senza codificarle direttamente nel codice sorgente. Invece, le chiavi vengono impostate nel manifest e possono differire per diverse varianti di build.

L'attributo android:extractNativeLibs controlla l'estrazione delle librerie native dall'APK. Per le app con targetSdk 34+, questo attributo deve essere specificato esplicitamente, altrimenti la build potrebbe fallire con l'errore INSTALL_FAILED_INVALID_APK. Se extractNativeLibs=false, le librerie native rimangono all'interno dell'APK senza decompressione, riducendo le dimensioni dell'app installata ma aumentando il tempo di caricamento delle librerie. Per la maggior parte delle app moderne, si consiglia extractNativeLibs=false per ridurre lo spazio su disco utilizzato sul dispositivo dell'utente.

L'attributo android:networkSecurityConfig consente di specificare un file di configurazione della sicurezza di rete. Ciò è particolarmente importante per le app con targetSdk 28+, dove il traffico HTTP è bloccato per impostazione predefinita. Il file di configurazione definisce i certificati attendibili, i domini per le connessioni HTTP e le regole di pinning dei certificati. Ciò sostituisce l'attributo obsoleto android:usesCleartextTraffic e fornisce un meccanismo più flessibile per gestire la sicurezza delle connessioni a livello di sistema operativo.

L'attributo android:largeHeap richiede una dimensione heap aumentata per l'app. Per impostazione predefinita, Android alloca a ogni app una quantità limitata di memoria che dipende dal dispositivo e dalla versione del sistema operativo. Se l'app lavora con immagini pesanti, video o grandi set di dati, largeHeap può prevenire OutOfMemoryError. Tuttavia, abusare di questo attributo è dannoso: un'app con un elevato consumo di memoria viene terminata più rapidamente dal sistema quando le risorse sono scarse. Utilizza largeHeap solo dopo aver effettuato il profiling e aver confermato la necessità.