Como mudar a versão mínima do SDK no Flutter

Este artigo explica como alterar o minSdkVersion no Flutter para garantir compatibilidade com pacotes externos. Guia completo para versões anteriores e posteriores à 2.8. Siga as etapas para que seu app funcione de maneira ideal em diferentes dispositivos Android.

Ao trabalhar com Flutter e usar pacotes de terceiros, muitas vezes você precisa ajustar o minSdkVersion para atender aos requisitos desses pacotes. Esse valor determina a versão mínima do Android que pode executar seu aplicativo. Uma configuração incorreta leva a falhas de compilação ou incompatibilidade com os usuários. Portanto, dominar o procedimento para alterar o minSdkVersion Flutter é uma habilidade essencial para desenvolvedores, técnicos e criadores de jogos.

O Flutter introduziu mudanças significativas na arquitetura de configuração do Android desde a versão 2.8. Antes, os desenvolvedores editavam diretamente o arquivo build.gradle. Agora, uma abordagem mais flexível usando local.properties está disponível. Este guia explica os dois métodos de forma clara e sequencial. Você aprenderá qual técnica se aplica à sua versão do Flutter e como evitar erros comuns.

Leia também: Como Implementar Clique em Drawables do EditText

O que é minSdkVersion e por que é importante?

minSdkVersion é um parâmetro dentro do arquivo de compilação Gradle. Ele define o nível mínimo da API Android que seu aplicativo suporta. Dispositivos com versões anteriores do Android não podem instalar seu aplicativo se o nível da API deles estiver abaixo desse limite. Esse parâmetro se torna crítico quando você adiciona pacotes que dependem de recursos específicos da API. Por exemplo, um pacote de câmera ou armazenamento pode exigir minSdkVersion 21 (Android 5.0) ou superior.

Escolher o minSdkVersion correto equilibra o alcance de audiência e as capacidades técnicas. Um valor muito baixo impede o uso de APIs modernas. Um valor muito alto exclui muitos usuários em potencial. Desenvolvedores de jogos que buscam gráficos de alto desempenho geralmente precisam de APIs mais recentes. Desenvolvedores de aplicativos profissionais que atendem a clientes corporativos podem priorizar uma compatibilidade mais ampla. Portanto, essa configuração não pode ser ignorada.

Principais diferenças antes e depois do Flutter 2.8

O Flutter 2.8 marcou um ponto de virada na arquitetura de configuração do Android. A partir desta versão, a equipe do Flutter recomenda uma abordagem centralizada usando local.properties. O método antigo de editar diretamente o build.gradle ainda funciona, mas é menos prático para projetos grandes. Aqui estão as principais diferenças:

• Versões anteriores a 2.8: Altere o minSdkVersion dentro do bloco defaultConfig em android/app/build.gradle.
• Versões 2.8 e superiores: Defina propriedades como flutter.minSdkVersion no local.properties e depois referencie-as no build.gradle.
• Vantagem do novo método: Separa a configuração específica da máquina do código fonte, facilitando a colaboração em equipe.

Se você usa Flutter 3.x ou superior, o método pós-2.8 continua válido. Na verdade, essa abordagem se tornou o padrão em modelos de novos projetos. Portanto, dominar as duas técnicas é útil para manter projetos legados e também os novos.

Alterando minSdkVersion em versões do Flutter anteriores à 2.8

Para projetos que ainda usam versões do Flutter mais antigas que a 2.8, siga estas etapas simples. Esse processo também é relevante se você estiver trabalhando com código-fonte legado que não foi migrado.

1. Abra o arquivo build.gradle localizado em Projeto > android > app > build.gradle.
2. Encontre o bloco defaultConfig dentro da seção android.
3. Altere o valor de minSdkVersion conforme necessário. Exemplo: minSdkVersion 23.
4. Salve o arquivo e execute flutter clean no seu terminal.
5. Recompile o projeto com flutter run para testar as alterações.

Certifique-se de não modificar outros parâmetros acidentalmente. Um erro comum é editar sem querer o compileSdkVersion ou targetSdkVersion. Concentre-se apenas no minSdkVersion. Após fazer a alteração, executar flutter clean é obrigatório para limpar o cache.

Alterando minSdkVersion no Flutter 2.8 e superiores

Para projetos que usam Flutter 2.8 ou superior, utilize o método mais limpo descrito abaixo. Essa abordagem também é recomendada para equipes, pois a configuração não se mistura ao código versionado.

1. Abra o arquivo local.properties em Projeto > android > local.properties. Se não existir, ele será criado automaticamente durante a primeira compilação.
2. Adicione as seguintes linhas ao final do arquivo (ou modifique as existentes):
   flutter.minSdkVersion=21
flutter.targetSdkVersion=30
flutter.compileSdkVersion=30
3. Abra o arquivo build.gradle na mesma pasta (android/app/build.gradle).
4. Altere a seção defaultConfig para ficar assim:
   minSdkVersion localProperties.getProperty('flutter.minSdkVersion').toInteger()
targetSdkVersion localProperties.getProperty('flutter.targetSdkVersion').toInteger()
5. Salve ambos os arquivos e execute flutter clean.
6. Execute flutter run para verificar.

A vantagem deste método é que você pode alterar as versões do SDK modificando apenas um arquivo. Equipes que usam controle de versão podem ignorar o local.properties (adicione ao .gitignore), enquanto o build.gradle permanece consistente para todos os membros.

Verificação e solução de problemas comuns

Após aplicar as alterações, verifique-as com flutter build apk. Se for bem-sucedido, o APK resultante terá o novo minSdkVersion. Você pode verificar isso usando a ferramenta aapt do SDK Android. Exemplo de comando:

aapt dump badging app-debug.apk | grep sdkVersion

Alguns problemas comuns que você pode encontrar:

• Erro “minSdkVersion cannot be less than version declared in library” → Isso significa que um pacote exige um minSdkVersion mais alto. Aumente seu valor de acordo com a exigência do pacote.
• A sincronização do Gradle falha → Verifique se a sintaxe para chamar as propriedades no build.gradle está correta. Preste atenção às letras maiúsculas.
• As alterações não têm efeito → Exclua as pastas .gradle e build dentro de android/ e repita o flutter clean.

Se você usa pipelines de CI/CD como GitHub Actions ou Jenkins, certifique-se de que o arquivo local.properties seja criado automaticamente com os valores apropriados. Você pode adicionar uma etapa como echo "flutter.minSdkVersion=21" >> android/local.properties no seu script de compilação.

Valores recomendados de minSdkVersion para aplicativos e jogos

A seleção do minSdkVersion correto deve ser baseada na pesquisa de público. Para aplicativos profissionais que visam um mercado amplo, a versão 21 (Android 5.0) ainda é comum porque cobre mais de 90% dos dispositivos ativos. No entanto, para jogos com gráficos pesados (como os que usam Vulkan ou OpenGL ES 3.2), talvez seja necessário aumentá-lo para 24 (Android 7.0) ou 26 (Android 8.0).

• minSdkVersion 19 (KitKat) → Apenas para suportar dispositivos muito antigos, alto risco de segurança.
• minSdkVersion 21 (Lollipop) → Escolha equilibrada entre alcance e recursos modernos.
• minSdkVersion 23 (Marshmallow) → Suporta permissões em tempo de execução, recomendado para novos aplicativos.
• minSdkVersion 26+ (Oreo) → Para jogos ou aplicativos que aproveitam as APIs mais recentes, como HDR ou JobScheduler.

Além disso, consulte as estatísticas de distribuição de versões do Android no Android Studio através do SDK Manager. Esses dados ajudam você a tomar decisões baseadas em evidências, não em suposições.

Conclusão

Alterar o minSdkVersion no Flutter é uma tarefa rotineira que todo desenvolvedor deve dominar. Esteja você usando uma versão antiga (anterior à 2.8) ou a versão mais recente, os procedimentos descritos acima garantirão que seu aplicativo permaneça compatível com pacotes externos. Sempre priorize o flutter clean após qualquer alteração de configuração. Com esse conhecimento, você pode evitar falhas de compilação e oferecer a melhor experiência aos seus usuários.

Finalmente, não hesite em testar em vários dispositivos emulados com diferentes níveis de API. Essa etapa verifica se seu aplicativo realmente funciona com o minSdkVersion especificado. Feliz codificação e otimize seus projetos Flutter!