Panoramica del file manifest dell'app

Ogni progetto di app deve avere un file AndroidManifest.xml con esattamente quel nome nella radice del set di origini del progetto. Il file manifest descrive le 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 è necessario per dichiarare quanto segue:

• I componenti dell'app, tra cui tutte le attività, i servizi, i ricevitori di trasmissione e i content provider. 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 per intent che descrivono come avviare il componente. Scopri di più sui componenti dell'app in una sezione successiva.
• Le autorizzazioni necessarie all'app per accedere a parti protette del sistema o ad altre app. Dichiara inoltre le autorizzazioni che altre app devono avere se vogliono accedere ai contenuti di questa app. Scopri di più sulle autorizzazioni in una sezione successiva.
• Le funzionalità hardware e software richieste dall'app, che influiscono sui dispositivi che possono installarla da Google Play. Scopri di più sulla compatibilità dei dispositivi in una sezione successiva.

Se utilizzi Android Studio per creare la tua app, il file manifest viene creato automaticamente e la maggior parte degli elementi essenziali del manifest vengono aggiunti man mano che crei l'app, soprattutto quando utilizzi i modelli di codice.

Funzionalità dei file

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

Componenti app

Per ogni componente dell'app che crei nella tua 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 crei una sottoclasse di uno di questi componenti senza dichiararla nel file manifest, il sistema non può avviarla.

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

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

Tuttavia, se il primo carattere nel valore name è un punto, il prefisso dello spazio dei nomi dell'app, dalla proprietà namespace del file build.gradle a livello di modulo, viene aggiunto al nome. 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 maggiori 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 dei sottopacchetti mancanti, ad esempio ".purchases.PayActivity", o utilizzare il nome del pacchetto completo.

Filtri per intent

Attività, servizi e ricevitori di trasmissione delle app vengono attivati dagli intent. Un intent è un messaggio definito da un oggetto Intent che descrive un'azione da eseguire, inclusi i dati su cui agire, la categoria di componente che deve 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 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 quale app utilizzare.

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

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

Icone ed etichette

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

In ogni caso, l'icona e l'etichetta impostate in un elemento principale diventano il valore predefinito 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 soddisfare un intent. Per impostazione predefinita, questa icona viene ereditata dall'icona dichiarata per il componente principale, ovvero l'elemento <activity> o <application>.

Potresti voler modificare l'icona per 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 avviare l'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 SMS deve avere la seguente riga nel 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 runtime. Indipendentemente dalla versione di Android supportata dall'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 tentativi di accesso a queste funzionalità non vanno 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, o un'autorizzazione dichiarata in un'altra app. La tua app può anche definire le proprie autorizzazioni. Una nuova autorizzazione viene dichiarata con l'elemento <permission>.

Per ulteriori informazioni, vedi Autorizzazioni su Android.

Compatibilità dei dispositivi

Il file manifest è anche il luogo in cui puoi 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 del sistema richieste dalla tua app.

Esistono diversi tag del 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 la tua app ha bisogno. Ad esempio, se la tua app non riesce a svolgere 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 disponibile la tua app sui Chromebook, devi tenere conto di alcune limitazioni importanti delle funzionalità hardware e software. Per saperne di più, vedi Compatibilità del file manifest dell'app per Chromebook.

<uses-sdk>

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

Tieni presente, tuttavia, 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 lì:

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
        ...
    }
}

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 saperne di più su come dichiarare il supporto della tua app per diversi dispositivi, consulta la panoramica della compatibilità dei dispositivi.

Convenzioni sui file

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

Elementi

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

Tutti i valori vengono impostati tramite attributi, non come dati di caratteri 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 eccezioni principali 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, molti attributi devono essere specificati 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> radice, tutti i nomi degli attributi iniziano con un prefisso android:, ad esempio android:alwaysRetainTaskState. Poiché il prefisso è universale, la documentazione in genere 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 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 visualizzati dagli utenti, ad esempio il titolo di un'attività o l'icona della tua app. Il valore di questi attributi potrebbe variare in base alla lingua dell'utente o ad altre configurazioni del dispositivo (ad esempio per fornire una dimensione diversa dell'icona in base alla densità di pixel del dispositivo), pertanto i valori devono essere impostati da una risorsa o un tema, anziché essere codificati nel file manifest. Il valore effettivo può quindi cambiare in base alle risorse alternative che fornisci per diverse configurazioni del dispositivo.

Le risorse sono espresse come valori nel seguente formato:

"@[package:]type/name"

Puoi omettere il nome package se la risorsa è fornita dalla tua app (incluso 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 tuo progetto, leggi Panoramica delle risorse dell'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 barre rovesciate doppie (\\) per eseguire l'escape dei caratteri, ad esempio \\n per una nuova riga o \\uxxxx per un carattere Unicode.

Riferimento agli elementi del file manifest

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

Limiti

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

I seguenti attributi hanno un limite di lunghezza massima:

File manifest di esempio

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