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 mientras te preparas para orientar tu contenido a la versión estable más reciente de la API y mientras pruebas tu app con la versión preliminar de la próxima versión de Android.
Cuando usas las herramientas del marco 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 tu app para realizar pruebas básicas. Dado 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 cause problemas si primero necesitas 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
![](https://developer.android.com/static/images/guide/app-compatibility/appcompat-dev-options.png?authuser=8&hl=es)
Figura 1: Pantalla Cambios en la compatibilidad de la app (App Compatibility Changes) en las opciones para desarrolladores
Puedes ver qué cambios están habilitados y activarlos o desactivarlos en las opciones para desarrolladores del dispositivo. Para acceder a estas opciones, sigue estos pasos:
- Si no están habilitadas las opciones para desarrolladores, habilítalas.
- Abre la app de Configuración de tu dispositivo y navega hasta Sistema > Avanzado > Opciones para desarrolladores > Cambios en la compatibilidad de la app.
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 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, una sección titulada Enabled for targetSdkVersion >=33. En algunas versiones anteriores de Android, esta sección se titula "Habilitada después del SDK API_LEVEL".
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 habilitarlos, lee la descripción del cambio 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
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 aNOTIFICATION_PERM_CHANGE_ID
. - UID
- Indica qué app se ve afectada por el cambio.
- Estado
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
Se inhabilitó el cambio 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 sutargetSDKVersion
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 se orientan a SDK versión 33 o posterior, se muestra
enableAfterTargetSdk=32
. Si el cambio no está restringido portargetSDKVersion
, se muestraenableAfterTargetSdk=0
.- Anulaciones de paquetes
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 detrue
ofalse
, según latargetSDKVersion
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 cambios de comportamiento en el marco de compatibilidad se incluye como parte de la documentación de cada versión de Android. Consulta los siguientes vínculos para obtener más información, según la versión de Android en la que pruebes 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 ver 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 14 (nivel de API 34), 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, puedes inhabilitar el cambio que causa el problema para continuar probando otros errores.
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 quetargetSDKVersion
los restrinja. Esto ayuda a garantizar que tus usuarios no tengan una experiencia degradada en la app 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 se orienta a una
targetSDKVersion
específica, cualquier cambio que esté restringido por esa versión estará habilitado de forma predeterminada. Por lo tanto, cuando cambies latargetSDKVersion
de tu app a una versión nueva, esta 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 inhabilitar ese cambio y, luego, vuelve a 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.
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:
- Si no están habilitadas las opciones para desarrolladores, habilítalas.
- Abre la app de Configuración de tu dispositivo y navega hasta Sistema > Avanzado > Opciones para desarrolladores > Cambios en la compatibilidad de la app.
- Selecciona tu app de la lista.
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 tu app es depurable y del tipo de compilación que se ejecuta en tu 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 |