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. Utilice esta flexibilidad mientras se prepara para orientar sus anuncios a la estable y mientras pruebas tu app con la versión preliminar de la con 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 o vuelve a compilar tu app para realizar pruebas básicas. Porque Los cambios se pueden activar o desactivar de forma individual. Puedes aislar, probar y depurar uno. cambio de comportamiento a la vez o inhabilitar un solo cambio que causa problemas si primero debes probar algo más.

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é comportamiento los cambios se habilitan mediante las opciones para desarrolladores, logcat o comandos de ADB.

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

Puedes ver qué cambios 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.

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) aparecerá en la IU, en una sección titulada Habilitado para targetSdkVersion >=33. En algunas versiones anteriores de Android, el título de esta sección es "Habilitada después del SDK API_LEVEL" en su lugar.

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 para habilitar estos cambios, lee la descripción del cambio en la página de del marco de trabajo 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 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 aplicación si la app 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 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 se habilita para apps orientadas a la versión del SDK 33 o una versión posterior, se muestra enableAfterTargetSdk=32. Si el cambio no es restringido por targetSDKVersion, se muestra enableAfterTargetSdk=0.

Anulaciones de paquetes

El nombre de cada paquete en el que se encuentra el estado predeterminado del cambio (habilitada o inhabilitada).

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 inhabilitado de forma predeterminada, por lo que la lista de paquetes puede incluir instancias de ambos true o false, según cada una de las targetSDKVersion de esas apps 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 de la siguiente manera: de la documentación para cada versión de Android. Consulta los siguientes vínculos para más información, según la versión de Android con la que pruebes tu app para:

• 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 son habilitados por predeterminadas para una versión específica de la plataforma, independientemente de la configuración targetSDKVersion, de modo que puedas ver si tu app se ve afectada cuando ejecutes tu en esa versión de la plataforma.

Por ejemplo, si te preparas para orientar la app a Android 15 (nivel de API 35), puedes comenzar instalando tu app en un dispositivo que se ejecute Android 15 y prueba tu app con tus pruebas habituales en los flujos de trabajo. Si tu app tiene problemas, puedes inhabilitar el cambio que es la causa del problema, para que puedas seguir 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 que targetSDKVersion los restrinja. Esto ayuda a garantizar que los usuarios no tendrá una experiencia degradada en la app cuando actualice su dispositivo a un nuevo 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 un targetSDKVersion, todos los cambios restringidos por esa versión estarán habilitados de forma predeterminada. Por lo tanto, cuando cambies la targetSDKVersion de tu app a una 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 una cambio de plataforma que esté habilitado, intenta inhabilitarlo y, luego, en el área de la aplicación.

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:

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. Si puedes activar o desactivar un cambio depende del tipo de cambio, si tu app es depurable y el 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