Sobreposições de recursos de tempo de execução (RROs)

Uma sobreposição de recursos de tempo de execução (RRO) é um pacote que altera os valores de recursos de um pacote de destino em tempo de execução. Por exemplo, um aplicativo instalado na imagem do sistema pode alterar seu comportamento com base no valor de um recurso. Em vez de codificar o valor do recurso em tempo de compilação, um RRO instalado em uma partição diferente pode alterar os valores dos recursos do aplicativo em tempo de execução.

RROs podem ser habilitados ou desabilitados. Você pode definir programaticamente o estado de habilitar/desabilitar para alternar a capacidade de um RRO de alterar os valores dos recursos. Os RROs são desabilitados por padrão (no entanto, os RROs estáticos são habilitados por padrão).

Sobreposição de recursos

As sobreposições funcionam mapeando recursos definidos no pacote de sobreposição para recursos definidos no pacote de destino. Quando um aplicativo tenta resolver o valor de um recurso no pacote de destino, o valor do recurso de sobreposição para o qual o recurso de destino está mapeado é retornado.

Configurando o manifesto

Um pacote é considerado um pacote RRO se contiver uma tag <overlay> como filha da tag <manifest> .

• O valor do atributo android:targetPackage necessário especifica o nome do pacote que o RRO pretende sobrepor.

• O valor do atributo opcional android:targetName especifica o nome do subconjunto de recursos sobrepostos do pacote de destino que o RRO pretende sobrepor. Se o destino não definir um conjunto de recursos sobrepostos, esse atributo não deverá estar presente.

O código a seguir mostra um exemplo de sobreposição 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:targetName="OverlayableResources"/>
</manifest>

As sobreposições não podem sobrepor código, portanto, não podem ter arquivos DEX. Além disso, o atributo android:hasCode da tag <application > no manifesto deve ser definido como false .

Definindo o mapa de recursos

No Android 11 ou superior, o mecanismo recomendado para definir o mapa de recursos de sobreposição é criar um arquivo no diretório res/xml do pacote de sobreposição, enumerar os recursos de destino que devem ser sobrepostos e seus valores de substituição e definir o valor do android:resourcesMap atributo da tag de manifesto <overlay> para uma referência ao arquivo de mapeamento de recursos.

O código a seguir mostra um exemplo de arquivo 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>

O código a seguir mostra um manifesto de sobreposição de exemplo.

<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>

Observação: no Android 10 ou inferior, os recursos são sobrepostos com base no nome. Para sobrepor a string/foo no pacote de destino, a sobreposição também deve definir a string/foo .

Construindo o pacote

O Android 11 ou superior é compatível com uma regra de compilação Soong para sobreposições que impede a Android Asset Packaging Tool 2 (AAPT2) de tentar desduplicar configurações de recursos com o mesmo valor ( --no-resource-deduping ) e de remover recursos sem configurações padrão ( --no-resource-removal ). O código a seguir mostra um arquivo Android.bp de exemplo.

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

Resolvendo recursos

Se um recurso de destino ou recurso de sobreposição tiver várias configurações definidas para o recurso que está sendo consultado, o tempo de execução dos recursos retornará o valor da configuração que melhor corresponde à configuração do dispositivo. Para determinar qual configuração é a configuração de melhor correspondência, mescle o conjunto de configurações de recursos de sobreposição no conjunto de configurações de recursos de destino e siga o fluxo regular de resolução de recursos (para obter detalhes, consulte Como o Android encontra o recurso de melhor correspondência ).

Por exemplo, se uma sobreposição define um valor para a configuração drawable-en e o destino define um valor para drawable-en-port , drawable-en-port tem uma correspondência melhor, de modo que o valor da configuração de destino drawable-en-port é escolhido em tempo de execução. Para sobrepor todas as configurações drawable-en , a sobreposição deve definir um valor para cada configuração drawable-en que o destino define.

As sobreposições podem fazer referência a seus próprios recursos, com comportamentos diferentes entre as versões do Android.

• No Android 11 ou superior, cada sobreposição tem seu próprio espaço de ID de recurso reservado que não se sobrepõe ao espaço de ID de recurso de destino ou a outros espaços de ID de recurso de sobreposição, portanto, as sobreposições que fazem referência a seus próprios recursos funcionam conforme o esperado.

• No Android 10 ou inferior, as sobreposições e os pacotes de destino compartilham o mesmo espaço de ID do recurso, o que pode causar colisões e comportamentos inesperados ao tentar fazer referência a seus próprios recursos usando a sintaxe @type/name .

Ativando/desativando sobreposições

Use a API OverlayManager para ativar e desativar sobreposições mutáveis ​​(recupere a interface da API usando Context#getSystemService(Context.OVERLAY_SERVICE) ). Uma sobreposição pode ser habilitada apenas pelo pacote a que se destina ou por um pacote com a permissão android.permission.CHANGE_OVERLAY_PACKAGES . Quando uma sobreposição é habilitada ou desabilitada, os eventos de alteração de configuração são propagados para o pacote de destino e as atividades de destino são reiniciadas.

Restringindo recursos sobrepostos

No Android 10 ou superior, a tag XML <overlayable> expõe um conjunto de recursos que os RROs podem sobrepor. No arquivo res/values/overlayable.xml de exemplo a seguir, string/foo e integer/bar são recursos usados ​​para criar temas para a aparência do dispositivo; para sobrepor esses recursos, uma sobreposição deve direcionar explicitamente a coleção de recursos sobrepostos por nome.

<!-- 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>

Um APK pode definir várias tags <overlayable> , mas cada tag deve ter um nome exclusivo no pacote. Por exemplo, é:

• OK para dois pacotes diferentes definirem <overlayable name="foo"> .

• Não é aceitável que um único APK tenha dois <overlayable name="foo"> .

O código a seguir mostra um exemplo de sobreposição no arquivo 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>

Quando um aplicativo define uma tag <overlayable> , as sobreposições segmentam esse aplicativo:

• Deve especificar targetName .

• Pode sobrepor apenas os recursos listados na tag <overlayable> .

• Pode segmentar apenas um nome <overlayable> .

Você não pode habilitar uma sobreposição visando um pacote que expõe recursos sobrepostos, mas não usa android:targetName para segmentar uma tag <overlayable> específica.

Observação: se o pacote de destino não tiver uma sobreposição definida, a sobreposição deverá ser pré-instalada na imagem do sistema ou assinada com a mesma assinatura do destino para sobrepor os recursos do pacote de destino.

Políticas de restrição

Use a tag <policy> para impor restrições aos recursos sobrepostos. O atributo type especifica quais políticas uma sobreposição deve cumprir para substituir os recursos incluídos. Os tipos com suporte incluem o seguinte.

• public . Qualquer sobreposição pode substituir o recurso.
• system . Qualquer sobreposição na partição do sistema pode substituir os recursos.
• vendor . Qualquer sobreposição na partição do fornecedor pode substituir os recursos.
• product . Qualquer sobreposição na partição do produto pode substituir os recursos.
• signature . Qualquer sobreposição assinada com a mesma assinatura do APK de destino pode substituir os recursos.

O código a seguir mostra um exemplo de tag <policy> no arquivo 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 várias políticas, use barras verticais (|) como caracteres separadores. Quando várias políticas são especificadas, uma sobreposição precisa atender apenas a uma política para substituir os recursos listados na tag <policy> .

Configurando sobreposições

O Android oferece suporte a diferentes mecanismos para configurar a mutabilidade, o estado padrão e a prioridade das sobreposições, dependendo da versão de lançamento do Android.

• Dispositivos com Android 11 ou superior podem usar um arquivo OverlayConfig ( config.xml ) em vez de atributos de manifesto. Usar um arquivo de sobreposição é o método recomendado para sobreposições.

• Todos os dispositivos podem usar atributos de manifesto ( android:isStatic e android:priority ) para configurar RROs estáticos.

Observação: somente as sobreposições imutáveis ​​direcionadas ao pacote android afetam os valores de recursos recuperados por meio Resources.getSystem() .

Usando OverlayConfig

No Android 11 ou superior, você pode usar o OverlayConfig para configurar a mutabilidade, o estado padrão e a prioridade das sobreposições. Para configurar uma sobreposição, crie ou modifique o arquivo localizado em partition/overlay/config/config.xml , onde partition é a partição da sobreposição a ser configurada. Para ser configurado, um overlay deve residir no diretório overlay/ da partição na qual o overlay está configurado. O código a seguir mostra um exemplo 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>"

A tag <overlay> requer um atributo de package que indica qual pacote de sobreposição está sendo configurado. O atributo enabled opcional controla se a sobreposição está ou não ativada por padrão (o padrão é false ). O atributo mutable opcional controla se a sobreposição é mutável ou não e pode ter seu estado ativado alterado programaticamente em tempo de execução (o padrão é true ). As sobreposições não listadas em um arquivo de configuração são mutáveis ​​e desabilitadas por padrão.

Precedência de sobreposição

Quando várias sobreposições substituem os mesmos recursos, a ordem das sobreposições é importante. Uma sobreposição tem maior precedência do que sobreposições com configurações que precedem sua própria configuração. A ordem de precedência das sobreposições em diferentes partições (da menor para a maior precedência) é a seguinte.

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

Nota: Quando o OverlayManagerService habilita sobreposições não configuradas, a ordem das sobreposições é indefinida.

Mesclando arquivos

O uso de tags <merge> permite que outros arquivos de configuração sejam mesclados na posição especificada no arquivo de configuração. O atributo path da tag representa o caminho do arquivo a ser mesclado em relação ao diretório que contém os arquivos de configuração de sobreposição.

Usando atributos de manifesto (RROs estáticos)

No Android 10 ou inferior, a imutabilidade e a precedência da sobreposição são configuradas usando os seguintes atributos de manifesto.

• android:isStatic . Quando o valor desse atributo booleano é definido como true , a sobreposição é habilitada por padrão e é imutável, o que impede que a sobreposição seja desabilitada.

• android:priority . O valor desse atributo numérico (que afeta apenas as sobreposições estáticas) configura a precedência da sobreposição quando várias sobreposições estáticas visam o mesmo valor de recurso. Um número mais alto indica uma precedência mais alta.

O código a seguir mostra um exemplo 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>

Mudanças no Android 11

No Android 11 ou superior, se um arquivo de configuração estiver localizado em partition/overlay/config/config.xml , as sobreposições serão configuradas usando esse arquivo e android:isStatic e android:priority não afetarão as sobreposições localizadas na partição. Definir um arquivo de configuração de sobreposição em qualquer partição impõe a precedência da partição de sobreposição.

Além disso, o Android 11 ou superior remove a capacidade de usar sobreposições estáticas para afetar os valores dos recursos lidos durante a instalação do pacote. Para o caso de uso comum de uso de sobreposições estáticas para alterar o valor de booleanos que configuram o estado ativado do componente, use a tag <component-override> SystemConfig (nova no Android 11).

Depuração de sobreposições

Para habilitar, desabilitar e despejar manualmente sobreposições, use o seguinte comando shell do gerenciador de sobreposições.

adb shell cmd overlay

OverlayManagerService usa idmap2 para mapear IDs de recursos no pacote de destino para IDs de recursos no pacote de sobreposição. Os mapeamentos de ID gerados são armazenados em /data/resource-cache/ . Se sua sobreposição não estiver funcionando corretamente, encontre o arquivo idmap correspondente para sua sobreposição em /data/resource-cache/ e execute o seguinte comando.

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

Este comando imprime o mapeamento de recursos conforme mostrado abaixo.

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