Cómo cambiar el valor de los recursos de una app durante el tiempo de ejecución

Una superposición de recursos del entorno de ejecución (RRO) es un paquete que cambia los valores de los recursos de un paquete de destino durante el tiempo de ejecución. Por ejemplo, una app instalada en la imagen del sistema podría cambiar su comportamiento según el valor de un recurso. En lugar de codificar el valor del recurso en el tiempo de compilación, un RRO instalado en una partición diferente puede cambiar los valores de los recursos de la app en el tiempo de ejecución.

Los RRO se pueden habilitar o inhabilitar. Puedes configurar de manera programática el estado de habilitado o inhabilitado para activar o desactivar la capacidad de un RRO de cambiar los valores de los recursos. Los RRO están inhabilitados de forma predeterminada (sin embargo, los RRO estáticos están habilitados de forma predeterminada).

Nota: Un RRO solo se puede usar para cambiar los valores de un recurso existente.

Recursos superpuestos

Las superposiciones funcionan asignando los recursos definidos en el paquete de superposición a los recursos definidos en el paquete de destino. Cuando una app intenta resolver el valor de un recurso en el paquete de destino, se muestra el valor del recurso de superposición al que se asigna el recurso de destino.

Cómo configurar el manifiesto

Un paquete se considera un paquete de RRO si contiene una etiqueta <overlay> como elemento secundario de la etiqueta <manifest>.

• El valor del atributo android:targetPackage obligatorio especifica el nombre del paquete que la RRO pretende superponer.

• El valor del atributo opcional android:targetName especifica el nombre del subconjunto de recursos superpuestos del paquete de destino que la RRO pretende superponer. Si el destino no define un conjunto de recursos superpuestos, este atributo no debe estar presente.

En el siguiente código, se muestra un ejemplo de AndroidManifest.xml superpuesta.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:targetName="OverlayableResources"/>
</manifest>

Las superposiciones no pueden superponerse con el código, por lo que no pueden tener archivos DEX. Además, el atributo android:hasCode de la etiqueta <application> en el manifiesto debe establecerse como false.

Define el mapa de recursos

En Android 11 o versiones posteriores, el mecanismo recomendado para definir el mapa de recursos superpuestos es crear un archivo en el directorio res/xml del paquete de superposición, enumerar los recursos de destino que se deben superponer y sus valores de reemplazo, y, luego, establecer el valor del atributo android:resourcesMap de la etiqueta de manifiesto <overlay> en una referencia al archivo de asignación de recursos.

En el siguiente código, se muestra un ejemplo de archivo res/xml/overlays.xml.

<?xml version="1.0" encoding="utf-8"?>
<overlay xmlns:android="http://schemas.android.com/apk/res/android" >
    <!-- Overlays string/config1 and string/config2 with the same resource. -->
    <item target="string/config1" value="@string/overlay1" />
    <item target="string/config2" value="@string/overlay1" />

    <!-- Overlays string/config3 with the string "yes". -->
    <item target="string/config3" value="@android:string/yes" />

    <!-- Overlays string/config4 with the string "Hardcoded string". -->
    <item target="string/config4" value="Hardcoded string" />

    <!-- Overlays integer/config5 with the integer "42". -->
    <item target="integer/config5" value="42" />
</overlay>

En el siguiente código, se muestra un ejemplo de manifiesto de superposición.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:targetName="OverlayableResources"
                   android:resourcesMap="@xml/overlays"/>
</manifest>

Nota: En Android 10 o versiones anteriores, los recursos se superponen según su nombre. Para superponer el recurso string/foo en el paquete de destino, la superposición también debe definir el recurso string/foo.

Compila el paquete

Android 11 o versiones posteriores admiten una regla de compilación de Soong para superposiciones que evita que Android Asset Packaging Tool 2 (AAPT2) intente anular las configuraciones de recursos con el mismo valor (--no-resource-deduping) y quitar recursos sin configuraciones predeterminadas (--no-resource-removal). El siguiente código muestra un ejemplo de archivo Android.bp.

runtime_resource_overlay {
    name: "ExampleOverlay",
    sdk_version: "current",
}

Cómo resolver recursos

Si un recurso de destino o de superposición tiene varias configuraciones definidas para el recurso que se consulta, el entorno de ejecución de recursos muestra el valor de la configuración que mejor coincide con la configuración del dispositivo. Para determinar qué configuración es la que mejor coincide, combina el conjunto de configuraciones de recursos superpuestos en el conjunto de configuraciones de recursos de destino y, luego, sigue el flujo de resolución de recursos normal (para obtener más detalles, consulta Cómo encuentra Android el recurso de coincidencia óptima).

Por ejemplo, si una superposición define un valor para la configuración de drawable-en y el destino define un valor para drawable-en-port, drawable-en-port tiene una mejor coincidencia, por lo que se elige el valor de la configuración de destino drawable-en-port en el tiempo de ejecución. Para superponer todas las configuraciones de drawable-en, la superposición debe definir un valor para cada configuración de drawable-en que define el objetivo.

Las superposiciones pueden hacer referencia a sus propios recursos, con comportamientos diferentes entre las versiones de Android.

• En Android 11 o versiones posteriores, cada superposición tiene su propio espacio de ID de recurso reservado que no se superpone con el espacio de ID de recurso de destino ni con otros espacios de ID de recurso de superposición, por lo que las superposiciones que hacen referencia a sus propios recursos funcionan como se espera.

• En Android 10 o versiones anteriores, las superposiciones y los paquetes de destino comparten el mismo espacio de ID de recurso, lo que puede causar colisiones y un comportamiento inesperado cuando intentan hacer referencia a sus propios recursos con la sintaxis @type/name.

Habilita o inhabilita las superposiciones

Las superposiciones se pueden habilitar o inhabilitar de forma manual y programática.

Cómo inhabilitar o habilitar manualmente las superposiciones

Para habilitar y verificar manualmente un RRO, ejecuta el siguiente comando:

adb shell cmd overlay enable --user current com.example.carrro
adb shell cmd overlay list --user current | grep -i com.example com.example.carrro

Esto habilita la RRO para el usuario del sistema (userId = 0) que es propietario de SystemUI. Esta instrucción no afecta a las apps que inicia el usuario en primer plano (userId = 10). Para habilitar el RRO para el usuario en primer plano, usa el parámetro -–user 10:

adb shell cmd overlay enable --user 10 com.example.carrro

Habilita o inhabilita las superposiciones de forma programática

Usa la API de OverlayManager para habilitar y deshabilitar superposiciones mutables (recupera la interfaz de la API con Context#getSystemService(Context.OVERLAY_SERVICE)). Solo el paquete al que se orienta o un paquete con el permiso android.permission.CHANGE_OVERLAY_PACKAGES puede habilitar una superposición. Cuando se habilita o inhabilita una superposición, los eventos de cambio de configuración se propagan al paquete de destino y se reinician las actividades de destino.

Restringe los recursos superpuestos

En Android 10 y versiones posteriores, la etiqueta XML <overlayable> expone un conjunto de recursos que los RRO pueden superponer. En el siguiente ejemplo de archivo res/values/overlayable.xml, string/foo y integer/bar son recursos que se usan para aplicar temas a la apariencia del dispositivo. Para superponer estos recursos, una superposición debe orientarse de forma explícita a la colección de recursos superponibles por nombre.

<!-- The collection of resources for theming the appearance of the device -->
<overlayable name="ThemeResources">
       <policy type="public">
               <item type="string" name="foo/" />
               <item type="integer" name="bar/" />
       </policy>
       ...
</overlayable>

Un APK puede definir varias etiquetas <overlayable>, pero cada una debe tener un nombre único dentro del paquete. Por ejemplo:

• Está bien que dos paquetes diferentes definan <overlayable name="foo">.

• No es correcto que un solo APK tenga dos bloques <overlayable name="foo">.

En el siguiente código, se muestra un ejemplo de una superposición en el archivo AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.my.theme.overlay">
       <application android:hasCode="false" />
       <!-- This overlay will override the ThemeResources resources -->
       <overlay android:targetPackage="android" android:targetName="ThemeResources">
</manifest>

Cuando una app define una etiqueta <overlayable>, las superposiciones orientadas a esa app hacen lo siguiente:

• Debes especificar targetName.

• Solo puede superponer los recursos que se enumeran en la etiqueta <overlayable>.

• Solo puede segmentarse para un nombre <overlayable>.

No puedes habilitar una superposición segmentada para un paquete que exponga recursos superponibles, pero que no use android:targetName para segmentar una etiqueta <overlayable> específica.

Nota: Si el paquete de destino no tiene una superposición definida, esta debe estar preinstalada en la imagen del sistema o firmada con la misma firma que el destino para superponer los recursos del paquete de destino.

Políticas de restricción

Usa la etiqueta <policy> para aplicar restricciones en los recursos superpuestos. El atributo type especifica qué políticas debe cumplir una superposición para anular los recursos incluidos. Entre los tipos admitidos, se incluyen los siguientes.

• public. Cualquier superposición puede anular el recurso.
• system. Cualquier superposición en la partición del sistema puede anular los recursos.
• vendor. Cualquier superposición en la partición del proveedor puede anular los recursos.
• product. Cualquier superposición en la partición del producto puede anular los recursos.
• oem. Cualquier superposición en la partición del OEM puede anular los recursos.
• odm. Cualquier superposición en la partición de odm puede anular los recursos.
• signature. Cualquier superposición firmada con la misma firma que el APK de destino puede reemplazar los recursos.
• actor. Cualquier superposición firmada con la misma firma que el APK del actor puede anular los recursos. El actor se declara en la etiqueta named-actor en la configuración del sistema.
• config_signature. Cualquier superposición firmada con la misma firma que el APK de overlay-config puede anular los recursos. La configuración de superposición se declara en la etiqueta overlay-config-signature en la configuración del sistema.

En el siguiente código, se muestra una etiqueta <policy> de ejemplo en el archivo res/values/overlayable.xml.

<overlayable name="ThemeResources">
   <policy type="vendor" >
       <item type="string" name="foo" />
   </policy>
   <policy type="product|signature"  >
       <item type="string" name="bar" />
       <item type="string" name="baz" />
   </policy>
</overlayable>

Para especificar varias políticas, usa barras verticales (|) como caracteres de separación. Cuando se especifican varias políticas, una superposición solo debe cumplir una política para anular los recursos que se enumeran en la etiqueta <policy>.

Configura superposiciones

Android admite diferentes mecanismos para configurar la mutabilidad, el estado predeterminado y la prioridad de las superposiciones según la versión de Android.

• Los dispositivos que ejecutan Android 11 o versiones posteriores pueden usar un archivo OverlayConfig (config.xml) en lugar de atributos de manifiesto. El uso de un archivo de superposición es el método recomendado para las superposiciones.

• Todos los dispositivos pueden usar atributos de manifiesto (android:isStatic y android:priority) para configurar RRO estáticos.

Nota: Solo las superposiciones inmutables orientadas al paquete android afectan los valores de los recursos recuperados a través de Resources.getSystem().

Usa OverlayConfig

En Android 11 y versiones posteriores, puedes usar OverlayConfig para configurar la mutabilidad, el estado predeterminado y la prioridad de las superposiciones. Para configurar una superposición, crea o modifica el archivo ubicado en partition/overlay/config/config.xml, donde partition es la partición de la superposición que se configurará. Para configurarse, una superposición debe residir en el directorio overlay/ de la partición en la que se configura. En el siguiente código, se muestra un ejemplo de product/overlay/config/config.xml.

<config>
    <merge path="OEM-common-rros-config.xml" />
    <overlay package="com.oem.overlay.device" mutable="false" enabled="true" />
    <overlay package="com.oem.green.theme" enabled="true" />
</config>"

La etiqueta <overlay> requiere un atributo package que indique qué paquete de superposición se está configurando. El atributo opcional enabled controla si la superposición está habilitada de forma predeterminada (el valor predeterminado es false). El atributo opcional mutable controla si la superposición es mutable y si se puede cambiar su estado habilitado de forma programática durante el tiempo de ejecución (el valor predeterminado es true). Las superposiciones que no se incluyen en un archivo de configuración son mutables y están inhabilitadas de forma predeterminada.

Prioridad de superposición

Cuando varias superposiciones anulan los mismos recursos, el orden de las superposiciones es importante. Una superposición tiene mayor prioridad que las superposiciones con configuraciones que la preceden. El orden de prioridad de las superposiciones en diferentes particiones (de la menor a la mayor prioridad) es el siguiente.

• system
• vendor
• odm
• oem
• product
• system_ext

Nota: Cuando OverlayManagerService habilita superposiciones no configuradas, el orden de las superposiciones no se define.

Cómo combinar archivos

El uso de etiquetas <merge> permite que se combinen otros archivos de configuración en la posición especificada en el archivo de configuración. El atributo path de la etiqueta representa la ruta de acceso del archivo que se combinará en relación con el directorio que contiene los archivos de configuración de superposición.

Usa atributos de manifiesto o RRO estáticos

En Android 10 o versiones anteriores, la inmutabilidad y la prioridad de la superposición se configuran con los siguientes atributos de manifiesto.

• android:isStatic. Cuando el valor de este atributo booleano se establece en true, la superposición se habilita de forma predeterminada y es inmutable, lo que evita que se inhabilite.

• android:priority: El valor de este atributo numérico (que solo afecta a las superposiciones estáticas) configura la prioridad de la superposición cuando varias superposiciones estáticas se orientan al mismo valor de recurso. Un número más alto indica una prioridad más alta.

En el siguiente código, se muestra un ejemplo de AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:isStatic="true"
                   android:priority="5"/>
</manifest>

Cambios en Android 11

En Android 11 o versiones posteriores, si un archivo de configuración se encuentra en partition/overlay/config/config.xml, las superposiciones se configuran con ese archivo, y android:isStatic y android:priority no tienen efecto en las superposiciones ubicadas en la partición. La definición de un archivo de configuración de superposición en cualquier partición aplica la precedencia de la partición de superposición.

Además, Android 11 o versiones posteriores quitan la capacidad de usar superposiciones estáticas para afectar los valores de los recursos que se leen durante la instalación del paquete. Para el caso de uso común de usar superposiciones estáticas para cambiar el valor de los valores booleanos que configuran el estado habilitado del componente, usa la etiqueta SystemConfig <component-override> (nueva en Android 11).

Superposiciones de depuración

Para habilitar, inhabilitar y volcar superposiciones de forma manual, usa el siguiente comando de shell del administrador de superposiciones.

adb shell cmd overlay

El uso de enable sin especificar un usuario afecta al usuario actual, es decir, al usuario del sistema (userId = 0), que es propietario de la IU del sistema. Esto no afecta al usuario en primer plano (userId = 10), que es propietario de las apps. Para habilitar el RRO para el usuario en primer plano, usa el parámetro –-user 10:

adb shell cmd overlay enable --user 10 com.example.carrro

OverlayManagerService usa idmap2 para asignar los IDs de recursos del paquete de destino a los IDs de recursos del paquete de superposición. Las asignaciones de ID generadas se almacenan en /data/resource-cache/. Si la superposición no funciona correctamente, busca el archivo idmap correspondiente en /data/resource-cache/ y, luego, ejecuta el siguiente comando.

adb shell idmap2 dump --idmap-path [file]

Este comando imprime la asignación de recursos como se muestra a continuación.

[target res id] - > [overlay res id] [resource name]
0x01040151 -> 0x01050001 string/config_dozeComponent
0x01040152 -> 0x01050002 string/config_dozeDoubleTapSensorType
0x01040153 -> 0x01050003 string/config_dozeLongPressSensorType