Sobre as regras de retenção

Ao ativar a otimização de apps com as configurações padrão, o R8 realiza otimizações extensivas para maximizar os benefícios de performance. O R8 faz modificações substanciais no código, incluindo renomeação, movimentação e remoção de classes, campos e métodos. Se essas modificações causarem erros, especifique quais partes do código o R8 não deve modificar declarando-as nas regras keep.

Cenários comuns que exigem regras keep

O R8 identifica e preserva todas as chamadas diretas no código. No entanto, o R8 não consegue identificar usos indiretos de código, o que pode fazer com que ele remova o código de que seu app precisa, causando falhas. Use regras keep para instruir o R8 a preservar esse código usado indiretamente. Confira algumas situações comuns em que você provavelmente precisará de regras keep:

• Código acessado por reflexão: o R8 não consegue identificar quando classes, campos ou métodos são acessados com reflexão. Por exemplo, o R8 não consegue identificar um método pesquisado pelo nome usando Class.getDeclaredMethod() ou uma anotação recuperada com Class.getAnnotation(). Nesses casos, o R8 pode renomear esses métodos e anotações ou removê-los completamente, levando a uma ClassNotFoundException ou uma NoSuchMethodException no ambiente de execução.
• Código chamado da Java Native Interface (JNI): quando o código nativo (C ou C++) chama um método Java ou Kotlin, ou o código Java ou Kotlin chama o código C++ com JNI, a chamada é baseada em uma pesquisa de string dinâmica do nome do método. O R8 não consegue identificar a chamada de método baseada em string dinâmica, e as otimizações podem quebrar o código.

Esta não é uma lista exaustiva de cenários que exigem regras keep, mas ela abrange a maioria dos casos em que você pode precisar de regras keep.

Como adicionar regras keep ao seu app

A configuração das regras keep depende da versão do AGP que você usa.

Apps maiores geralmente têm código em vários módulos de biblioteca. Nesses casos, geralmente é melhor colocar as regras keep junto com o código a que elas se aplicam no módulo de biblioteca específico. A diferença crucial na manutenção de regras keep para bibliotecas está em como você declara essas regras no arquivo do módulo de biblioteca build.gradle.kts (ou build.gradle). Consulte Otimização para autores de bibliotecas para saber mais.

Para versões do AGP 9.3 e mais recentes

Adicione suas regras a um arquivo com o sufixo .keep no src/<variant>/keepRules diretório. Por exemplo, src/main/keepRules/custom-rules.keep. O uso da DSL atualizada para o AGP 9.3 e mais recentes permite a otimização de código e recursos e não exige que você defina explicitamente o arquivo de regras keep padrão do Android (proguard-android-optimize.txt), porque ele é incluído por padrão, a menos que seja omitido explicitamente.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Omitir as regras keep padrão da plataforma Android (avançado)

O AGP fornece um conjunto de regras padrão da plataforma Android. Para omitir essas regras da configuração do projeto e gerenciar todas as regras keep, defina optimization.keepRules.includeDefault como false.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

DSL legada para versões do AGP anteriores à 9.3

Adicione suas regras a um arquivo proguard-rules.pro localizado no diretório raiz do módulo do app. O arquivo já pode estar lá, mas, se não estiver, crie-o. Para aplicar as regras no arquivo, declare-o no arquivo do módulo build.gradle.kts (ou build.gradle).

Por padrão, o arquivo de build também inclui o arquivo proguard-android-optimize.txt. Esse arquivo inclui regras necessárias para a maioria dos projetos Android. Portanto, deixe-o no arquivo de build. Esse arquivo é baseado no arquivo proguard-common.txt e compartilha conteúdo com ele.

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

Adicionar uma regra keep

Ao adicionar regras keep, você pode incluir opções globais e definir suas próprias regras keep.

• Opções globais: são diretivas gerais que afetam como o R8 opera em toda a base de código. Para saber mais, consulte Opções globais.

• Regras keep: as regras keep precisam ser projetadas com cuidado para garantir o equilíbrio certo entre maximizar a otimização de código sem quebrar o app inadvertidamente. Para saber como escrever regras keep, consulte Adicionar regras keep.

Regras keep para autores de bibliotecas

Depois de aprender sobre as opções globais e a sintaxe das regras keep, consulte Otimização para autores de bibliotecas para mais detalhes.