Panoramica del file manifest dell'app

Ogni progetto di app deve avere un file AndroidManifest.xml, con esattamente questo nome, nella directory principale del set di origine del progetto. Il file manifest descrive le informazioni essenziali sulla tua app relative agli strumenti di creazione di Android, al sistema operativo Android e a Google Play.

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

  • I componenti dell'app, incluse 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 relativa classe Kotlin o Java. Può anche dichiarare funzionalità, ad esempio le configurazioni di dispositivi che può gestire, e i filtri intent che descrivono come può essere avviato il componente. Scopri di più sui componenti dell'app in una sezione che segue.
  • Le autorizzazioni necessarie all'app per accedere a parti protette del sistema o di altre app. Dichiara inoltre le eventuali autorizzazioni che altre app devono disporre se vogliono accedere ai contenuti da questa app. Scopri di più sulle autorizzazioni in una sezione che segue.
  • Le funzionalità hardware e software richieste dall'app, che determinano quali dispositivi possono installare l'app da Google Play. Scopri di più sulla compatibilità dei dispositivi in una sezione che segue.

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

Funzionalità per i file

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

Componenti dell'app

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

Se esegui una sottoclasse di 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 nel valore name è un punto, lo spazio dei nomi dell'app, dalla proprietà namespace del file build.gradle a livello di modulo, ha un prefisso al nome. Ad esempio, se lo spazio dei nomi è "com.example.myapp", il nome dell'attività seguente si risolve 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, vedi Impostare lo spazio dei nomi.

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

Filtri per intent

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

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

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

Per ulteriori informazioni, consulta il documento Intent e filtri di intent.

Icone ed etichette

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

In ogni caso, l'icona e l'etichetta impostate in un elemento principale diventano i valori predefiniti 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 ogni componente dell'app, come tutte le attività.

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

Ti consigliamo di modificare l'icona di un filtro per intent se fornisce un'azione unica che vuoi indicare meglio nella finestra di dialogo di selezione. Per ulteriori informazioni, vedi Consentire ad altre app di iniziare le tue attività.

Autorizzazioni

Le app per Android devono richiedere l'autorizzazione ad accedere a dati utente sensibili, come contatti e SMS, o ad alcune 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 app in fase di runtime. 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 accesso a queste funzionalità non andranno a buon fine.

La tua app può anche proteggere i propri componenti con le autorizzazioni. Può utilizzare qualsiasi autorizzazione definita da Android, come elencato in android.Manifest.permission, oppure 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, consulta la sezione Autorizzazioni su Android.

Compatibilità dei dispositivi

Nel file manifest puoi anche dichiarare i tipi di funzionalità hardware o software richieste dalla tua app e, di conseguenza, i tipi di dispositivi con cui la tua app è 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 dall'app.

Esistono diversi tag manifest che definiscono i dispositivi con cui è compatibile la tua app. Di seguito sono riportate alcune delle più comuni.

<uses-feature>

L'elemento <uses-feature> ti consente di dichiarare le funzionalità hardware e software di cui la tua app ha bisogno. Ad esempio, se la tua app non può raggiungere le funzionalità di base su un dispositivo senza un sensore per la bussola, puoi dichiarare il sensore per la 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 la tua app disponibile sui Chromebook, devi prendere in considerazione alcune importanti limitazioni di funzionalità hardware e software. Per ulteriori informazioni, consulta la sezione Compatibilità del file manifest delle app per Chromebook.

<uses-sdk>

A ogni versione successiva della piattaforma vengono spesso aggiunte 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. Di conseguenza, se utilizzi Android Studio, specifica al loro posto i valori minSdkVersion e targetSdkVersion:

trendy

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 maggiori 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 sulla compatibilità dei dispositivi.

Convenzioni per i file

In questa sezione vengono descritte le convenzioni e le regole generalmente applicabili a tutti gli elementi e gli attributi del file manifest.

Elementi
Sono obbligatori solo gli elementi <manifest> e <application>. Ciascuno di essi deve avvenire una sola volta. La maggior parte degli altri elementi può verificarsi zero o più volte. Tuttavia, alcune di queste 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 inseriti in qualsiasi ordine. Esistono due principali eccezioni a questa regola:

  • Un elemento <activity-alias> deve seguire l'elemento <activity> di cui è un alias.
  • L'elemento <application> deve essere l'ultimo all'interno dell'elemento <manifest>.
Attributi
Tecnicamente, tutti gli attributi sono facoltativi. Tuttavia, è necessario specificare molti attributi per consentire a un elemento di compiere il proprio 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:, ad esempio android:alwaysRetainTaskState. Poiché il prefisso è universale, generalmente la documentazione lo omette quando fa riferimento agli attributi per nome.

Più valori
Se è possibile specificare più di un valore, l'elemento viene quasi sempre ripetuto, invece di elencare più valori all'interno di un singolo elemento. Ad esempio, un filtro per 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 che vengono mostrati agli utenti, come il titolo di un'attività o l'icona dell'app. Il valore di questi attributi potrebbe variare in base alla lingua dell'utente o ad altre configurazioni del dispositivo (ad esempio, fornire dimensioni delle icone diverse in base alla densità dei pixel del dispositivo), pertanto i valori devono essere impostati da una risorsa o da un tema, anziché essere impostati come hardcoded nel file manifest. Il valore effettivo può quindi variare in base alle risorse alternative fornite per le diverse configurazioni dispositivo.

Le risorse sono espresse come valori con il seguente formato:

"@[package:]type/name"

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

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

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

Per ulteriori informazioni su come aggiungere risorse al progetto, consulta Panoramica delle risorse per le app.

Per applicare invece 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 le doppie barre rovesciate (\\) per l'escape dei caratteri, ad esempio \\n per una nuova riga o \\uxxxx per un carattere Unicode.

Riferimento agli elementi manifest

La seguente tabella 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 è compatibile l'applicazione.
<data> Aggiunge una specifica dei dati a un filtro per intent.
<grant-uri-permission> Specifica i sottoinsiemi di dati dell'app a cui il fornitore di contenuti principale è autorizzato ad accedere.
<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 ricevitore può rispondere.
<manifest> L'elemento principale del file AndroidManifest.xml.
<meta-data> Una coppia nome-valore relativa a un elemento di dati arbitrari aggiuntivi che possono essere forniti 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 di altre applicazioni.
<permission-group> Dichiara un nome per un raggruppamento logico di autorizzazioni correlate.
<permission-tree> Dichiara il nome di base per una struttura 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 sull'applicazione di filtri alla visibilità dei pacchetti.
<receiver> Dichiara un componente BroadcastRicevitore.
<service> Dichiara un componente del 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 quelle supportate dalla tua app.
<uses-configuration> Indica 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> Consente di specificare un'autorizzazione di sistema che l'utente deve concedere per il corretto funzionamento dell'app.
<uses-permission-sdk-23> Specifica che un'app richiede un'autorizzazione specifica, 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 a livello di API.

Esempio di file manifest

Il codice XML seguente è un AndroidManifest.xml di esempio semplice 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>