Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica del file manifest dell'app

Ogni progetto di app deve avere un file AndroidManifest.xml, con lo stesso nome, nella radice del set di origini del progetto. Il file manifest descrive informazioni essenziali sulla tua app per gli strumenti di creazione di Android, il sistema operativo Android e Google Play.

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

I componenti dell'app, inclusi tutte le attività, i servizi, i destinatari della trasmissione e i fornitori di contenuti. Ogni componente deve definire le proprietà di base, come il nome della relativa classe Kotlin o Java. Può anche dichiarare funzionalità, ad esempio le configurazioni dei dispositivi che è in grado di gestire, e filtri di intent che descrivono come può essere avviato il componente. Scopri di più sui componenti delle 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 le altre app devono disporre per 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, soprattutto quando utilizzi i modelli di codice.

Funzionalità dei file

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

Componenti dell'app

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

<activity> per ogni sottoclasse di Activity
<service> per ogni sottoclasse di Service
<receiver> per ogni sottoclasse di BroadcastReceiver
<provider> per ogni sottoclasse di ContentProvider

Se sottoclassi uno qualsiasi 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. Ad esempio, se lo spazio dei nomi è "com.example.myapp", il seguente nome dell'attività si risolve in com.example.myapp.MainActivity:

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

Per saperne di più sull'impostazione del nome o dello spazio dei nomi del pacchetto, vedi Impostare lo spazio dei nomi.

Se alcuni componenti dell'app risiedono 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 annunci vengono attivati dagli 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 gestirlo 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 tale componente. Se più app sono in grado di gestire l'intent, l'utente può selezionarne 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 funzionalità diversa del componente.

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

Icone ed etichette

Diversi elementi del file manifest hanno attributi icon e label per mostrare rispettivamente un'icona 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 ciascuno dei componenti dell'app, come 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 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 del selettore. Per ulteriori informazioni, vedi Consentire ad altre app di iniziare l'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 file manifest. Se l'autorizzazione viene concessa, l'app può utilizzare le funzionalità protette. In caso contrario, i tentativi di accesso 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. È stata 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 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 dalla tua 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 necessarie per la tua app. Ad esempio, se la tua app non può raggiungere le funzionalità di base su un dispositivo senza sensore per la bussola, puoi dichiarare il sensore 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 limitazioni delle funzionalità hardware e software importanti. 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 l'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 lì 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 relative ai file

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

Elementi

Sono obbligatori solo gli elementi <manifest> e <application>. Ciascuno deve comparire una sola volta. La maggior parte degli altri elementi può verificarsi zero o più volte. Tuttavia, alcune di queste devono essere presenti affinché il file manifest sia utile.

Tutti i valori vengono impostati tramite attributi, non come dati 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 eccezioni principali a questa regola:

Un elemento <activity-alias> deve seguire il comando <activity> per 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 in modo che un elemento possa raggiungere 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 si fa riferimento agli attributi per nome.

Più valori

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

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 dalla libreria, perché le risorse di 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 un valore definito in un tema, il primo carattere deve essere ? anziché @:

"?[package:]type/name"

Valori stringa

Dove 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 per gli 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 può rispondere un'attività, un servizio o un ricevitore di trasmissioni.
`<manifest>`	L'elemento principale del file `AndroidManifest.xml`.
`<meta-data>`	Una coppia nome-valore per un elemento di dati arbitrari aggiuntivi che possono essere forniti al componente padre.
`<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 il nome per un raggruppamento logico di autorizzazioni correlate.
`<permission-tree>`	Dichiara il nome di base per una struttura di autorizzazioni.
`<provider>`	Dichiara il 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 del ricevitore per la trasmissione.
`<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 dall'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>`	Specifica un'autorizzazione di sistema che l'utente deve concedere per il corretto funzionamento dell'app.
`<uses-permission-sdk-23>`	Consente di specificare che un'app richiede un'autorizzazione particolare, 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 mediante un numero intero a livello di API.

Esempio di file manifest

Il codice XML seguente è 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>