Herramientas de marco de compatibilidad

Android 11 introdujo nuevas herramientas para desarrolladores que permiten probar y depurar una app en función de cambios de comportamiento en las versiones más recientes de la plataforma de Android. Estas herramientas forman parte de un marco de compatibilidad que permite a los desarrolladores de apps activar y desactivar cambios de manera individual mediante opciones para desarrolladores o ADB. Usa esta flexibilidad durante la etapa de preparación para orientar tu contenido a la última versión estable de la API y probar la app con la versión preliminar del próximo lanzamiento de Android.

La plataforma de Android adapta automáticamente su lógica interna, por lo que no necesitas cambiar tu targetSDKVersion ni volver a compilar tu app para realizar pruebas básicas. Debido a que los cambios se pueden activar o desactivar de forma individual, puedes aislar, probar y depurar un cambio de comportamiento a la vez, o bien inhabilitar un solo cambio que genere problemas, en caso de que primero necesites probar otro.

Cómo identificar los cambios habilitados

Puedes comprobar qué cambios de comportamiento están habilitados usando las opciones para desarrolladores, logcat o comandos de ADB.

Cómo identificar los cambios habilitados mediante las opciones para desarrolladores

Figura 1: Pantalla Cambios de compatibilidad (App Compatibility Changes) con apps en las opciones para desarrolladores

Puedes ver los cambios que están habilitados y activarlos o desactivarlos en las opciones para desarrolladores de un dispositivo. Para acceder a esas opciones, sigue estos pasos:

  1. Si no están habilitadas las opciones para desarrolladores, habilítalas.
  2. Abre la app de Configuración de tu dispositivo y navega hasta Sistema > Avanzado > Opciones para desarrolladores > Cambios de compatibilidad con apps.
  3. Selecciona tu app de la lista.

Por lo general, cada cambio de comportamiento pertenece a una de las siguientes dos categorías:

  • Cambios que afectan a todas las apps que se ejecutan en esa versión de Android, sin importar la targetSdkVersion de la app.

    Estos cambios están habilitados de forma predeterminada en el marco de compatibilidad y aparecen en la IU, en la sección Cambios habilitados de manera predeterminada.

  • Cambios que solo afectan a las apps orientadas a ciertas versiones de Android. Debido a que estos cambios solo afectan a las apps que se orientan a una versión específica de Android, también se conocen como cambios vinculados por targetSDKVersion.

    Estos cambios están habilitados de forma predeterminada en el marco de compatibilidad si tu app está orientada a una versión posterior a la versión de API mencionada. Por ejemplo, un cambio de comportamiento restringido por targetSDKVersion en Android 11 (nivel de API 30) se mostrará en la IU, en la opción Habilitados después del SDK 29.

También verás una sección en la figura 1, llamada Cambios inhabilitados de manera predeterminada. Los cambios que se incluyen en esta sección pueden servir para diversos propósitos. Antes de habilitar esos cambios, lee la descripción correspondiente en la lista de marcos de compatibilidad de esa versión de Android.

Cómo identificar los cambios habilitados mediante logcat

Para cada cambio de comportamiento, la primera vez durante el proceso de la app cuando llama a la API afectada, el sistema genera un mensaje de logcat como este:

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

Cada mensaje de logcat incluye la siguiente información:

ID del cambio
Indica qué cambio afecta a la app. Este valor se mapea a uno de los cambios de comportamiento que aparecen en la pantalla Cambios de compatibilidad con apps (App Compatibility Changes) (consulta la figura 1). En este ejemplo, 119147584 se mapea a CALLBACK_ON_CLEAR_CHANGE.
UID
Indica qué app se ve afectada por el cambio.
Estado

Indica si el cambio está afectando a la app en este momento.

El estado puede ser uno de los siguientes valores:

Estado Significado
ENABLED El cambio está habilitado actualmente y afectará el comportamiento de la app si esta usa las API que se modificaron.
DISABLED

Por el momento, el cambio está inhabilitado y no afectará a la app.

Nota: Si se inhabilita este cambio porque la targetSDKVersion de la app está por debajo del umbral requerido, se habilitará el cambio de forma predeterminada cuando la app aumente sus targetSDKVersion para orientarse a una versión superior.

LOGGED El cambio se registra mediante el marco de compatibilidad, pero no se puede activar ni desactivar. Aun así, es posible que siga afectando el comportamiento de la app. Consulta la descripción del cambio en la lista de marcos de compatibilidad de esa versión de Android para obtener más información. En muchos casos, estos tipos de cambios son experimentales y se pueden ignorar.

Cómo identificar los cambios habilitados mediante ADB

Ejecuta el siguiente comando de ADB para ver el conjunto completo de cambios (habilitados o inhabilitados) en todo el dispositivo:

adb shell dumpsys platform_compat

El resultado muestra la siguiente información para cada cambio:

ID del cambio
Un identificador único para este cambio de comportamiento. Por ejemplo, 119147584.
Nombre
Es el nombre de este cambio de comportamiento. Por ejemplo, CALLBACK_ON_CLEAR_CHANGE.
Criterios de targetSDKVersion

¿Con qué targetSDKVersion se restringe el cambio (si corresponde)?

Por ejemplo, si este cambio solo está habilitado para apps orientadas al SDK versión 30 o superior, se muestra enableAfterTargetSdk=29. Si el cambio no está restringido por targetSDKVersion, se muestra enableAfterTargetSdk=0.

Anulaciones de paquetes

Es el nombre de cada paquete en el que se anuló el estado predeterminado del cambio (habilitado o inhabilitado).

Por ejemplo, si este es un cambio que está habilitado de forma predeterminada, se mostrará el nombre del paquete de la app si desactivaste el cambio mediante las opciones para desarrolladores o ADB. En este caso, el resultado sería el siguiente:

packageOverrides={com.my.package=false}

Los cambios restringidos por targetSDKVersion se pueden habilitar o inhabilitar de forma predeterminada, por lo que la lista de paquetes puede incluir instancias de true o false, según la targetSDKVersion de cada app. Por ejemplo:

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

Obtén más información sobre cambios específicos

La lista completa de los cambios de comportamiento en el marco de compatibilidad se incluye como parte de la documentación para cada versión de Android. Consulta los siguientes vínculos para obtener más información, según la versión de Android con la que quieras probar tu app:

Cuándo activar o desactivar los cambios

El propósito principal del marco de compatibilidad es brindarte control y flexibilidad cuando pruebas la app con nuevas versiones de Android. En esta sección, se describen algunas estrategias que puedes usar para determinar cuándo activar o desactivar los cambios mientras pruebas y depuras tu app.

Cuándo desactivar los cambios

Decidir cuándo desactivar los cambios suele depender de si el cambio está restringido por targetSDKVersion o no.

Se habilitaron los cambios para todas las apps

Los cambios que afectan a todas las apps están habilitados de forma predeterminada para una versión de plataforma específica, independientemente de la targetSDKVersion de tu app, de modo que puedas determinar si se ve afectada cuando la ejecutas en esa versión de la plataforma.

Por ejemplo, si estás preparando tu contenido para orientarlo a Android 11 (nivel de API 30), puedes comenzar instalando tu app en un dispositivo que ejecute esa versión de Android y realizando los flujos de trabajo de prueba típicos. Si tu app tiene problemas, inhabilita el cambio que genere el error para poder seguir buscando otras fallas.

Debido a que estos cambios pueden afectar a todas las apps independientemente de su targetSDKVersion, deberías probar y actualizar tu app para estos cambios antes de que targetSDKVersion los restrinja. Eso ayuda a garantizar que los usuarios no tengan una experiencia negativa cuando actualicen su dispositivo a una nueva versión de la plataforma.

También debes priorizar la prueba de estos cambios porque no puedes desactivarlos si usas una compilación de lanzamiento pública de Android. Lo ideal es que realices pruebas con estos cambios para cada versión de Android mientras esa versión esté en vista previa.

Cambios restringidos por targetSDKVersion

Si tu app está orientada a una targetSDKVersion específica, cualquier cambio que esté restringido por esa versión se habilitará de forma predeterminada. Por lo tanto, cuando cambies la targetSDKVersion de tu app a una versión nueva, tu app comenzará a verse afectada por muchos cambios nuevos a la vez.

Como la app podría verse afectada por más de uno de estos cambios, es posible que debas desactivar algunos de ellos de forma individual a medida que pruebas y depuras tu app.

Cuándo activar los cambios

Los cambios restringidos por una targetSDKVersion específica están inhabilitados de forma predeterminada cada vez que se orienta una app a una versión del SDK anterior a la versión restringida. Por lo general, cuando te prepares para orientar tu contenido a una targetSdkVersion nueva, tendrás una lista de cambios de comportamiento que deberás usar para probar y depurar tu app.

Por ejemplo, supongamos que pruebas tu app con una serie de cambios de plataforma en la próxima targetSdkVersion. Mediante opciones para desarrolladores o comandos de ADB, puedes habilitar y probar cada uno de los cambios restringidos, en lugar de modificar el manifiesto de tu app y aceptar todos los cambios a la vez. Este control adicional te ayuda a probar los cambios de forma aislada, para evitar depurar y actualizar varias partes de tu app al mismo tiempo.

Después de habilitar un cambio, puedes probar y depurar tu app con los flujos de trabajo de prueba típicos. Si tienes problemas, verifica tus registros para determinar la causa del error. En caso de que no esté claro si el problema se debe a un cambio de plataforma habilitado, intenta inhabilitarlo y, luego, probar esa área de la app.

Cómo activar o desactivar los cambios

El marco de compatibilidad te permite activar o desactivar cada cambio mediante las opciones para desarrolladores o los comandos de ADB. Debido a que activar o desactivar los cambios puede hacer que falle la app o que se inhabiliten importantes cambios de seguridad, existen algunas restricciones para activar o desactivar los cambios.

Cómo activar o desactivar los cambios mediante las opciones para desarrolladores

Usa las opciones para desarrolladores si deseas activar o desactivar los cambios. Sigue estos pasos a fin de encontrar esas opciones:

  1. Si no están habilitadas las opciones para desarrolladores, habilítalas.
  2. Abre la app de Configuración de tu dispositivo y navega hasta Sistema > Avanzado > Opciones para desarrolladores > Cambios de compatibilidad con apps.
  3. Selecciona tu app de la lista.
  4. En la lista de cambios, busca el cambio que desees activar o desactivar, y presiona el interruptor.

    Lista de cambios que pueden activarse o desactivarse

Cómo activar o desactivar cambios mediante ADB

Para activar o desactivar un cambio mediante ADB, ejecuta uno de los siguientes comandos:

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

Pasa el CHANGE_ID (por ejemplo, 119147584) o el CHANGE_NAME (por ejemplo, CALLBACK_ON_CLEAR_CHANGE) y el PACKAGE_NAME de la app.

También puedes usar el siguiente comando para restablecer el estado predeterminado de un cambio y quitar cualquier anulación que hayas establecido mediante ADB o las opciones para desarrolladores:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Restricciones para activar o desactivar los cambios

De forma predeterminada, cada cambio de comportamiento está habilitado o inhabilitado. Los cambios que afectan a todas las apps están habilitados de forma predeterminada. Otros cambios están restringidos por una targetSdkVersion. Estos cambios están habilitados de forma predeterminada cuando una app se orienta a la versión del SDK correspondiente o una superior, y están inhabilitados de forma predeterminada cuando una app se orienta a una versión del SDK inferior a la versión restringida. Cuando activas o desactivas un cambio, anulas su estado predeterminado.

Para evitar que se use el marco de compatibilidad con intenciones maliciosas, hay algunas restricciones que limitan cuándo puedes activar o desactivar los cambios. La posibilidad de activar o desactivar un cambio depende del tipo de cambio, de si la app es depurable y del tipo de compilación que se ejecuta en el dispositivo. En la siguiente tabla, se indica cuándo puedes activar o desactivar diferentes tipos de cambios:

Tipo de compilación App no depurable App depurable
Todos los cambios Cambios restringidos por targetSDKVersion Todos los demás cambios
Vista previa para desarrolladores o compilación Beta No se puede activar o desactivar Se puede activar o desactivar Se puede activar o desactivar
Compilación de usuario público No se puede activar o desactivar Se puede activar o desactivar No se puede activar o desactivar