Présentation du fichier manifeste d'application

Chaque projet d'application doit disposer d'un fichier AndroidManifest.xml, portant précisément 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, des services, des broadcast receivers et des 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 des 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 Il déclare également toutes les autorisations dont les autres applications doivent disposer pour accéder au contenu de cette application. Vous trouverez plus d'informations sur les autorisations dans la 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. Pour en savoir plus sur la compatibilité des appareils, consultez la section suivante.

Si vous utilisez Android Studio pour compiler votre application, le fichier manifeste est créé automatiquement. La plupart des éléments essentiels du fichier manifeste sont ajoutés à mesure que vous compilez votre 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:

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.

Indiquez 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, le nom est précédé de l'espace de noms de l'application, à partir de la propriété namespace du fichier build.gradle au niveau du module. 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 en savoir plus sur la définition du nom du package ou de l'espace de noms, consultez Définir l'espace de noms.

Si vous avez des composants d'application qui résident dans des sous-packages, tels que com.example.myapp.purchases, la valeur name doit ajouter les noms de sous-package 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 une action doit être effectuée, la catégorie du composant attendu 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 l'icône déclarée pour le composant parent, à savoir l'élément <activity> ou <application>.

Vous pouvez modifier l'icône d'un filtre d'intent s'il fournit une action unique que vous souhaitez mieux indiquer 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 requises par votre application et, par extension, les types d'appareils avec lesquels votre application est compatible. Le Google Play Store ne permet pas aux utilisateurs d'installer votre application sur des appareils qui ne proposent pas les fonctionnalités ou la version du système requises par votre application.

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 obtenir les fonctionnalités de base sur un appareil sans capteur de boussole, vous pouvez déclarer le capteur de boussole comme requis à l'aide de la balise suivante dans le fichier manifeste:

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

Remarque : Si vous souhaitez que votre application soit disponible sur les Chromebooks, vous devez tenir compte de certaines limites importantes au niveau des fonctionnalités matérielles et logicielles. Pour en savoir plus, consultez la section Compatibilité des fichiers manifestes 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, sachez que les attributs de l'élément <uses-sdk> sont remplacés par les propriétés correspondantes dans le fichier build.gradle. Par conséquent, si vous utilisez Android Studio, spécifiez-y les valeurs minSdkVersion et targetSdkVersion:

Groovy

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

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 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 le <activity> dont il est l'alias.
  • L'élément <application> doit être le dernier élément 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, les valeurs par défaut sont indiquées dans la documentation de référence.

À l'exception de certains attributs de l'élément racine <manifest>, tous les noms d'attributs commencent par un préfixe android:, tel que 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 répertorier 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 taille d'icône différente en fonction de la densité en pixels de l'appareil). Les valeurs doivent donc être définies à partir d'une ressource ou d'un thème, et non 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 en savoir plus sur l'ajout de ressources à votre projet, consultez 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 barres obliques inverses (\\) pour échapper les caractères, tels que \\n pour un retour à la 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.

<action> Ajoute une action à un filtre d'intent.
<activity> Déclare un composant d'activité.
<activity-alias> Déclare un alias pour une activité.
<application> Déclare l'application.
<category> Ajoute un nom de catégorie à un filtre d'intent.
<compatible-screens> Spécifie chaque configuration d'écran avec laquelle l'application est compatible.
<data> Ajoute une spécification de données à un filtre d'intent.
<grant-uri-permission> Indique les sous-ensembles de données d'application auxquels le fournisseur de contenu parent est autorisé à accéder.
<instrumentation> Déclare une classe Instrumentation qui vous permet de surveiller l'interaction d'une application avec le système.
<intent-filter> Spécifie les types d'intents auxquels une activité, un service ou un broadcast receiver peut répondre.
<manifest> Élément racine du fichier AndroidManifest.xml.
<meta-data> Paire nom-valeur pour un élément de données arbitraires supplémentaires pouvant être fournies au composant parent.
<path-permission> Définit le chemin d'accès et les autorisations requises pour un sous-ensemble de données spécifique au sein d'un fournisseur de contenu.
<permission> Déclare une autorisation de sécurité pouvant être utilisée pour limiter l'accès à des composants ou à des fonctionnalités propres à cette application ou à d'autres.
<permission-group> Déclare un nom pour un regroupement logique d'autorisations associées.
<permission-tree> Indique le nom de base d'une arborescence d'autorisations.
<provider> Déclare un composant de fournisseur de contenu.
<queries> Déclare l'ensemble d'autres applications auxquelles votre application a l'intention d'accéder. Pour en savoir plus, consultez le guide sur le filtrage de la visibilité des packages.
<receiver> Déclare un composant broadcast receiver.
<service> Déclare un composant de service.
<supports-gl-texture> Indique un seul format de compression de texture GL compatible avec l'application.
<supports-screens> Indique les tailles d'écran compatibles avec votre application et active le mode de compatibilité pour les écrans plus grands que ceux que votre application prend en charge.
<uses-configuration> Indique les caractéristiques d'entrée spécifiques requises par l'application.
<uses-feature> Déclare une seule fonctionnalité matérielle ou logicielle utilisée par l'application.
<uses-library> Indique une bibliothèque partagée avec laquelle l'application doit être associée.
<uses-native-library> Indique une bibliothèque partagée native fournie par le fournisseur avec laquelle l'application doit être associée.
<uses-permission> Indique une autorisation système que l'utilisateur doit accorder pour que l'application fonctionne correctement.
<uses-permission-sdk-23> Indique qu'une application requiert une autorisation particulière, mais uniquement si elle est installée sur un appareil équipé d'Android 6.0 (niveau d'API 23) ou version ultérieure.
<uses-sdk> Vous permet d'exprimer la compatibilité d'une application avec une ou plusieurs versions de la plate-forme Android à l'aide d'un niveau d'API exprimé sous forme d'entier.

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>