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 rotundos de manera individual desde las opciones para desarrolladores o ADB. Usa esta flexibilidad durante la etapa de preparación para seleccionar la última versión estable de la API como el objetivo de tu contenido y probar la app con la versión preliminar del próximo lanzamiento de Android.

Cuando usas las herramientas del framework de compatibilidad, la plataforma de Android adapta automáticamente su lógica interna, por lo que no necesitas cambiar tu targetSDKVersion ni volver a compilar la 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

Cuando un cambio de comportamiento está habilitado, puede afectar la manera en que tu app accede a las APIs de la plataforma que se ven afectadas por ese cambio. 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 en la compatibilidad de la app (App Compatibility Changes) 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 estas 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 en la compatibilidad de la app.

3. Selecciona tu app de la lista.

   Nota: Debes usar una variante de compilación depurable de tu app para activar y desactivar los cambios.

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 que tienen como objetivo ciertas versiones de Android. Debido a que estos cambios solo afectan a las apps que tienen como objetivo una versión específica de Android, también se conocen como cambios restringidos 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 13 (nivel de API 33) se mostrará en la IU, en una sección titulada Enabled for targetSdkVersion >=33. En algunas versiones anteriores de Android, esta sección se titula "Habilitado después del SDK API_LEVEL".

  Nota: Durante la versión preliminar de Android 15, hasta que se finalice el nivel de API, algunos cambios que solo se habilitan cuando se segmenta para Android 15 usan un valor de 10000 para el nivel de API en lugar del nivel de API final y presunto de 35.

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 con 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: 194833441; UID 10265; state: ENABLED

Nota: Cada cambio solo se registra, como máximo, una vez por proceso. Fuerza la detención y reinicia el proceso de la app para asegurarte de ver todos los mensajes relevantes de logcat.

Cada mensaje de logcat incluye la siguiente información:

ID del cambio

Indica qué cambio afecta a la app. Este valor se asigna a uno de los cambios de comportamiento que aparecen en la pantalla Cambios en la compatibilidad de la app (App Compatibility Changes) (consulta la figura 1). En este ejemplo, 194833441 se asigna a NOTIFICATION_PERM_CHANGE_ID.

UID

Indica qué app se ve afectada por el cambio.

State

Indica si el cambio afecta a la app.

El estado puede ser uno de los siguientes valores:

Estado	Significado
ENABLED	El cambio está habilitado y afectará el comportamiento de la app si esta usa las APIs que se modificaron.
DISABLED	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 su targetSDKVersion para seleccionar como objetivo una versión superior.
LOGGED	El cambio se registra en 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 con 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, 194833441.

Nombre

Es el nombre de este cambio de comportamiento. Por ejemplo, NOTIFICATION_PERM_CHANGE_ID.

Criterios de targetSDKVersion

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

Por ejemplo, si este cambio solo está habilitado para apps que seleccionan como objetivo el SDK versión 33 o superior, se muestra enableAfterTargetSdk=32. 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 desde 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:

• Android 15 (nivel de API 35)
• Android 14 (nivel de API 34)
• Android 13 (nivel de API 33)
• Android 12 (niveles de API 31 y 32)
• Android 11 (nivel de API 30)

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 versiones más recientes 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 15 (nivel de API 35), 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 frecuentemente 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 una app tiene como objetivo una versión del SDK anterior a la versión restringida. Por lo general, cuando te prepares para seleccionar como objetivo 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. Si usas 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. Si 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 si usas 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.

Nota: Cada vez que actives o desactives un cambio para una app con las opciones para desarrolladores o los comandos de ADB, se cerrará la app a fin de garantizar que la anulación se aplique de inmediato.

Cómo activar o desactivar los cambios con 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 en la compatibilidad de la app.
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.

   

Cómo activar o desactivar cambios con ADB

Para activar o desactivar un cambio con 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, 194833441) o el CHANGE_NAME (por ejemplo, NOTIFICATION_PERM_CHANGE_ID) 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 con 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 tiene como objetivo la versión del SDK correspondiente o una superior, y están inhabilitados de forma predeterminada cuando una app tiene como objetivo 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