Alterar o valor dos recursos de um aplicativo no tempo de execução

Uma sobreposição de recursos no ambiente de execução (RRO) é um pacote que altera os valores de recursos de um pacote de destino no ambiente de execução. Por exemplo, um app instalado no sistema imagem pode mudar de comportamento com base no valor de um recurso. Em vez de fixar no código o valor do recurso no tempo de build, uma RRO instalada em um pode alterar os valores dos recursos do aplicativo no ambiente de execução.

As RROs podem ser ativadas ou desativadas. Você pode definir programaticamente o ativar/desativar o estado para alternar a capacidade de uma RRO de alterar valores de recursos. RROs ficam desativados por padrão. No entanto, as RROs estáticas são ativadas padrão).

Observação: uma RRO só pode ser usada para alterar os valores de um recurso atual.

Recursos de sobreposição

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

Configurar o manifesto

Um pacote é considerado RRO se tiver uma tag <overlay> como filho da tag <manifest>.

• O valor do atributo obrigatório android:targetPackage especifica o nome. do pacote que a RRO pretende sobrepor.

• O valor do atributo opcional android:targetName especifica o nome do o subconjunto sobreposto de recursos do pacote de destino que a RRO pretende sobreposição. Se o destino não definir um conjunto de recursos sobreposto, este não deve 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, por isso não podem ter arquivos DEX. Além disso, Atributo android:hasCode de <application> no manifesto precisa ser Defina como false.

Definir o mapa de recursos

No Android 11 ou versões mais recentes, o mecanismo recomendado para definir o mapa de recursos de sobreposição é criar um arquivo no res/xml do pacote de sobreposição, enumerar os recursos de destino que devem ser sobrepostas e seus valores de substituição, defina o valor do android:resourcesMap da tag de manifesto <overlay> a uma referência ao arquivo de mapeamento de recursos.

O código abaixo 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 exemplo de manifesto de sobreposição.

<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 versões anteriores, os recursos são sobrepostos com base no nome. Para sobrepor o recurso string/foo no pacote de destino, a sobreposição também precisa defina o recurso string/foo.

Criar o pacote

O Android 11 ou versões mais recentes oferecem suporte a uma regra de build Soong para sobreposições que impedem o Android Asset Packaging Tool 2 (AAPT2) de tentar eliminar a duplicação de configurações de recursos com o mesmo valor (--no-resource-deduping) e da remoção de recursos sem padrão (--no-resource-removal). O código a seguir mostra um exemplo arquivo Android.bp.

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

Resolver recursos

Se um recurso de destino ou de sobreposição tiver várias configurações definidas para o recurso que está sendo consultado, o ambiente de execução de recursos retorna o valor do que melhor corresponda à configuração do dispositivo. Para determinar qual é a configuração mais adequada, mescle o um conjunto de configurações de recursos de sobreposição no conjunto de recursos de destino e seguir o fluxo regular de resolução de recursos (por exemplo, detalhes, consulte Como o Android encontra as melhores recurso).

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, portanto, o valor da configuração de destino drawable-en-port é escolhido no tempo de execução. Para sobrepor todas as configurações de drawable-en, a sobreposição precisa definir um valor para cada configuração de drawable-en definida pelo destino.

As sobreposições podem referenciar seus próprios recursos, com comportamentos diferentes entre Versões do Android.

• No Android 11 ou versões mais recentes, cada sobreposição tem espaço de ID de recurso reservado que não se sobrepõe ao espaço de ID do recurso de destino ou outros espaços de ID de recurso de sobreposição, de modo que as sobreposições que fazem referência aos próprios recursos funcionar da forma esperada.

• No Android 10 ou versões anteriores, as sobreposições e os pacotes de destino compartilham o mesmo recurso ID do cliente, que pode causar colisões e comportamentos inesperados quando tentam para referenciar os próprios recursos usando a sintaxe @type/name.

Ativar/desativar sobreposições

Usar a API OverlayManager para ativar e desativar sobreposições mutáveis (extrair a interface da API usando Context#getSystemService(Context.OVERLAY_SERVICE)). Um sobreposição pode ser ativada somente pelo pacote que ela segmenta ou por um pacote com o android.permission.CHANGE_OVERLAY_PACKAGES. Quando uma sobreposição é ativados ou desativados, os eventos de alteração de configuração são propagados para o pacote de destino e das atividades de destino.

Restringir recursos sobrepostos

No Android 10 ou versões mais recentes, a tag XML <overlayable> expõe um conjunto de recursos que as RROs podem sobrepor. No exemplo a seguir, O arquivo res/values/overlayable.xml, string/foo e integer/bar são recursos usado para aplicar temas à aparência do dispositivo; para sobrepor esses recursos, uma sobreposição precisa segmentar explicitamente o conjunto de recursos que podem ser 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 precisa ter uma tag exclusiva. dentro do pacote. Por exemplo, ela é:

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

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

O código abaixo mostra um exemplo de sobreposição na 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 app define uma tag <overlayable>, as sobreposições que segmentam esse app:

• É necessário especificar targetName.

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

• É possível segmentar apenas um nome <overlayable>.

Não é possível ativar uma sobreposição que segmenta um pacote que expõe recursos, mas não usa android:targetName para visar um <overlayable>.

Observação: se o pacote de destino não tiver um elemento sobreposto definido, a sobreposição precisará pré-instalado na imagem do sistema ou assinado com a mesma assinatura do para sobrepor os recursos do pacote de destino.

Políticas de restrição

Use a tag <policy> para aplicar restrições a recursos que podem ser sobrepostos. A O atributo type especifica quais políticas uma sobreposição precisa preencher para substituir os recursos incluídos. Os tipos compatíveis incluem os seguintes.

• 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.
• oem: Qualquer sobreposição na partição do OEM pode substituir os recursos.
• odm: Qualquer sobreposição na partição odm pode substituir os recursos.
• signature: Qualquer sobreposição assinada com a mesma assinatura do APK de destino pode substituir os recursos.
• actor: Qualquer sobreposição assinada com a mesma assinatura do APK do ator pode substituir os recursos. O ator é declarado na tag names-actor do sistema. configuração
• config_signature: Qualquer sobreposição com a mesma assinatura do O apk overlay-config pode substituir os recursos. O overlay-config é declarado na tag overlay-config-signature na configuração do sistema.

O código a seguir mostra um exemplo de tag <policy> na 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 a apenas uma para substituir os recursos listados na tag <policy>.

Configurar sobreposições

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

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

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

.

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

Usar OverlayConfig

No Android 11 ou versões mais recentes, você pode usar 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, em que partition é a partição do a ser configurada. Para ser configurada, uma sobreposição deve residir no Diretório overlay/ da partição em que a sobreposição está configurada. A 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 package que indica qual sobreposição está sendo configurado. O atributo opcional enabled controla se a sobreposição será ativada por padrão (o padrão é false). O parâmetro opcional O atributo mutable controla se a sobreposição é mutável e pode ter o estado ativado mudou programaticamente no momento da execução (o padrão é true). As sobreposições não listadas em um arquivo de configuração são mutáveis e desativadas por padrão.

Precedência da sobreposição

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

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

.

Observação :quando o OverlayManagerService ativa sobreposições não configuradas, a ordem de sobreposições é indefinido.

Mesclar arquivos

O uso de tags <merge> permite que outros arquivos de configuração sejam mesclados no 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 arquivos de configuração de sobreposição.

Usar atributos de manifesto/RROs estáticas

No Android 10 ou versões anteriores, a imutabilidade e a precedência de 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 é ativada por padrão e é imutável, o que impede que a sobreposição sejam desativados.

• android:priority: O valor desse atributo numérico (que afeta apenas sobreposições estáticas) configura a precedência da sobreposição quando vários as sobreposições segmentam o mesmo valor de recurso. Quanto maior o número, maior precedência.

O código abaixo 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 mais recente, se um arquivo de configuração for localizados em partition/overlay/config/config.xml, as sobreposições são configuradas usando esse arquivo e android:isStatic e android:priority não afetam superposições de dados localizadas na partição. Definir um arquivo de configuração de sobreposição em qualquer a partição aplica a precedência da partição de sobreposição.

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

Depurar sobreposições

Para ativar, desativar e despejar sobreposições manualmente, use a seguinte sobreposição gerenciador de shell do Cloud.

adb shell cmd overlay

OverlayManagerService usa idmap2 para mapear IDs de recursos no destino. aos IDs de recursos no pacote de sobreposição. Os mapeamentos de ID gerados são armazenada 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, em seguida, execute o comando a seguir.

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

Esse 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