minSdkVersion: o que é e como escolher a versão mínima do Android

O que é minSdkVersion no Android?

minSdkVersion é um parâmetro inteiro no build.gradle que especifica o nível mínimo de API do Android para instalação do aplicativo. Se o nível de API do dispositivo estiver abaixo do valor especificado, o PackageManager bloqueia a instalação e o Google Play Store oculta o aplicativo dos resultados de busca para esse dispositivo. minSdkVersion é escrito no AndroidManifest.xml durante a compilação através da tag <uses-sdk android:minSdkVersion> e é verificado a cada instalação.

O valor de minSdkVersion é um compromisso entre o alcance do público e o acesso a novas APIs. Quanto menor o minSdk, mais dispositivos podem instalar o aplicativo, especialmente em regiões em desenvolvimento onde smartphones Android antigos são populares. Quanto maior o minSdk, menos código de compatibilidade retroativa é necessário e mais APIs modernas estão disponíveis sem verificações em tempo de execução. Android Jetpack e bibliotecas AndroidX fornecem backports de muitas APIs novas para versões antigas do Android, permitindo escolher um minSdk mais baixo sem perder funcionalidade.

minSdkVersion afeta todas as etapas do desenvolvimento: análise estática (lint usa minSdk para avisos), compatibilidade de dependências (bibliotecas podem exigir seu próprio minSdk), testes (é necessário testar em dispositivos com minSdk) e Google Play Console (o alcance do público é calculado com base no minSdk). Alterar minSdkVersion é uma das decisões mais importantes na configuração do projeto, pois afeta o código, os testes e a base de usuários.

Onde minSdkVersion é especificado

Build.gradle.kts (Kotlin DSL) é o padrão moderno em projetos Android. O parâmetro minSdk é definido no bloco defaultConfig no nível do módulo. O valor pode ser sobrescrito para diferentes tipos de compilação e variantes de produto, permitindo testar em APIs mais baixas sem alterar o valor principal.

// build.gradle.kts — configuração básica do minSdk
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26      // Android 8.0 Oreo
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }

    // Sobrescrita do minSdk para diferentes sabores
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

No exemplo, minSdk = 26 corresponde ao Android 8.0 Oreo. Este é um valor popular em 2026: ele exclui apenas ~15% dos dispositivos de acordo com o Distribution Dashboard do Android Studio. compileSdk = 36 dá acesso a todas as APIs do Android 16, e targetSdk = 36 inclui as mudanças comportamentais da versão mais recente. Para compilações de depuração, minSdk pode ser reduzido para testes em emuladores antigos.

Como escolher minSdkVersion: fatores e estratégia

Escolher minSdkVersion é uma decisão estratégica baseada na análise do público-alvo, requisitos de API e ecossistema de bibliotecas. Não existe um único valor correto para todos os projetos. Em 2026, o Android Studio recomenda minSdk = 26 (Android 8.0) como nível base para novos projetos, mas para aplicações B2B ou soluções empresariais, valores mais baixos ou mais altos podem ser aceitáveis.

Fatores para escolher minSdkVersion

O primeiro fator é o Distribution Dashboard. O Android Studio fornece estatísticas de dispositivos ativos por nível de API com base em dados do Google Play, atualizadas mensalmente. minSdkVersion deve cobrir pelo menos 90-95% dos dispositivos ativos do mercado-alvo. Para aplicativos internacionais com público na África e Sudeste Asiático, minSdk deve ser reduzido para 21 (Android 5.0) devido à alta proporção de dispositivos antigos.

O segundo fator são os requisitos de dependências. Cada biblioteca tem seu próprio minSdkVersion especificado em seu manifesto. Se uma biblioteca requer minSdk 29 e o aplicativo requer minSdk 26, a compilação falhará com um erro de fusão de manifesto. As bibliotecas modernas do Google Play Services têm minSdk 21, Firebase tem minSdk 21, a maioria das bibliotecas Jetpack tem minSdk 21 ou 26, e Compose BOM tem minSdk 21. Para Compose, o limite mínimo é API 21.

O terceiro fator são as APIs necessárias. Se uma funcionalidade chave do aplicativo requer uma API disponível apenas a partir de um certo nível (por exemplo, PhotoPicker — API 34, Predicted Navigation — API 35), isso pode justificar o aumento do minSdk. No entanto, uma combinação de backports do AndroidX (Activity Result API, NotificationCompat) e verificações em tempo de execução é mais frequentemente usada para manter um minSdk baixo.

Estratégia de seleção passo a passo

Passo 1: abra o Android Studio, File → New Project, e veja o minSdk recomendado no assistente. Passo 2: verifique o Distribution Dashboard no Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Passo 3: analise as dependências do projeto — execute a compilação e corrija conflitos de fusão de manifesto. Passo 4: avalie quais APIs de nível X são realmente usadas sem backports. Passo 5: defina minSdk como o valor mínimo que cobre 90%+ do público-alvo e é compatível com todas as dependências.

Cobertura de dispositivos: distribuição de níveis de API (2026)

A distribuição de dispositivos por nível de API é uma métrica dinâmica que muda a cada trimestre. De acordo com o Distribution Dashboard do Android Studio de junho de 2026, cerca de 85% dos dispositivos Android ativos rodam em API 26 (Android 8.0) e superior, 72% em API 29 (Android 10) e superior, e 55% em API 31 (Android 12) e superior. O mercado chinês tem suas próprias estatísticas devido à ausência do Google Play Services em muitos dispositivos Huawei.

Os dispositivos GMS (Google Mobile Services) atualizam mais rápido: a parcela de API 31+ neles atinge 68% graças aos requisitos obrigatórios do Google Play para fabricantes. Os dispositivos não-GMS (Huawei, Honor, algumas marcas chinesas) têm uma distribuição mais antiga: a parcela de API 31+ neles é de cerca de 35%. Se seu aplicativo é voltado para o mercado internacional, confie nas estatísticas globais. Se é voltado para a China, considere o segmento não-GMS.

Conclusão: para um aplicativo internacional, minSdk 26 cobre 85% dos dispositivos com custos mínimos de compatibilidade retroativa. Para aplicativos com público em regiões em desenvolvimento, minSdk 21 (97% de cobertura) é justificado, mas exigirá mais código para trabalhar com APIs legadas. Para aplicativos empresariais com uma frota de dispositivos controlada, você pode definir minSdk 31 e eliminar completamente o código de fallback.

Compatibilidade retroativa: AndroidX, lint e @RequiresApi

A compatibilidade retroativa é o principal desafio com um minSdkVersion baixo. O AndroidX (anteriormente Support Library) fornece backports de APIs modernas para versões antigas do Android: AppCompatActivity para Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat e dezenas de outros componentes. Usar equivalentes do AndroidX em vez de APIs nativas é o primeiro passo para a compatibilidade.

lint (o analisador estático do Android Studio) escaneia o código em busca de chamadas de API acima de minSdkVersion. Se um método é anotado com @RequiresApi em um nível de API maior que minSdk e é chamado sem verificação, o lint destaca um erro. Para suprimir o aviso, use a anotação @SuppressLint("NewApi") no método ou @RequiresApi(Build.VERSION_CODES.TIRAMISU) em toda a função. As verificações em tempo de execução via Build.VERSION.SDK_INT são o mecanismo principal para chamar com segurança novas APIs em dispositivos antigos.

// Exemplo de compatibilidade retroativa: PhotoPicker (API 34+) e fallback
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — funciona em qualquer nível de API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker está disponível apenas a partir da API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Usando PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (funciona em todas as versões)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Este método não pode ser chamado na API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

A classe ImagePickerActivity demonstra três níveis de compatibilidade retroativa. A Activity Result API do AndroidX funciona em todos os níveis de API, portanto a seleção básica de imagem não depende do minSdk. O PhotoPicker (ACTION_PICK_IMAGES) está disponível apenas a partir da API 34 e é chamado sob uma verificação de SDK_INT com fallback para GetContent. O método usePhotoPickerOnly é marcado com @RequiresApi — o lint não permitirá chamá-lo sem verificação. O AppCompat do AndroidX adapta automaticamente o tema, fragmentos e animações à versão do SO.

minSdkVersion em bibliotecas e módulos

Bibliotecas (AAR, JAR) também têm um minSdkVersion especificado em seu manifesto. Ao conectar uma biblioteca, o Gradle verifica a compatibilidade: se o minSdk da biblioteca for maior que o minSdk do aplicativo, a compilação falha com um erro. Para bibliotecas públicas, é recomendado especificar o menor minSdk possível (21 para a maioria dos casos) para não limitar os consumidores. Se uma biblioteca requer API 29+, ela perde ~28% dos usuários potenciais.

Projetos multimódulo podem ter diferentes valores de minSdkVersion para diferentes módulos. Por exemplo, o módulo :core:network pode ter minSdk 26, enquanto o módulo :feature:camera pode ter minSdk 29 (devido ao CameraX com requisitos específicos). O Google Play exige que o minSdk do módulo principal :app seja menor ou igual ao minSdk de todos os módulos dependentes. Na prática, todos os módulos de um mesmo aplicativo geralmente têm o mesmo minSdk para facilitar a manutenção.

// build.gradle.kts — módulo de biblioteca com minSdk baixo
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // Mínimo para cobertura máxima
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, adiciona backports
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Um módulo de biblioteca com minSdk = 21 é compatível com 97% dos dispositivos e não limita os consumidores. Se a biblioteca usa APIs acima de 21, o desenvolvedor deve adicionar verificações em tempo de execução ou especificar @RequiresApi nos métodos relevantes. O AndroidX Core KTX (minSdk 21) fornece backports para Context, Bundle, Locale e outras classes do sistema, permitindo que a biblioteca mantenha um minSdk baixo.

Erros comuns ao escolher minSdkVersion

Erros ao escolher minSdk podem custar milhares de instalações ou semanas de desenvolvimento adicional. O primeiro erro comum é copiar minSdk de um modelo de projeto sem analisar o Distribution Dashboard. Muitos desenvolvedores deixam minSdk = 21 do Template do Android Studio, embora minSdk 26 fosse suficiente para seu público e reduzisse o número de verificações SDK_INT no código.

O segundo erro é um minSdk muito alto sem considerar o mercado. Se você definir minSdk = 31 (Android 12) para um aplicativo internacional, perde ~45% dos dispositivos. Para uma startup ou um aplicativo de audiência em massa, isso é um desastre. Sempre verifique o Distribution Dashboard antes de aumentar o minSdk e use testes A/B no Google Play Console se não tiver certeza.

O terceiro erro é ignorar o minSdk das dependências. Ao adicionar uma nova biblioteca, verifique seu minSdk na documentação ou no arquivo POM. O Firebase ML Kit requer minSdk 21, algumas bibliotecas de câmera personalizadas requerem minSdk 29. Se a fusão de manifesto falhar em produção devido a uma nova biblioteca, a correção pode levar dias.

// Exemplo: verificação de compatibilidade de API em tempo de execução
fun checkFeatureAvailability(): Boolean {
    // Erro típico — chamar uma API sem verificar SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — use PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — use MediaStore
            true
        }
        else -> {
            // API < 29 — usamos ACTION_GET_CONTENT
            true
        }
    }
}

A arquitetura correta para verificações de nível de API é uma expressão when com intervalos cobrindo todos os valores possíveis de minSdk a compileSdk. A regra principal: qualquer chamada a uma API de nível X deve ser protegida por uma verificação de VERSION.SDK_INT para todos os dispositivos com nível de API de minSdk a X. O lint ajuda a detectar chamadas não verificadas, mas não pode garantir cobertura total para código dinâmico.