Ferramentas de framework de compatibilidade

O Android 11 introduziu novas ferramentas para desenvolvedores para testar e depurar seu app em relação às mudanças de comportamento nas versões mais recentes da plataforma Android. Essas ferramentas fazem parte de um framework de compatibilidade que permite aos desenvolvedores de apps ativar e desativar alterações interruptivas usando opções do desenvolvedor ou ADB individualmente. Use essa flexibilidade para direcionar aos usuários versão estável da API e, ao testar seu aplicativo com a versão de pré-lançamento da próxima versão do Android.

Quando você usa as ferramentas do framework de compatibilidade, a plataforma Android adapta automaticamente sua lógica interna, para que você não precise alterar seu targetSDKVersion ou recompile o app para realizar testes básicos. Devido ao as mudanças podem ser alternadas individualmente, é possível isolar, testar e depurar uma de comportamento de cada vez ou desativar uma única mudança que esteja causando problemas se você precisa testar outra coisa primeiro.

Como identificar quais mudanças estão ativadas

Quando uma mudança de comportamento está ativada, ela pode afetar a forma como seu app acessa as APIs da plataforma impactadas por essa mudança. É possível verificar qual comportamento as mudanças são ativadas usando as opções do desenvolvedor, o logcat ou os comandos ADB.

Identificar mudanças ativadas usando as opções do desenvolvedor

Figura 1. Tela de mudanças na compatibilidade de apps nas opções do desenvolvedor.

Você pode ver quais mudanças estão ativadas e ativar ou desativar essas mudanças no as opções do desenvolvedor de um dispositivo. Para acessar essas opções, siga estas etapas:

  1. Se as opções do desenvolvedor ainda não estiverem ativadas, ative-as.
  2. Abra o app Configurações do seu dispositivo e navegue até Sistema > Avançado > Opções do desenvolvedor > Mudanças na compatibilidade de apps.

  3. Selecione seu app na lista.

Cada mudança de comportamento geralmente pertence a uma destas duas categorias:

  • Mudanças que afetam todos os apps executados nessa versão do Android, independentemente da targetSdkVersion do app.

    Essas mudanças são ativadas por padrão no framework de compatibilidade e são listadas na IU na seção Mudanças ativadas por padrão.

  • Mudanças que afetam apenas apps voltados a determinadas versões do Android. Como essas mudanças afetam apenas os apps voltados a uma versão específica do Android, elas também são chamadas de mudanças controladas pela targetSDKVersion.

    Essas mudanças serão ativadas por padrão no framework de compatibilidade se o app for direcionado a uma versão mais recente do que a da API listada. Por exemplo: uma mudança de comportamento controlada por targetSDKVersion O Android 13 (nível 33 da API) seria listado na interface com o título Ativado para targetSdkVersion >=33. Em algumas versões anteriores do Android, essa seção é chamada de "Ativado depois do SDK API_LEVEL" como alternativa.

Você também notará uma seção na figura 1 chamada Mudanças desativadas por padrão. As mudanças que se enquadram nessa seção podem servir para vários fins. Antes ativar essas alterações, leia a descrição da alteração na página de compatibilidade lista de frameworks para essa versão do Android.

Identificar mudanças ativadas usando o logcat

Para cada mudança de comportamento, na primeira vez durante o processo do app quando o app chama a API afetada, o sistema gera uma mensagem de logcat como esta:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

Cada mensagem de logcat inclui as seguintes informações:

ID da mudança
Indica qual mudança está afetando o app. Esse valor é mapeado para uma das mudanças de comportamento listadas na tela Mudanças na compatibilidade de apps (consulte a figura 1). Neste exemplo, 194833441 é mapeado para NOTIFICATION_PERM_CHANGE_ID.
UID
Indica qual app é afetado pela mudança.
Estado

Indica se a mudança está afetando o app.

O estado pode ser um destes valores:

Estado Significado
ENABLED A mudança está ativada e afetará o comportamento do app se o aplicativo usa as APIs que foram alteradas.
DISABLED

A mudança está desativada e não vai afetar o app.

Observação: se essa mudança estiver desativada porque a targetSDKVersion do app está abaixo do limite necessário, a mudança será ativada por padrão quando o app aumentar o valor da targetSDKVersion para ser direcionado a uma versão mais recente.
LOGGED A mudança está sendo registrada pelo framework de compatibilidade, mas não pode ser ativada ou desativada. Apesar disso, ela ainda pode afetar o comportamento do app. Para mais informações, consulte a descrição da mudança na lista do framework de compatibilidade dessa versão do Android. Em muitos casos, esses tipos de mudanças são experimentais e podem ser ignorados.

Identificar mudanças ativadas usando ADB

Execute o seguinte comando ADB para ver o conjunto completo de mudanças (ativas e desativadas) em todo o dispositivo:

adb shell dumpsys platform_compat

A saída lista as seguintes informações para cada mudança:

ID da mudança
Um identificador exclusivo para essa mudança de comportamento. Por exemplo, 194833441.
Nome
O nome dessa mudança de comportamento. Por exemplo, NOTIFICATION_PERM_CHANGE_ID.
critérios de targetSDKVersion

Por qual targetSDKVersion a mudança é controlada (se houver).

Por exemplo, se essa mudança só for ativada para apps destinados à versão do SDK 33 ou mais recente, enableAfterTargetSdk=32 é a saída. Se a mudança não for controlado por targetSDKVersion, enableAfterTargetSdk=0 é a saída.

Modificações de pacotes

O nome de cada pacote em que o estado padrão da mudança (ativado ou desativado) foi substituído.

Por exemplo, se essa for uma mudança ativada por padrão, o nome do pacote do app será listado se você tiver desativado a mudança usando as opções do desenvolvedor ou o ADB. Nesse caso, o resultado seria:

packageOverrides={com.my.package=false}

As mudanças controladas por targetSDKVersion podem ser ativadas ou desativada por padrão, de modo que a lista de pacotes pode incluir instâncias de ambos true ou false, dependendo da targetSDKVersion do app. Por exemplo:

packageOverrides={com.my.package=true, com.another.package=false}

Saiba mais sobre mudanças específicas

A lista completa de mudanças de comportamento no framework de compatibilidade está incluída como da documentação de cada versão do Android. Acesse os links a seguir para mais informações, dependendo da versão do Android em que você está testando o app para:

Quando ativar ou desativar as mudanças

O principal objetivo do framework de compatibilidade é oferecer a você controle e flexibilidade para testar seu app com versões mais recentes do Android. Esta seção descreve algumas estratégias que podem ser usadas para determinar quando ativar ou desativar mudanças durante o teste e a depuração do app.

Quando desativar as mudanças

A decisão de quando desativar as mudanças geralmente depende de a mudança ser controlada pela targetSDKVersion ou não.

Mudanças ativadas para todos os apps

As mudanças que afetam todos os apps são ativadas por padrão para uma versão específica da plataforma, independentemente da targetSDKVersion. Assim, é possível conferir se o app é afetado pela execução da nessa versão da plataforma.

Por exemplo, se você estiver se preparando para direcionar ao Android 15 (nível 35 da API), você pode começar instalando o app em um dispositivo que executa Android 15 e testar o app usando os testes típicos os fluxos de trabalho. Se o app tiver problemas, desative a mudança é a causa do problema. Assim, você pode continuar testando se há outros problemas.

Como essas mudanças podem afetar todos os apps, independente da targetSDKVersion, em geral é preciso testar e atualizar o app quanto a essas mudanças antes que elas sejam controladas pela targetSDKVersion. Isso ajuda a garantir que seus usuários não terão uma experiência de app prejudicada ao atualizar o dispositivo para um novo uma versão da plataforma.

Você também precisa priorizar o teste dessas mudanças porque não é possível desativá-las ao usar um build de lançamento público do Android. O ideal é realizar testes dessas mudanças para cada versão do Android enquanto a versão está disponível na prévia.

Mudanças controladas pela targetSDKVersion

Caso seu app esteja segmentando um targetSDKVersion, todas as mudanças controladas por essa versão serão ativadas por padrão. Quando você muda o targetSDKVersion do app para uma nova mais recente, seu app começará a ser afetado por muitas novas alterações de uma só vez.

Como o app pode ser afetado por mais de uma dessas mudanças, talvez seja necessário desativar algumas individualmente durante o teste e a depuração do app.

Quando ativar as mudanças

As mudanças controladas por uma targetSDKVersion específica são desativadas por padrão sempre que um app está direcionado a uma versão do SDK anterior à versão controlada. Normalmente, ao se preparar para direcionar a uma nova targetSdkVersion, você vai precisar testar e depurar uma lista de mudanças de comportamento no seu app.

Por exemplo, é possível testar o app em relação a uma série de mudanças de plataforma na próxima targetSdkVersion. Usando opções do desenvolvedor ou comandos ADB, é possível ativar e testar cada mudança controlada uma por uma, em vez de mudar o manifesto do app e ativar todas as mudanças de uma vez. Esse controle extra pode ajudar a testar as mudanças de forma isolada e evitar a depuração e atualização de várias partes do app ao mesmo tempo.

Depois de ativar uma mudança, você pode testar e depurar o app usando fluxos de trabalho de teste típicos. Se você encontrar problemas, verifique seus registros para ajudar a determinar a causa. Se não estiver claro se o problema é causado por de plataforma ativada, desative essa mudança e teste novamente do seu app.

Ativar ou desativar mudanças

O framework de compatibilidade permite ativar ou desativar cada mudança usando as opções do desenvolvedor ou comandos ADB. Como a ativação ou desativação de mudanças pode fazer com que o app falhe ou desative mudanças de segurança importantes, existem algumas restrições de quando você pode ativar ou desativar mudanças.

Ativar ou desativar mudanças usando as opções do desenvolvedor

Use as opções do desenvolvedor para ativar ou desativar mudanças. Para encontrar as opções, siga estas etapas:

  1. Se as opções do desenvolvedor ainda não estiverem ativadas, ative-as.
  2. Abra o app de configurações do seu dispositivo e navegue até Sistema > Avançado > Opções do desenvolvedor > Mudanças na compatibilidade de apps.
  3. Selecione seu app na lista.

  4. Na lista de mudanças, encontre a mudança que você quer ativar ou desativar e toque na chave.

    Lista de mudanças que podem ser ativadas ou desativadas

Ativar ou desativar mudanças usando o ADB

Para ativar ou desativar uma mudança usando ADB, execute um dos seguintes comandos:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Transmita ou a CHANGE_ID (por exemplo, 194833441) ou CHANGE_NAME (por exemplo, NOTIFICATION_PERM_CHANGE_ID) e o PACKAGE_NAME do seu app.

Também é possível usar o comando abaixo para redefinir uma mudança para o estado padrão, removendo qualquer substituição que você tenha definido usando o ADB ou as opções do desenvolvedor:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Restrições sobre a alternância de mudanças

Por padrão, cada mudança de comportamento é ativada ou desativada. As mudanças que afetam todos os apps são ativadas por padrão. Outras mudanças são controladas por um targetSdkVersion. Essas mudanças são ativadas por padrão quando um app é direcionado à versão correspondente do SDK ou uma mais recente e são desativadas por padrão quando um app é direcionado a uma versão do SDK anterior à versão controlada. Ao ativar ou desativar uma mudança, você modifica o estado padrão dela.

Para impedir que o framework de compatibilidade seja usado de forma maliciosa, há algumas restrições sobre quando você pode ativar ou desativar as mudanças. Se você pode ativar ou não uma mudança depende do tipo de mudança, ou seja, se o app é depurável, e o tipo de build em execução no dispositivo. A tabela a seguir descreve quando é possível ativar ou desativar diferentes tipos de mudanças:

Tipo de build App não depurável App depurável
Todas as mudanças Mudanças controladas por targetSDKVersion Todas as outras mudanças
Visualização do desenvolvedor ou build Beta Não é possível ativar/desativar Pode alternar Pode alternar
Build pública de usuário Não é possível ativar/desativar Pode alternar Não é possível ativar/desativar