Outils de framework de compatibilité

Android 11 a introduit de nouveaux outils pour les développeurs permettant de tester et déboguer votre application face aux changements de comportement des versions plus récentes de la plate-forme Android. Ces outils font partie d'un framework de compatibilité qui permet aux développeurs d'activer et de désactiver individuellement les modifications destructives à l'aide d'options pour les développeurs ou d'ADB. Utilisez cette flexibilité lorsque vous vous préparez à cibler la dernière version stable de l'API et lorsque vous testez votre application avec la version preview de la prochaine version d'Android.

Lorsque vous utilisez les outils du framework de compatibilité, la plate-forme Android adapte sa logique interne. Vous n'avez donc pas besoin de modifier votre targetSDKVersion ni de recompiler votre application pour effectuer des tests de base. Étant donné que les modifications peuvent être activées individuellement, vous pouvez isoler, tester et déboguer un changement de comportement à la fois, ou désactiver un seul changement qui pose problème si vous devez d'abord tester autre chose.

Comment identifier les modifications activées

Lorsqu'un changement de comportement est activé, cela peut affecter la façon dont votre application accède aux API de la plate-forme concernées par ce changement. Vous pouvez vérifier quels changements de comportement sont activés à l'aide des options pour les développeurs, Logcat ou les commandes ADB.

Identifier les modifications activées à l'aide des options pour les développeurs

Figure 1 : Écran Modifications de la compatibilité de l'application dans les options pour les développeurs.

Vous pouvez voir quelles modifications sont activées et activer ou désactiver ces modifications dans les options pour les développeurs d'un appareil. Pour accéder à ces options, procédez comme suit:

  1. Si les options pour les développeurs ne sont pas déjà activées, activez-les.
  2. Sur votre appareil, ouvrez l'application Paramètres et accédez à Système > Paramètres avancés > Options pour les développeurs > Modifications de compatibilité des applications.

  3. Sélectionnez votre application dans la liste.

Chaque changement de comportement appartient généralement à l'une des deux catégories suivantes :

  • Modifications qui affectent toutes les applications exécutées sur cette version d'Android, quelle que soit la targetSdkVersion de l'application.

    Ces modifications sont activées par défaut dans le framework de compatibilité et sont listées dans l'interface utilisateur, dans la section Modifications activées par défaut.

  • Modifications qui ne concernent que les applications qui ciblent certaines versions d'Android. Étant donné que ces modifications n'affectent que les applications qui ciblent une version spécifique d'Android, elles sont également appelées modifications contrôlées par targetSDKVersion.

    Ces modifications sont activées par défaut dans le framework de compatibilité si votre application cible une version supérieure à celle de la version d'API répertoriée. Par exemple, un changement de comportement contrôlé par targetSDKVersion dans Android 13 (niveau d'API 33) serait listé dans l'UI dans une section intitulée Activé pour targetSdkVersion >=33. Dans certaines versions antérieures d'Android, cette section s'intitule "Enabled After SDK API_LEVEL" (Activé après le SDK API_LEVEL).

Vous remarquerez également une section dans la figure 1 intitulée Modifications désactivées par défaut. Les modifications incluses dans cette section peuvent avoir plusieurs utilités. Avant d'activer ces modifications, lisez leur description dans la liste des frameworks de compatibilité pour cette version d'Android.

Identifier les modifications activées à l'aide de Logcat

Pour chaque changement de comportement, la première fois que votre application appelle l'API concernée au cours du processus, le système génère un message Logcat semblable à celui-ci :

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

Chaque message Logcat inclut les informations suivantes :

ID de modification
Indique la modification qui affecte l'application. Cette valeur correspond à l'un des changements de comportement repris sur l'écran Modifications de compatibilité des applications (voir figure 1). Dans cet exemple, 194833441 correspond à NOTIFICATION_PERM_CHANGE_ID.
UID
Indique l'application concernée par la modification.
État

Indique si la modification affecte l'application.

L'état peut être l'une des valeurs suivantes :

État Signification
ENABLED La modification est activée et affectera le comportement de l'application si elle utilise les API modifiées.
DISABLED

Cette modification est désactivée et n'aura aucune incidence sur l'application.

Remarque : Si cette modification est désactivée, car le paramètre targetSDKVersion de l'application est inférieur au seuil requis, la modification sera activée par défaut lorsque l'application augmentera de targetSDKVersion pour cibler une version supérieure.
LOGGED La modification est enregistrée dans le framework de compatibilité, mais ne peut pas être activée ni désactivée. Bien qu'il ne soit pas possible d'activer ou de désactiver ce changement, il se peut qu'il affecte toujours le comportement de votre application. Pour en savoir plus, consultez la description de la modification dans la liste des frameworks de compatibilité pour cette version d'Android. Dans de nombreux cas, ces types de modifications sont expérimentaux et peuvent être ignorés.

Identifier les modifications activées à l'aide d'ADB

Exécutez la commande ADB suivante pour afficher l'ensemble des modifications (activées et désactivées) sur l'ensemble de l'appareil :

adb shell dumpsys platform_compat

Le résultat affiche les informations suivantes pour chaque modification :

ID de modification
Identifiant unique de ce changement de comportement. Par exemple, 194833441.
Nom
Nom de ce changement de comportement. Par exemple, NOTIFICATION_PERM_CHANGE_ID.
Critères targetSDKVersion

La targetSDKVersion avec laquelle la modification est contrôlée (le cas échéant).

Par exemple, si cette modification n'est activée que pour les applications ciblant la version 33 ou ultérieure du SDK, enableAfterTargetSdk=32 est renvoyé. Si la modification n'est pas contrôlée par targetSDKVersion, enableAfterTargetSdk=0 est renvoyé.

Remplacements de package

Nom de chaque package pour lequel l'état par défaut de la modification (activé ou désactivé) a été remplacé.

Par exemple, s'il s'agit d'une modification activée par défaut, le nom du package de votre application apparaît dans la liste si vous désactivez la modification à l'aide des options pour les développeurs ou d'ADB. Dans ce cas, le résultat est le suivant :

packageOverrides={com.my.package=false}

Les modifications contrôlées par targetSDKVersion peuvent être activées ou désactivées par défaut. Par conséquent, la liste des packages peut inclure des instances true ou false, selon la targetSDKVersion de chaque application. Exemple :

packageOverrides={com.my.package=true, com.another.package=false}

En savoir plus sur les modifications spécifiques

La liste complète des changements de comportement dans le framework de compatibilité est incluse dans la documentation de chaque version d'Android. Pour en savoir plus, consultez les liens ci-dessous, en fonction de la version d'Android pour laquelle vous testez votre application:

Quand activer/désactiver les modifications ?

L'objectif principal du framework de compatibilité est de vous offrir contrôle et flexibilité lorsque vous testez votre application avec des versions plus récentes d'Android. Cette section décrit certaines stratégies pouvant être utilisées pour déterminer quand activer ou désactiver les modifications lorsque vous testez et déboguez votre application.

Quand désactiver les modifications ?

Le choix du moment où désactiver les modifications dépend généralement du fait que la modification est contrôlée ou non par targetSDKVersion.

Modifications activées pour toutes les applications

Les modifications qui affectent toutes les applications sont activées par défaut pour une version de plate-forme spécifique, quelle que soit la targetSDKVersion de votre application. Vous pouvez donc voir si votre application est affectée en exécutant votre application sur cette version de plate-forme.

Par exemple, si vous vous apprêtez à cibler Android 15 (niveau d'API 35), vous pouvez commencer par installer votre application sur un appareil exécutant Android 15 et la tester à l'aide de vos workflows de test habituels. Si votre application rencontre des problèmes, vous pouvez désactiver la modification à l'origine du problème afin de pouvoir continuer à tester d'autres problèmes.

Étant donné que ces modifications peuvent affecter toutes les applications, indépendamment de la targetSDKVersion, vous devez généralement tester et mettre à jour votre application pour ces changements avant les modifications contrôlées par la targetSDKVersion. Cela garantit à vos utilisateurs une expérience d'application qui ne va pas se dégrader s'ils mettent à jour leur appareil vers une nouvelle version de la plate-forme.

Vous devez également tester ces modifications en priorité, car vous ne pouvez pas les désactiver lorsque vous utilisez une version publique d'Android. Idéalement, vous devriez tester ces modifications pour chaque version d'Android pendant qu'elle est en version preview.

Modifications contrôlées par targetSDKVersion

Si votre application cible une targetSDKVersion spécifique, toutes les modifications contrôlées par cette version sont activées par défaut. Ainsi, lorsque vous passez de la targetSDKVersion de votre application à une nouvelle version, elle sera affectée par de nombreuses nouvelles modifications simultanées.

Comme votre application peut être affectée par plusieurs de ces modifications, vous devrez peut-être désactiver certaines d'entre elles individuellement lorsque vous testerez et déboguerez votre application.

Quand activer les modifications ?

Les modifications contrôlées par une targetSDKVersion spécifique sont désactivées par défaut lorsqu'une application cible une version du SDK inférieure à la version contrôlée. En règle générale, lorsque vous vous préparez à cibler une nouvelle targetSdkVersion, vous avez une liste de modifications de comportements à tester et à déboguer pour votre application.

Par exemple, vous allez peut-être tester votre application par le biais d'une série de changements de plate-forme dans la prochaine targetSdkVersion. À l'aide des options pour les développeurs ou des commandes ADB, vous pouvez activer et tester chaque modification contrôlée une par une, plutôt que de modifier le fichier manifeste de votre application et d'activer chaque modification en même temps. Cette commande supplémentaire peut vous aider à tester les modifications de façon isolée, et vous éviter de devoir déboguer et mettre à jour plusieurs parties de votre application en même temps.

Après avoir activé une modification, vous pouvez tester et déboguer votre application à l'aide de vos workflows de test habituels. Si vous rencontrez des problèmes, consultez vos journaux pour déterminer la cause du problème. Si vous ne parvenez pas à déterminer si le problème est dû à un changement de plate-forme activé, désactivez-le, puis testez à nouveau cette zone de votre application.

Activer ou désactiver les modifications

Le framework de compatibilité vous permet d'activer ou de désactiver chaque modification à l'aide des options pour les développeurs ou des commandes ADB. L'activation ou la désactivation des modifications peut entraîner le plantage de votre application ou la désactivation de modifications de sécurité importantes. C'est pourquoi il existe des restrictions concernant le moment où vous pouvez activer/désactiver les modifications.

Activer/Désactiver les modifications à l'aide des options pour les développeurs

Activez ou désactivez les modifications à l'aide des options pour les développeurs. Pour trouver les options pour les développeurs, procédez comme suit :

  1. Si les options pour les développeurs ne sont pas déjà activées, activez-les.
  2. Sur votre appareil, ouvrez l'application Paramètres et accédez à Système > Paramètres avancés > Options pour les développeurs > Modifications de compatibilité des applications.
  3. Sélectionnez votre application dans la liste.

  4. Dans la liste des modifications, recherchez celle que vous souhaitez activer ou désactiver, puis appuyez sur le bouton.

    Liste des modifications que vous pouvez activer ou désactiver

Activer/Désactiver les modifications à l'aide d'ADB

Pour activer ou désactiver une modification à l'aide d'ADB, exécutez l'une des commandes suivantes :

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Transmettez CHANGE_ID (par exemple, 194833441) ou CHANGE_NAME (par exemple, NOTIFICATION_PERM_CHANGE_ID) ainsi que le PACKAGE_NAME de votre application.

Vous pouvez également utiliser la commande suivante pour réinitialiser l'état par défaut d'une modification, en supprimant tout remplacement que vous avez défini à l'aide d'ADB ou des options pour les développeurs :

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Restrictions concernant l'activation ou la désactivation des modifications

Par défaut, chaque changement de comportement est activé ou désactivé. Les modifications qui concernent toutes les applications sont activées par défaut. Les autres modifications sont contrôlées par une targetSdkVersion. Ces modifications sont activées par défaut lorsqu'une application cible la version du SDK correspondante ou supérieure, et désactivées par défaut lorsqu'une application cible une version du SDK antérieure à la version contrôlée. Lorsque vous activez ou désactivez une modification, vous remplacez son état par défaut.

Pour éviter que le framework de compatibilité soit utilisé de manière malveillante, il existe des restrictions concernant le moment où vous pouvez activer/désactiver les modifications. L'activation ou la désactivation d'une modification dépend du type de modification, de si votre application est débogable ou non, et du type de compilation exécuté sur votre appareil. Le tableau suivant indique dans quels cas vous pouvez activer ou désactiver différents types de modifications :

Type de compilation Application non débogable Application débogable
Toutes les modifications Modifications contrôlées par la targetSDKVersion Toutes les autres modifications
Preview développeur ou version bêta Activation/Désactivation impossible Activation/Désactivation possible Activation/Désactivation possible
Build d'utilisateur public Activation/Désactivation impossible Activation/Désactivation possible Activation/Désactivation impossible