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. Profitez de cette flexibilité pour cibler les derniers version stable de l'API et lorsque vous testez votre application avec la version preview de la la prochaine version d'Android.

Lorsque vous utilisez les outils du framework de compatibilité, la plate-forme Android adapte automatiquement sa logique interne. targetSDKVersion ou recompilez votre application pour effectuer des tests de base. En effet, peuvent être activées individuellement, vous pouvez isoler, tester et déboguer une modification. changement de comportement à la fois ou désactiver un seul changement à l'origine des problèmes 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 quel comportement les modifications sont activées à l'aide des options pour 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.

   Remarque :Vous devez utiliser une variante de compilation débogable de votre application pour activer les modifications.

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 répertorié dans l'UI dans une section intitulée Activé pour targetSdkVersion 33 ou supérieur. Sur certaines versions antérieures d’Android, cette section est intitulée "Activé après le SDK API_LEVEL" à la place.

  Remarque :Pendant la preview d'Android 15 jusqu'à ce que le niveau d'API soit finalisé, certains les modifications qui ne sont activées que lors du ciblage d'Android 15 utilisent la valeur 10000 pour le niveau d'API au lieu du niveau d'API potentiel supposé 35.

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 Pour activer ces modifications, consultez leur description dans la section Compatibilité liste des frameworks associés à 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

Remarque : Chaque modification n'est consignée qu'une seule fois par processus. Forcez l'arrêt de votre application et redémarrez-la pour vous assurer que tous les messages Logcat pertinents s'affichent.

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 affecte le comportement de l'application si l'application utilise les API qui ont été modifiées.
DISABLED	La modification est désactivée et n'affectera pas 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 du SDK 33 ou version ultérieure, enableAfterTargetSdk=32 est la sortie. Si la modification n'est pas contrôlée par targetSDKVersion, enableAfterTargetSdk=0 est en sortie.

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é par défaut, la liste des packages peut donc inclure des instances des true ou false, en fonction du targetSDKVersion de chacune de ces applications. 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. Consultez les liens suivants pour plus d'informations, selon la version d'Android sur laquelle vous testez votre application pour:

• Android 15 (niveau d'API 35)
• Android 14 (niveau d'API 34)
• Android 13 (niveau d'API 33)
• Android 12 (niveaux d'API 31 et 32)
• Android 11 (niveau d'API 30)

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 par défaut pour une version de plate-forme spécifique, quelle que soit targetSDKVersion, afin que vous puissiez voir si votre appli est affectée par l'exécution de votre l'application sur cette version de la plate-forme.

Par exemple, si vous vous préparez à cibler Android 15 (niveau d'API 35), vous pouvez commencer par installer votre application sur un appareil exécutant Android 15 et testez votre application sur la base de vos tests habituels de flux de travail. Si votre application rencontre des problèmes, vous pouvez désactiver la modification à l'origine du problème. Vous pouvez donc 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. Ainsi, vos utilisateurs n'ont pas une expérience d'application dégradée s'ils mettent à jour leur appareil 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 un type targetSDKVersion, toutes les modifications contrôlées par cette version sont activées. par défaut. Ainsi, lorsque vous remplacez le targetSDKVersion de votre application par un nouveau votre application sera affectée par de nombreuses nouvelles modifications à la fois.

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 n'êtes pas certain que la cause du problème de la plate-forme activée, essayez de la désactiver, puis testez à nouveau 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.

Remarque : Chaque fois que vous modifiez une application à l'aide des options pour les développeurs ou des commandes ADB, l'application est supprimée afin que votre remplacement prenne effet immédiatement.

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.

   

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. Indique si vous pouvez activer/désactiver une modification dépend de son type, que votre application soit débogable ou non ; et le 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