Présentation du fichier manifeste d'application

Chaque projet d'application doit disposer d'un fichier AndroidManifest.xml, portant exactement ce nom, à la racine de l'ensemble de sources du projet. Le fichier manifeste décrit les informations essentielles concernant votre application aux outils de compilation et au système d'exploitation Android, ainsi qu'à Google Play.

Entre autres éléments, le fichier manifeste est tenu de déclarer les éléments suivants :

• Les composants de l'application, y compris l'ensemble des activités, services, broadcast receivers et fournisseurs de contenu. Chaque composant doit définir des propriétés de base, telles que le nom de sa classe Kotlin ou Java. Il peut également déclarer des fonctionnalités telles que les configurations d'appareil qu'il peut gérer et les filtres d'intent qui décrivent comment démarrer le composant. Pour en savoir plus sur les composants d'application, consultez la section suivante.
• Les autorisations dont l'application a besoin pour accéder aux parties protégées du système ou à d'autres applications Le fichier manifeste déclare également toutes les autorisations dont les autres applications doivent disposer pour accéder au contenu de cette application. En savoir plus sur les autorisations dans une section suivante.
• Les fonctionnalités matérielles et logicielles requises par l'application, qui déterminent quels appareils peuvent installer l'application depuis Google Play. En savoir plus sur la compatibilité des appareils dans une section suivante

Si vous utilisez Android Studio pour compiler votre application, le fichier manifeste est créé pour vous et la plupart des éléments essentiels du fichier manifeste sont ajoutés à mesure que vous compilez l'application, en particulier lorsque vous utilisez des modèles de code.

Fonctionnalités du fichier

Les sections suivantes décrivent comment certaines des caractéristiques les plus importantes de votre application sont reflétées dans le fichier manifeste.

Composants de l'application

Pour chaque composant d'application que vous créez dans votre application, déclarez un élément XML correspondant dans le fichier manifeste:

• <activity> pour chaque sous-classe de Activity
• <service> pour chaque sous-classe de Service
• <receiver> pour chaque sous-classe de BroadcastReceiver
• <provider> pour chaque sous-classe de ContentProvider

Si vous sous-classez l'un de ces composants sans le déclarer dans le fichier manifeste, le système ne peut pas le démarrer.

Spécifiez le nom de votre sous-classe avec l'attribut name en utilisant la désignation de package complète. Par exemple, une sous-classe Activity est déclarée comme suit:

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

Toutefois, si le premier caractère de la valeur name est un point, l'espace de noms de l'application, à partir de la propriété namespace du fichier build.gradle au niveau du module, est ajouté au nom en tant que préfixe. Par exemple, si l'espace de noms est "com.example.myapp", le nom d'activité suivant est résolu en com.example.myapp.MainActivity:

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

Pour savoir comment définir le nom du package ou l'espace de noms, consultez Définir l'espace de noms.

Si certains de vos composants d'application se trouvent dans des sous-packages, tels que com.example.myapp.purchases, la valeur name doit ajouter les noms des sous-packages manquants (tels que ".purchases.PayActivity") ou utiliser le nom de package complet.

Filtres d'intent

Les activités, les services et les broadcast receivers des applications sont activés par des intents. Un intent est un message défini par un objet Intent qui décrit une action à effectuer, y compris les données sur lesquelles l'action doit être exécutée, la catégorie de composant à utiliser pour effectuer l'action et d'autres instructions.

Lorsqu'une application émet un intent pour le système, le système localise un composant d'application qui peut gérer l'intent en fonction des déclarations de filtre d'intent dans le fichier manifeste de chaque application. Le système lance une instance du composant correspondant et transmet l'objet Intent à ce composant. Si plusieurs applications peuvent gérer l'intent, l'utilisateur peut sélectionner celle à utiliser.

Un composant d'application peut avoir un nombre illimité de filtres d'intent (définis avec l'élément <intent-filter>), chacun décrivant une fonctionnalité différente de ce composant.

Pour en savoir plus, consultez le document Intents et filtres d'intent.

Icônes et libellés

Un certain nombre d'éléments du fichier manifeste possèdent des attributs icon et label servant respectivement à afficher une petite icône et à afficher un libellé de texte pour les utilisateurs du composant d'application correspondant.

Dans tous les cas, l'icône et le libellé définis dans un élément parent deviennent les valeurs icon et label par défaut pour tous les éléments enfant. Par exemple, l'icône et le libellé définis dans l'élément <application> correspondent à l'icône et au libellé par défaut de chacun des composants de l'application, comme toutes les activités.

L'icône et le libellé définis dans l'élément <intent-filter> d'un composant sont présentés à l'utilisateur chaque fois que ce composant est proposé en tant qu'option permettant de répondre à un intent. Par défaut, cette icône est héritée de toute icône déclarée pour le composant parent, l'élément <activity> ou <application>.

Vous pouvez modifier l'icône pour un filtre d'intent, si celui-ci fournit une action unique que vous souhaitez mettre en évidence dans la boîte de dialogue du sélecteur. Pour en savoir plus, consultez Autoriser d'autres applications à démarrer votre activité.

Autorisations

Les applications Android doivent demander l'autorisation d'accéder aux données utilisateur sensibles, telles que les contacts et les SMS, ou à certaines fonctionnalités système, comme l'appareil photo et l'accès à Internet. Chaque autorisation est identifiée par un libellé unique. Par exemple, une application qui doit envoyer des SMS doit comporter la ligne suivante dans le fichier manifeste :

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

À partir d'Android 6.0 (niveau d'API 23), l'utilisateur peut approuver ou refuser certaines autorisations d'application au moment de l'exécution. Cependant, quelle que soit la version d'Android compatible avec votre application, vous devez déclarer toutes les demandes d'autorisation avec un élément <uses-permission> dans le fichier manifeste. Si l'autorisation est accordée, l'application peut utiliser les fonctionnalités protégées. Si ce n'est pas le cas, ses tentatives d'accès à ces fonctionnalités échouent.

Votre application peut également protéger ses propres composants à l'aide d'autorisations. Elle peut utiliser n'importe quelle autorisation définie par Android, dans android.Manifest.permission, ou une autorisation déclarée dans une autre application. Votre application peut également définir ses propres autorisations. Une nouvelle autorisation est déclarée avec l'élément <permission>.

Pour en savoir plus, consultez la section Autorisations sur Android.

Compatibilité avec les appareils

Le fichier manifeste vous permet également de déclarer les types de fonctionnalités matérielles ou logicielles nécessaires à votre application, ainsi que les types d'appareils compatibles avec votre application. Le Google Play Store n'autorise pas les utilisateurs à installer votre application sur les appareils qui n'offrent pas les fonctionnalités ni la version du système requises par celle-ci.

Plusieurs balises du fichier manifeste définissent les appareils compatibles avec votre application. Voici quelques-unes des plus courantes.

<uses-feature>

L'élément <uses-feature> vous permet de déclarer les fonctionnalités matérielles et logicielles dont votre application a besoin. Par exemple, si votre application ne peut pas assurer des fonctionnalités de base sur un appareil sans capteur de boussole, vous pouvez déclarer que le capteur de boussole est requis à l'aide de la balise de fichier manifeste suivante:

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

Remarque : Si vous souhaitez rendre votre application disponible sur les Chromebooks, vous devez tenir compte de certaines limites importantes concernant les fonctionnalités matérielles et logicielles. Pour en savoir plus, consultez Compatibilité du fichier manifeste d'application pour les Chromebooks.

<uses-sdk>

Souvent, chaque version de plate-forme successive ajoute de nouvelles API non disponibles dans la version précédente. Pour indiquer la version minimale compatible avec votre application, votre fichier manifeste doit inclure la balise <uses-sdk> et son attribut minSdkVersion.

Toutefois, veillez à ce que les attributs de l'élément <uses-sdk> soient remplacés par les propriétés correspondantes dans le fichier build.gradle. Par conséquent, si vous utilisez Android Studio, spécifiez les valeurs minSdkVersion et targetSdkVersion à la place:

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

Pour en savoir plus sur le fichier build.gradle, découvrez comment configurer votre compilation.

Pour savoir comment déclarer la compatibilité de votre application avec différents appareils, consultez la page Présentation de la compatibilité des appareils.

Conventions de fichiers

Cette section décrit les conventions et les règles qui s'appliquent généralement à tous les éléments et attributs du fichier manifeste.

Éléments

Seuls les éléments <manifest> et <application> sont obligatoires. Chacun d'eux ne doit apparaître qu'une seule fois. La plupart des autres éléments peuvent apparaître plusieurs fois ou ne pas apparaître du tout. Cependant, certains d'entre eux doivent être présents pour que le fichier manifeste soit utile.

Toutes les valeurs sont définies via des attributs et non en tant que données de caractères au sein d'un élément.

Les éléments de même niveau ne sont généralement pas ordonnés. Par exemple, les éléments <activity>, <provider> et <service> peuvent être placés dans n'importe quel ordre. Il existe deux exceptions clés à cette règle :

• Un élément <activity-alias> doit suivre l'<activity> dont il est l'alias.
• L'élément <application> doit être le dernier élément au sein de l'élément <manifest>.

Attributs

Techniquement, tous les attributs sont facultatifs. Cependant, de nombreux attributs doivent être spécifiés pour qu'un élément puisse remplir son objectif. Pour les attributs vraiment facultatifs, la documentation de référence indique les valeurs par défaut.

À l'exception de certains attributs de l'élément racine <manifest>, tous les noms d'attributs commencent par un préfixe android:, comme android:alwaysRetainTaskState. Étant donné que le préfixe est universel, il est généralement omis dans la documentation lorsque vous faites référence à des attributs par nom.

Valeurs multiples

Si vous pouvez spécifier plusieurs valeurs, il est presque toujours préférable de répéter l'élément pour chaque valeur au lieu de regrouper ces valeurs au sein d'un même élément. Par exemple, un filtre d'intent peut présenter plusieurs actions :

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

Valeurs des ressources

Certains attributs ont des valeurs visibles par les utilisateurs, par exemple le titre d'une activité ou l'icône de votre application. La valeur de ces attributs peut varier en fonction de la langue de l'utilisateur ou d'autres configurations de l'appareil (par exemple, pour fournir une icône différente en fonction de la densité en pixels de l'écran de l'appareil). Les valeurs doivent donc être définies à partir d'une ressource ou d'un thème, au lieu d'être codées en dur dans le fichier manifeste. La valeur réelle peut ensuite varier en fonction des ressources alternatives que vous fournissez pour différentes configurations d'appareil.

Les ressources sont exprimées sous forme de valeurs au format suivant :

"@[package:]type/name"

Vous pouvez omettre le nom package si la ressource est fournie par votre application (y compris si elle est fournie par une dépendance de la bibliothèque, car les ressources de la bibliothèque sont fusionnées avec les vôtres). Le seul autre nom de package valide est android, lorsque vous souhaitez utiliser une ressource du framework Android.

type est un type de ressource, tel que string ou drawable, et name est le nom qui identifie la ressource concernée. Voici un exemple :

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

Pour savoir comment ajouter des ressources à votre projet, consultez la section Présentation des ressources d'application.

Pour appliquer à la place une valeur définie dans un thème, le premier caractère doit être ? au lieu de @ :

"?[package:]type/name"

Valeurs de chaîne

Lorsqu'une valeur d'attribut est une chaîne, utilisez des doubles barres obliques inverses (\\) pour échapper les caractères, tels que \\n pour une nouvelle ligne ou \\uxxxx pour un caractère Unicode.

Documentation de référence sur les éléments du fichier manifeste

Le tableau suivant fournit des liens vers les documents de référence pour tous les éléments valides du fichier AndroidManifest.xml.

Limites

Le nombre d'occurrences des balises suivantes dans un fichier manifeste est limité:

La longueur maximale des attributs suivants est limitée:

Exemple de fichier manifeste

Le code XML ci-dessous est un exemple simple de AndroidManifest.xml qui déclare deux activités pour l'application.

<?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>