Gestire i file manifest

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina descrive come funziona l'unione del manifest e come puoi applicare le preferenze di unione per risolvere i conflitti di unione. Per un'introduzione al file manifest dell'app, consulta la panoramica del file manifest dell'app.

Unire più file manifest

Il file APK o Android App Bundle può contenere un solo AndroidManifest.xml file, ma il progetto Android Studio può contenere diversi file manifest forniti dal set di origine principale, dalle varianti di build e dalle librerie importate. Durante la compilazione dell'app, la compilazione Gradle unisce tutti i file manifest in un unico file manifest che viene pacchettizzato nell'app.

Lo strumento di unione manifest combina tutti gli elementi XML di ogni file seguendo le strategie di unione ed obbedendo alle preferenze di unione che hai definito con attributi XML speciali.

Suggerimento:utilizza la visualizzazione Manifest unito, descritta in una sezione successiva, per visualizzare l'anteprima dei risultati del manifest unito e trovare gli errori di conflitto.

Unisci priorità

Lo strumento di unione combina tutti i file manifest in un unico file in sequenza, in base alla priorità di ciascun file manifest. Ad esempio, se hai tre file manifest, il manifest con la priorità più bassa viene unito al manifest con la priorità successiva e poi a quello con la priorità più alta, come illustrato nella figura 1.

Esistono tre tipi di base di file manifest che possono essere uniti tra loro e le relative priorità di unione sono le seguenti (la priorità più alta è la prima):

1. File manifest per la variante di build

   Se hai più set di origini per la tua variante, le priorità del manifest sono le seguenti:

   • File manifest della variante di compilazione (ad esempio src/demoDebug/)
   • Manifest del tipo di build (ad esempio src/debug/)
   • File manifest della versione del prodotto (ad esempio src/demo/)

     Se utilizzi le dimensioni del gusto, le priorità del manifest corrispondono all'ordine in cui ogni dimensione è elencata nella proprietà flavorDimensions (la prima è la priorità più alta).

2. File manifest principale per il modulo dell'app
3. File manifest di una raccolta inclusa

   Se hai più librerie, le relative priorità del manifest corrispondono all'ordine in cui appaiono nel blocco Gradle dependencies.

Ad esempio, un file manifest della libreria viene unito al file manifest principale, che a sua volta viene unito al file manifest della variante di build. Tieni presente che si tratta delle stesse priorità di unione per tutti i set di origini, come descritto in Creare set di origini.

Importante: le configurazioni di compilazione del file build.gradle sostituiscono gli attributi corrispondenti nel file manifest unito. Ad esempio, minSdk del file build.gradle obuild.gradle.kts sostituisce l'attributo corrispondente nell'elemento manifest<uses-sdk>. Per evitare confusione, ometti l'elemento <uses-sdk> e definisci queste proprietà solo nel file build.gradle. Per maggiori dettagli, consulta Configurare la compilazione.

Euristiche per i conflitti di unione

Lo strumento di unione può associare logicamente ogni elemento XML di un manifest a un elemento corrispondente in un altro manifest. Per informazioni dettagliate sul funzionamento della corrispondenza, consulta le priorità di unione nella sezione precedente.

Se un elemento del manifest con priorità inferiore non corrisponde a nessun elemento del manifest con priorità superiore, viene aggiunto al manifest unito. Tuttavia, se esiste un elemento corrispondente, lo strumento di unione tenta di combinare tutti gli attributi di ciascuno nello stesso elemento. Se lo strumento rileva che entrambi i manifest contengono lo stesso attributo con valori diversi, si verifica un conflitto di unione.

La tabella 1 mostra i possibili risultati quando lo strumento di unione tenta di combinare tutti gli attributi nello stesso elemento.

Tabella 1. Comportamento di unione predefinito per i valori dell'attributo

Tuttavia, ci sono alcune situazioni in cui lo strumento di unione si comporta in modo diverso per evitare conflitti di unione:

• Gli attributi nell'elemento <manifest> non vengono mai uniti; vengono utilizzati solo gli attributi del manifest con la priorità più alta.
• L'attributo android:required negli elementi <uses-feature> e <uses-library> utilizza un'unione OR. In caso di conflitto, viene applicato "true" e la funzionalità o la libreria richiesta da un manifest è sempre inclusa.
• Gli attributi nell'elemento <uses-sdk> utilizzano sempre il valore del manifest con priorità più alta, tranne nelle seguenti situazioni:
  • Quando il manifest con priorità inferiore ha un valore minSdk superiore, viene visualizzato un errore, a meno che non applichi la regola di unione overrideLibrary.
  • Quando il file manifest di priorità inferiore ha un valore targetSdkVersion inferiore, lo strumento di unione utilizza il valore del file manifest di priorità superiore e aggiunge anche le autorizzazioni di sistema necessarie per garantire che la libreria importata continui a funzionare correttamente (per i casi in cui la versione di Android superiore abbia aumentato le limitazioni delle autorizzazioni). Per ulteriori informazioni su questo comportamento, consulta la sezione relativa alle autorizzazioni implicite del sistema.
• L'elemento <intent-filter> non viene mai associato tra i manifest. Ognuno viene trattato come univoco e viene aggiunto all'elemento principale comune nel manifest unito.

Per tutti gli altri conflitti tra attributi, viene visualizzato un errore e devi indicare allo strumento di unione come risolverlo aggiungendo un attributo speciale nel file manifest con priorità più alta. Consulta la sezione seguente sui indicatori delle regole di unione.

Non fare affidamento sui valori predefiniti degli attributi. Poiché tutti gli attributi unici sono combinati nello stesso elemento, ciò potrebbe causare risultati imprevisti se il manifest con priorità più elevata dipende effettivamente dal valore predefinito di un attributo senza dichiararlo. Ad esempio, se il manifest con priorità più alta non dichiara l'attributo android:launchMode, viene utilizzato il valore predefinito "standard". Tuttavia, se il manifest con priorità inferiore dichiara questo attributo con un valore diverso, questo valore viene applicato al manifest unito, che sostituisce il valore predefinito. Devi definire esplicitamente ogni attributo come vuoi. I valori predefiniti per ogni attributo sono documentati nel riferimento manifest.

Indicatori delle regole di unione

Un indicatore di regola di unione è un attributo XML che puoi utilizzare per esprimere la tua preferenza su come risolvere i conflitti di unione o rimuovere elementi e attributi indesiderati. Puoi applicare un indicatore a un intero elemento o solo ad attributi specifici di un elemento.

Quando unisce due file manifest, lo strumento di unione cerca questi indicatori nel file manifest con priorità più alta.

Tutti gli indicatori appartengono allo spazio dei nomi tools di Android, quindi devi prima dichiarare questo spazio dei nomi nell'elemento <manifest>, come mostrato di seguito:

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

Indicatori dei nodi

Per applicare una regola di unione a un intero elemento XML (a tutti gli attributi di un determinato elemento manifest e a tutti i relativi tag secondari), utilizza i seguenti attributi:

tools:node="merge"

Unisci tutti gli attributi in questo tag e tutti gli elementi nidificati quando non ci sono conflitti utilizzando le euristiche per i conflitti di unione. Questo è il comportamento predefinito per gli elementi.

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="merge">
</activity>

Risultato del manifest unito:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

tools:node="merge-only-attributes"

Unisci gli attributi solo in questo tag; non unire gli elementi nidificati.

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="merge-only-attributes">
</activity>

Risultato del manifest unito:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">
</activity>

tools:node="remove"

Rimuovi questo elemento dal manifest unito. Viene utilizzato quando nel manifest unito viene rilevato un elemento non necessario fornito da un file manifest di priorità inferiore che non è sotto il tuo controllo (ad esempio una libreria importata).

Manifest con priorità bassa:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifest ad alta priorità:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      tools:node="remove"/>
</activity-alias>

Risultato del manifest unito:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

tools:node="removeAll"

È simile a tools:node="remove", ma rimuove tutti gli elementi corrispondenti a questo tipo di elemento (all'interno dello stesso elemento principale).

Manifest con priorità bassa:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifest ad alta priorità:

<activity-alias android:name="com.example.alias">
  <meta-data tools:node="removeAll"/>
</activity-alias>

Risultato del manifest unito:

<activity-alias android:name="com.example.alias">
</activity-alias>

tools:node="replace"

Sostituisci completamente l'elemento con priorità inferiore. In altre parole, se nel manifest con priorità inferiore è presente un elemento corrispondente, ignoralo e utilizzalo esattamente come appare in questo manifest.

Manifest con priorità bassa:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifest ad alta priorità:

<activity-alias android:name="com.example.alias"
    tools:node="replace">
  <meta-data android:name="fox"
      android:value="@string/dingeringeding"/>
</activity-alias>

Risultato del manifest unito:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="fox"
      android:value="@string/dingeringeding"/>
</activity-alias>

tools:node="strict"

Genera un errore di compilazione ogni volta che questo elemento nel manifest con priorità inferiore non corrisponde esattamente all'elemento nel manifest con priorità superiore (a meno che non sia risolto da altri indicatori delle regole di unione). Questo sostituisce le euristiche dei conflitti di unione. Ad esempio, se il manifest con priorità inferiore include un attributo aggiuntivo, la compilazione non va a buon fine (mentre il comportamento predefinito aggiunge l'attributo aggiuntivo al manifest unito).

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="strict">
</activity>

Viene creato un errore di unione del manifest. I due elementi manifest non possono essere diversi in modalità rigorosa. Devi applicare altri indicatori di regole di unione per risolvere queste differenze. Senza tools:node="strict", questi due file possono essere uniti senza errori, come mostrato nell'esempio per tools:node="merge".

Indicatori di attributi

Per applicare una regola di unione solo ad attributi specifici in un tag manifest, utilizza i seguenti attributi. Ogni attributo accetta uno o più nomi di attributo (incluso lo spazio dei nomi dell'attributo), separati da virgole.

tools:remove="attr, ..."

Rimuovi gli attributi specificati dal manifest unito. Viene utilizzato quando il file manifest con priorità inferiore include questi attributi e vuoi assicurarti che non vengano inseriti nel manifest unito.

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:remove="android:windowSoftInputMode">

Risultato del manifest unito:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait">

tools:replace="attr, ..."

Sostituisci gli attributi specificati nel manifest con priorità inferiore con quelli di questo manifest. In altre parole, mantieni sempre i valori del manifest con priorità più elevata.

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:theme="@oldtheme"
    android:exported="false"
    android:windowSoftInputMode="stateUnchanged">

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    tools:replace="android:theme,android:exported">

Risultato del manifest unito:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">

tools:strict="attr, ..."

Genera un errore di compilazione ogni volta che questi attributi nel manifest con priorità inferiore non corrispondono esattamente agli attributi nel manifest con priorità superiore. Questo è il comportamento predefinito per tutti gli attributi, tranne per quelli con comportamenti speciali come descritto nelle euristiche dei conflitti di unione.

Manifest con priorità bassa:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="landscape">
</activity>

Manifest ad alta priorità:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:strict="android:screenOrientation">
</activity>

Viene creato un errore di unione del manifest. Devi applicare altri indicatori di regola di unione per risolvere il conflitto. Questo è il comportamento predefinito, quindi lo stesso risultato si ottiene aggiungendo esplicitamente tools:strict="screenOrientation".

Puoi anche applicare più indicatori a un elemento, come mostrato nell'esempio seguente:

<activity android:name="com.example.ActivityOne"
    android:theme="@oldtheme"
    android:exported="false"
    android:allowTaskReparenting="true"
    android:windowSoftInputMode="stateUnchanged">

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    tools:replace="android:theme,android:exported"
    tools:remove="android:windowSoftInputMode">

Risultato del manifest unito:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:allowTaskReparenting="true"
    android:screenOrientation="portrait">

Selettore di indicatori

Se vuoi applicare gli indicatori delle regole di unione solo a una raccolta specifica importata, aggiungi l'attributo tools:selector con il nome del pacchetto della raccolta.

Ad esempio, con il seguente manifest, la regola di unione remove viene applicata solo quando il file manifest con priorità inferiore proviene dalla libreria com.example.lib1:

<permission android:name="permissionOne"
    tools:node="remove"
    tools:selector="com.example.lib1">

Se il manifest con priorità inferiore proviene da un'altra origine, la remove regola di unione viene ignorata.

Nota:se lo utilizzi con uno degli indicatori di attributo, si applica a tutti gli attributi specificati nell'indicatore.

Sostituisci <uses-sdk> per le librerie importate

Per impostazione predefinita, quando importi una libreria con un valore minSdk superiore a quello del file manifest principale, si verifica un errore e la libreria non può essere importata.

Per fare in modo che lo strumento di unione ignori questo conflitto e importi la libreria mantenendo il valore minSdk inferiore della tua app, aggiungi l'attributo overrideLibrary al tag <uses-sdk>. Il valore dell'attributo può essere costituito da uno o più nomi di pacchetti di librerie (separati da virgole), che indicano le librerie che possono sostituire minSdk del manifest principale.

Ad esempio, se il file manifest principale dell'app applica overrideLibrary come segue:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.app"
          xmlns:tools="http://schemas.android.com/tools">
  <uses-sdk tools:overrideLibrary="com.example.lib1, com.example.lib2"/>
...

Il seguente manifest può essere unito senza errori relativi al tag <uses-sdk> e il manifest unito mantiene minSdk="2" dal manifest dell'app.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.lib1">
   <uses-sdk android:minSdk="4" />
...

Autorizzazioni di sistema implicite

Alcune API Android che in passato erano liberamente accessibili dalle app sono state limitate dalle autorizzazioni di sistema nelle versioni recenti di Android.

Per evitare di interrompere le app che prevedono l'accesso a queste API, le versioni recenti di Android consentono alle app di continuare ad accedere a queste API senza l'autorizzazione se targetSdkVersion è impostato su un valore inferiore alla versione in cui è stata aggiunta la limitazione. Questo comportamento conferisce all'app un'autorizzazione implicita per consentire l'accesso alle API. I manifest uniti con valori diversi per targetSdkVersion possono essere interessati.

Se il file manifest con priorità inferiore ha un valore inferiore per targetSdkVersion che gli fornisce un'autorizzazione implicita e il manifest con priorità superiore non ha la stessa autorizzazione implicita (perché targetSdkVersion è uguale o superiore alla versione in cui è stata aggiunta la limitazione), lo strumento di unione aggiunge esplicitamente l'autorizzazione di sistema al manifest unito.

Ad esempio, se la tua app imposta targetSdkVersion su 4 o versioni successive e importa una biblioteca con targetSdkVersion impostato su 3 o versioni precedenti, lo strumento di unione aggiunge l'autorizzazione WRITE_EXTERNAL_STORAGE al manifest unito.

La tabella 2 elenca tutte le possibili autorizzazioni che possono essere aggiunte al manifest unito:

Tabella 2. Elenco delle autorizzazioni che lo strumento di unione potrebbe aggiungere al manifest unito

Controlla il manifest unito e individua i conflitti

Anche prima di creare l'app, puoi visualizzare un'anteprima del manifest unito. Per visualizzare un'anteprima:

1. In Android Studio, apri il file AndroidManifest.xml.
2. Fai clic sulla scheda Manifesto combinato nella parte inferiore dell'editor.

La visualizzazione Manifest unito mostra i risultati del manifest unito a sinistra e le informazioni su ciascun file manifest unito a destra, come mostrato nella figura 2.

Gli elementi uniti da file manifest di priorità inferiore sono evidenziati in colori diversi a sinistra. La chiave per ogni colore è specificata in Origini manifest.

Figura 2. La visualizzazione Manifest unito.

I file manifest che facevano parte della compilazione, ma che non hanno contribuito con elementi o attributi, sono elencati in Altri file manifest.

Per visualizzare le informazioni sulla provenienza di un elemento, fai clic sull'elemento nel riquadro a sinistra. I dettagli verranno visualizzati in Log dell'unione.

Se si verificano conflitti, vengono visualizzati in Errori di unione insieme a un consiglio su come risolverlo utilizzando i indicatori delle regole di unione.

Gli errori vengono stampati anche nella finestra Log eventi. Per visualizzarli, seleziona Visualizza > Finestre degli strumenti > Log eventi.

Per visualizzare un log completo dell'albero decisionale di unione, puoi trovare il file di log nella directory build/outputs/logs/ del modulo, denominato manifest-merger-buildVariant-report.txt.

Unire i criteri

Lo strumento di unione manifest può associare logicamente ogni elemento XML di un file manifest a un elemento corrispondente in un altro file. L'unione associa ogni elemento utilizzando una chiave di corrispondenza, un valore dell'attributo univoco (ad es. android:name) o l'unicità naturale del tag stesso (ad es. può esserci un solo elemento <supports-screen>).

Se due manifest hanno lo stesso elemento XML, lo strumento unisce i due elementi utilizzando una di tre norme di unione:

Unisci

Combina tutti gli attributi non in conflitto nello stesso tag e unisci gli elementi secondari in base alle rispettive norme di unione. Se alcuni attributi sono in conflitto tra loro, uniscili con gli indicatori delle regole di unione.

Unisci solo elementi secondari

Non combinare o unire gli attributi (mantieni solo gli attributi forniti dal file manifest con la priorità più alta) e unisci gli elementi secondari in base al relativo criterio di unione.

Keep

Lascia l'elemento così com'è e aggiungilo all'elemento principale comune nel file unito. Viene utilizzato solo quando è accettabile che esistano più dichiarazioni dello stesso elemento.

La tabella 3 elenca ogni tipo di elemento, il tipo di criterio di unione utilizzato e la chiave utilizzata per determinare una corrispondenza di elementi tra due manifest:

Tabella 3. Norme di unione degli elementi manifest e chiavi di corrispondenza

Inserire le variabili di compilazione nel manifest

Se devi inserire nel file AndroidManifest.xml variabili definite nel file build.gradle, puoi farlo con la proprietà manifestPlaceholders. Questa proprietà accetta una mappa di coppie chiave-valore, come mostrato di seguito:

android {
    defaultConfig {
        manifestPlaceholders = [hostName:"www.example.com"]
    }
    ...
}

android {
    defaultConfig {
        manifestPlaceholders["hostName"] = "www.example.com"
    }
    ...
}

Puoi quindi inserire uno dei segnaposto nel file manifest come valore dell'attributo:

<intent-filter ... >
    <data android:scheme="https" android:host="${hostName}" ... />
    ...
</intent-filter>

Per impostazione predefinita, gli strumenti di compilazione forniscono anche l'ID applicazione della tua app nel segnaposto ${applicationId}. Il valore corrisponde sempre all'ID applicazione finale per la build corrente, incluse le modifiche in base alle varianti di build. Questo è utile quando vuoi utilizzare uno spazio dei nomi univoco per gli identificatori come un'azione di intent, anche tra le varianti di build.

Ad esempio, se il file build.gradle ha il seguente aspetto:

android {
    defaultConfig {
        applicationId "com.example.myapp"
    }
    flavorDimensions "type"
    productFlavors {
        free {
            applicationIdSuffix ".free"
            dimension "type"
        }
        pro {
            applicationIdSuffix ".pro"
            dimension "type"
        }
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"
    }
    flavorDimensions += "type"
    productFlavors {
        create("free") {
            applicationIdSuffix = ".free"
            dimension = "type"
        }
        create("pro") {
            applicationIdSuffix = ".pro"
            dimension = "type"
        }
    }
}

Dopodiché puoi inserire l'ID applicazione nel manifest come segue:

<intent-filter ... >
    <action android:name="${applicationId}.TRANSMOGRIFY" />
    ...
</intent-filter>

Il risultato del manifest quando crei la versione del prodotto "senza costi" è il seguente:

<intent-filter ... >
   <action android:name="com.example.myapp.free.TRANSMOGRIFY" />
    ...
</intent-filter>

Per saperne di più, consulta Impostare l'ID applicazione.