Panoramica del file manifest dell'app

Ogni progetto di app deve avere un file AndroidManifest.xml con lo stesso nome nella directory principale dell'insieme di origini del progetto. Il file manifest descrive informazioni essenziali sulla tua app agli strumenti di compilazione Android, al sistema operativo Android e a Google Play.

Tra le altre cose, il file manifest deve dichiarare quanto segue:

  • I componenti dell'app, tra cui tutte le attività, i servizi, i ricevitori di trasmissione e i fornitori di contenuti. Ogni componente deve definire proprietà di base, come il nome della classe Kotlin o Java. Può anche dichiarare funzionalità, ad esempio le configurazioni del dispositivo che può gestire, e filtri di intent che descrivono come può essere avviato il componente. Scopri di più sui componenti dell'app nella sezione seguente.
  • Le autorizzazioni necessarie all'app per accedere a parti protette del sistema o di altre app. Dichiara inoltre tutte le autorizzazioni che altre app devono avere per accedere ai contenuti di questa app. Scopri di più sulle autorizzazioni nella sezione successiva.
  • Le funzionalità hardware e software richieste dall'app, che influiscono sui dispositivi su cui è possibile installare l'app da Google Play. Scopri di più sulla compatibilità dei dispositivi nella sezione seguente.

Se utilizzi Android Studio per compilare l'app, il file manifest viene creato automaticamente e la maggior parte degli elementi manifest essenziali viene aggiunta durante la compilazione dell'app, in particolare quando utilizzi i modelli di codice.

Funzionalità dei file

Le sezioni seguenti descrivono in che modo alcune delle caratteristiche più importanti della tua app vengono riportate nel file manifest.

Componenti dell'app

Per ogni componente dell'app che crei nella tua app, dichiara un elemento XML corrispondente nel file manifest:

Se sottoclassifichi uno di questi componenti senza dichiararlo nel file manifest, il sistema non può avviarlo.

Specifica il nome della sottoclasse con l'attributo name, utilizzando la designazione completa del pacchetto. Ad esempio, una sottoclasse Activity viene dichiarata come segue: 

<manifest ... >
    <application ... >
        <activity android:name="com.example.myapp.MainActivity" ... >
        </activity>
    </application>
</manifest>

Tuttavia, se il primo carattere del valore name è un punto, viene anteposto al nome l'ambito del nome dell'app, dalla proprietà namespace del file build.gradle a livello di modulo. Ad esempio, se lo spazio dei nomi è "com.example.myapp", il seguente nome dell'attività viene risolto in com.example.myapp.MainActivity: 

<manifest ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

Per ulteriori informazioni sull'impostazione del nome del pacchetto o dello spazio dei nomi, consulta Impostare lo spazio dei nomi.

Se i componenti dell'app si trovano in sottopacchetti, ad esempio in com.example.myapp.purchases, il valore name deve aggiungere i nomi dei sottopacchetti mancanti, ad esempio ".purchases.PayActivity", o utilizzare il nome del pacchetto completo.

Filtri per intent

Le attività delle app, i servizi e i ricevitori di trasmissione vengono attivati dagli intent. Un'intenzione è un messaggio definito da un oggetto Intent che descrive un'azione da eseguire, inclusi i dati su cui intervenire, la categoria del componente che deve eseguire l'azione e altre istruzioni.

Quando un'app emette un intent al sistema, quest'ultimo individua un componente dell'app in grado di gestire l'intent in base alle dichiarazioni del filtro per intent nel file manifest di ogni app. Il sistema avvia un'istanza del componente corrispondente e passa l'oggetto Intent a quel componente. Se più di un'app può gestire l'intent, l'utente può selezionare l'app da utilizzare.

Un componente dell'app può avere un numero illimitato di filtri intent (definiti con l'elemento <intent-filter>), ognuno dei quali descrive una funzionalità diversa del componente.

Per saperne di più, consulta il documento Intent e filtri intent.

Icone ed etichette

Alcuni elementi manifest hanno gli attributi icon e label per mostrare agli utenti rispettivamente una piccola icona e un'etichetta di testo per il componente dell'app corrispondente.

In ogni caso, l'icona e l'etichetta impostate in un elemento principale diventano i valori predefiniti di icon e label per tutti gli elementi secondari. Ad esempio, l'icona e l'etichetta impostate nell'elemento <application> sono l'icona e l'etichetta predefinite per ciascuno dei componenti dell'app, ad esempio tutte le attività.

L'icona e l'etichetta impostate in <intent-filter> di un componente vengono mostrate all'utente ogni volta che il componente viene presentato come opzione per adempiere a un'intenzione. Per impostazione predefinita, questa icona viene ereditata dall'icona dichiarata per il componente principale, ovvero dall'elemento <activity> o <application>.

Potresti voler modificare l'icona per un filtro intent se fornisce un'azione univoca che vuoi indicare meglio nella finestra di dialogo del selettore. Per ulteriori informazioni, vedi Consentire ad altre app di avviare la tua attività.

Autorizzazioni

Le app per Android devono richiedere l'autorizzazione per accedere a dati utente sensibili, come contatti e SMS, o a determinate funzionalità di sistema, come la fotocamera e l'accesso a internet. Ogni autorizzazione è identificata da un'etichetta univoca. Ad esempio, un'app che deve inviare messaggi SMS deve avere la seguente riga nel file manifest: 

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

A partire da Android 6.0 (livello API 23), l'utente può approvare o rifiutare alcune autorizzazioni delle app in fase di esecuzione. Tuttavia, indipendentemente dalla versione di Android supportata dalla tua app, devi dichiarare tutte le richieste di autorizzazione con un elemento <uses-permission> nel manifest. Se l'autorizzazione viene concessa, l'app può utilizzare le funzionalità protette. In caso contrario, i suoi tentativi di accedere a queste funzionalità non andranno a buon fine.

L'app può anche proteggere i propri componenti con le autorizzazioni. Può utilizzare qualsiasi autorizzazione definita da Android, come elencato in android.Manifest.permission, o un'autorizzazione dichiarata in un'altra app. L'app può anche definire le proprie autorizzazioni. Viene dichiarata una nuova autorizzazione con l'elemento <permission>.

Per ulteriori informazioni, vedi Autorizzazioni su Android.

Compatibilità dei dispositivi

Nel file manifest puoi anche dichiarare i tipi di funzionalità hardware o software richieste dalla tua app e, per estensione, i tipi di dispositivi con cui è compatibile. Google Play Store non consente agli utenti di installare la tua app su dispositivi che non forniscono le funzionalità o la versione di sistema richieste dalla tua app.

Esistono diversi tag manifest che definiscono i dispositivi con cui la tua app è compatibile. Di seguito sono riportati alcuni dei più comuni.

<uses-feature>

L'elemento <uses-feature> ti consente di dichiarare le funzionalità hardware e software di cui ha bisogno la tua app. Ad esempio, se la tua app non riesce a raggiungere la funzionalità di base su un dispositivo senza un sensore bussola, puoi dichiarare il sensore bussola come richiesto con il seguente tag manifest:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

Nota: se vuoi rendere disponibile la tua app su Chromebook, devi tenere conto di alcune limitazioni importanti delle funzionalità hardware e software. Per ulteriori informazioni, consulta Compatibilità del file manifest dell'app per Chromebook.

<uses-sdk>

Ogni versione successiva della piattaforma aggiunge spesso nuove API non disponibili nella versione precedente. Per indicare la versione minima con cui la tua app è compatibile, il file manifest deve includere il tag <uses-sdk> e il relativo attributo minSdkVersion.

Tuttavia, tieni presente che gli attributi nell'elemento <uses-sdk> vengono sostituiti dalle proprietà corrispondenti nel file build.gradle. Pertanto, se utilizzi Android Studio, specifica i valori minSdkVersion e targetSdkVersion al suo interno:

Groovy

android {
    defaultConfig {
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdkVersion 21

        // Specifies the API level used to test the app.
        targetSdkVersion 33
        ...
    }
}

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(21)

        // Specifies the API level used to test the app.
        targetSdkVersion(33)
        ...
    }
}

Per ulteriori informazioni sul file build.gradle, leggi l'articolo su come configurare la build.

Per scoprire di più su come dichiarare il supporto della tua app per diversi dispositivi, consulta la Panoramica della compatibilità dei dispositivi.

Convenzioni per i file

Questa sezione descrive le convenzioni e le regole che si applicano in genere a tutti gli elementi e gli attributi del file manifest.

Elementi
Sono obbligatori solo gli elementi <manifest> e <application>. Ognuno deve verificarsi una sola volta. La maggior parte degli altri elementi può verificarsi zero o più volte. Tuttavia, alcuni di questi elementi devono essere presenti per rendere utile il file manifest.

Tutti i valori vengono impostati tramite attributi, non come dati di carattere all'interno di un elemento.

Gli elementi allo stesso livello in genere non sono ordinati. Ad esempio, gli elementi <activity>, <provider> e <service> possono essere posizionati in qualsiasi ordine. Esistono due importanti eccezioni a questa regola:

  • Un elemento <activity-alias> deve seguire l'elemento <activity> di cui è un alias.
  • L'elemento <application> deve essere l'ultimo elemento all'interno dell'elemento <manifest>.
Attributi
Tecnicamente, tutti gli attributi sono facoltativi. Tuttavia, è necessario specificare molti attributi affinché un elemento possa raggiungere il suo scopo. Per gli attributi veramente facoltativi, la documentazione di riferimento indica i valori predefiniti.

Ad eccezione di alcuni attributi dell'elemento <manifest> principale, tutti i nomi degli attributi iniziano con un prefisso android:, come android:alwaysRetainTaskState. Poiché il prefisso è universale, la documentazione generalmente lo omette quando fa riferimento agli attributi per nome.

Più valori
Se è possibile specificare più di un valore, l'elemento viene quasi sempre ripetuto, anziché elencare più valori all'interno di un singolo elemento. Ad esempio, un filtro intent può elencare diverse azioni: 
<intent-filter ... >
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.INSERT" />
    <action android:name="android.intent.action.DELETE" />
    ...
</intent-filter>
Valori delle risorse
Alcuni attributi hanno valori visualizzati agli utenti, ad esempio il titolo di un'attività o l'icona dell'app. Il valore di questi attributi potrebbe essere diverso in base alla lingua dell'utente o ad altre configurazioni del dispositivo (ad esempio per fornire una dimensione dell'icona diversa in base alla densità di pixel del dispositivo), pertanto i valori devono essere impostati da una risorsa o un tema anziché essere hardcoded nel file manifest. Il valore effettivo può quindi variare in base alle risorse alternative che fornisci per configurazioni del dispositivo diverse.

Le risorse sono espresse come valori con il seguente formato:

"@[package:]type/name"

Puoi omettere il nome package se la risorsa è fornita dalla tua app (anche se è fornita da una dipendenza della libreria, perché le risorse della libreria vengono unite alle tue). L'unico altro nome pacchetto valido è android, quando vuoi utilizzare una risorsa del framework Android.

type è un tipo di risorsa, ad esempio string o drawable, e name è il nome che identifica la risorsa specifica. Ecco un esempio: 

<activity android:icon="@drawable/smallPic" ... >

Per saperne di più su come aggiungere risorse al progetto, consulta la Panoramica delle risorse dell'app.

Per applicare un valore definito in un tema, il primo carattere deve essere ? anziché @:

"?[package:]type/name"

Valori stringa
Se il valore di un attributo è una stringa, utilizza due barre rovesciate (\\) per dare un'interpretazione letterale ai caratteri, ad esempio \\n per un a capo o \\uxxxx per un carattere Unicode.

Riferimento agli elementi manifest

La tabella seguente fornisce i link ai documenti di riferimento per tutti gli elementi validi nel file AndroidManifest.xml.

<action> Aggiunge un'azione a un filtro per intent.
<activity> Dichiara un componente dell'attività.
<activity-alias> Dichiara un alias per un'attività.
<application> Dichiara l'applicazione.
<category> Aggiunge un nome di categoria a un filtro per intent.
<compatible-screens> Specifica ogni configurazione dello schermo con cui l'applicazione è compatibile.
<data> Aggiunge una specifica dei dati a un filtro per intent.
<grant-uri-permission> Specifica i sottoinsiemi di dati dell'app a cui il provider di contenuti principale ha l'autorizzazione di accesso.
<instrumentation> Dichiara una classe Instrumentation che consente di monitorare l'interazione di un'applicazione con il sistema.
<intent-filter> Specifica i tipi di intent a cui un'attività, un servizio o un broadcast receiver può rispondere.
<manifest> L'elemento principale del file AndroidManifest.xml.
<meta-data> Una coppia di nome e valore per un elemento di dati arbitrari aggiuntivi che può essere fornito al componente principale.
<path-permission> Definisce il percorso e le autorizzazioni richieste per un sottoinsieme specifico di dati all'interno di un fornitore di contenuti.
<permission> Dichiara un'autorizzazione di sicurezza che può essere utilizzata per limitare l'accesso a componenti o funzionalità specifici di questa o altre applicazioni.
<permission-group> Dichiara un nome per un raggruppamento logico di autorizzazioni correlate.
<permission-tree> Dichiara il nome di base per un albero di autorizzazioni.
<provider> Dichiara un componente del fornitore di contenuti.
<queries> Dichiara l'insieme di altre app a cui la tua app intende accedere. Scopri di più nella guida sul filtro della visibilità dei pacchetti.
<receiver> Dichiara un componente di ricezione di annunci.
<service> Dichiara un componente di servizio.
<supports-gl-texture> Dichiara un singolo formato di compressione delle texture GL supportato dall'app.
<supports-screens> Dichiara le dimensioni dello schermo supportate dalla tua app e attiva la modalità di compatibilità dello schermo per schermi più grandi di quelli supportati dalla tua app.
<uses-configuration> Indica le funzionalità di input specifiche richieste dall'applicazione.
<uses-feature> Dichiara una singola funzionalità hardware o software utilizzata dall'applicazione.
<uses-library> Specifica una libreria condivisa a cui deve essere collegata l'applicazione.
<uses-native-library> Specifica una libreria condivisa nativa fornita dal fornitore a cui deve essere collegata l'app.
<uses-permission> Specifica un'autorizzazione di sistema che l'utente deve concedere affinché l'app funzioni correttamente.
<uses-permission-sdk-23> Specifica che un'app richiede una determinata autorizzazione, ma solo se è installata su un dispositivo con Android 6.0 (livello API 23) o versioni successive.
<uses-sdk> Consente di esprimere la compatibilità di un'applicazione con una o più versioni della piattaforma Android, tramite un numero intero del livello API.

Limiti

I seguenti tag hanno un limite al numero di occorrenze in un file manifest:

Nome tag Limite
<package> 1000
<meta-data> 1000
<uses-library> 1000

I seguenti attributi hanno un limite di lunghezza massima:

Attributo Limite
name 1024
versionName 1024
host 255
mimeType 255

File manifest di esempio

Il codice XML riportato di seguito è un semplice esempio AndroidManifest.xml che dichiara due attività per l'app.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0">

    <!-- Beware that these values are overridden by the build.gradle file -->
    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <!-- This name is resolved to com.example.myapp.MainActivity
             based on the namespace property in the build.gradle file -->
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <activity
            android:name=".DisplayMessageActivity"
            android:parentActivityName=".MainActivity" />
    </application>
</manifest>