API Level: o que é, versões da API e targetSdk

O que é API Level Android?

API Level Android é um identificador inteiro atribuído a cada versão pública da API do Android Framework. O primeiro lançamento Android 1.0 tinha API Level 1, Android 1.5 — API Level 3, Android 2.2 — API Level 8, Android 4.0 — API Level 14, Android 8.0 — API Level 26, Android 12 — API Level 31, Android 14 — API Level 34, Android 15 — API Level 35, Android 16 (2025) — API Level 36. Cada novo API Level pode adicionar novas classes, métodos, constantes, permissões e alterar o comportamento dos existentes.

O API Level não aumenta estritamente em 1 a cada versão. Por exemplo, Android 4.4W (Wear) tem API 20, enquanto Android 5.0 — API 21. As lacunas estão relacionadas a iterações internas e dispositivos Wear OS. Para o desenvolvedor, é importante conhecer não o nome da versão (KitKat, Lollipop, Tiramisu), mas seu API Level — é o que é usado no código para verificações de compatibilidade.

O principal objetivo do API Level é a compatibilidade retroativa. Um aplicativo compilado contra API 34 pode funcionar em dispositivos com API 34 e inferiores (se não usar novas APIs sem verificação). O Android Runtime (ART) verifica as chamadas de API em nível de sistema e aplica mudanças comportamentais dependendo do targetSdkVersion do aplicativo.

Como o Android lida com o API Level

Ao instalar um aplicativo, o PackageManager verifica se o API Level do dispositivo >= minSdkVersion do AndroidManifest.xml. Se a condição não for atendida — a instalação é bloqueada com a mensagem "App not installed". Durante a execução, o Android Runtime monitora chamadas de API que exigem um API Level superior e gera NoSuchMethodError ou UnsatisfiedLinkError se o método não estiver presente na versão atual.

minSdk, targetSdk, compileSdk: diferenças e papel de cada parâmetro

No arquivo build.gradle (Module: app), o desenvolvedor especifica três parâmetros de API Level: minSdkVersion, targetSdkVersion e compileSdkVersion. Confundi-los é um dos erros mais comuns entre desenvolvedores Android iniciantes. Cada parâmetro é responsável por um aspecto diferente da compatibilidade, e seus valores devem ser consistentes.

minSdkVersion

minSdkVersion é o API Level mínimo no qual o aplicativo pode ser instalado e executado. Dispositivos com API Level abaixo de minSdk não veem o aplicativo na Google Play e não podem instalá-lo. O valor é escolhido com base no público-alvo: minSdk 21 (Android 5.0) cobre 97% dos dispositivos, minSdk 26 (Android 8.0) — cerca de 85%, minSdk 31 (Android 12) — cerca de 55% (dados do Android Studio Distribution Dashboard, 2026). Quanto menor o minSdk, maior a cobertura, mas mais código de compatibilidade retroativa é necessário.

targetSdkVersion

targetSdkVersion é o API Level contra o qual o aplicativo foi testado. O Android usa targetSdk para aplicar mudanças comportamentais: se o aplicativo especifica targetSdk 33, o sistema ativa todas as mudanças comportamentais introduzidas na API 33. Se targetSdk for 31, o sistema não aplica as mudanças da API 32-33, preservando a compatibilidade com o comportamento antigo. Este é o parâmetro mais importante para a segurança: o Google Play exige targetSdk não mais de 1 ano desde o API Level atual.

compileSdkVersion

compileSdkVersion é a versão do Android SDK contra a qual o código é compilado. Determina quais APIs estão disponíveis em tempo de compilação. compileSdk deve ser >= targetSdk e, idealmente, igual ao último API Level estável. Aumentar compileSdk não afeta o comportamento em tempo de execução — apenas a disponibilidade de novas APIs para o compilador. Após aumentar compileSdk, é necessário verificar o código em busca de APIs obsoletas e novos requisitos de permissões.

// build.gradle.kts — exemplo de configuração de API Level
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

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

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

No exemplo de build.gradle.kts, compileSdk = 36 (o mais recente no momento da escrita), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 dá acesso a todas as APIs do Android 16. targetSdk 36 ativa todas as mudanças comportamentais do Android 16. minSdk 26 cobre ~85% dos dispositivos. AndroidX Activity KTX e AppCompat fornecem compatibilidade retroativa para fragmentos e temas.

AndroidManifest.xml

Os parâmetros minSdk e targetSdk também podem ser especificados no AndroidManifest.xml, mas projetos modernos usam build.gradle — os valores do Gradle substituem o manifesto. No manifesto, pode ser útil especificar para bibliotecas e módulos que não usam a configuração de compilação do Gradle.

Mudanças comportamentais: como o targetSdk afeta o comportamento do aplicativo

Mudanças comportamentais são modificações na forma como o sistema Android funciona que são aplicadas apenas a aplicativos com targetSdk >= um determinado API Level. Cada nova versão do Android introduz mudanças comportamentais que podem quebrar aplicativos existentes se não forem atualizados. Este é um mecanismo chave de segurança do Android: aplicativos antigos continuam funcionando como antes, os novos seguem as regras atuais.

Principais mudanças comportamentais por versão

Android 10 (API 29) — Scoped Storage: aplicativos com targetSdk 29+ não têm acesso direto ao sistema de arquivos compartilhado, apenas via MediaStore, SAF ou seu próprio armazenamento. Android 11 (API 30) — Package Visibility: filtro de pacotes, aplicativos veem apenas os pacotes instalados com os quais interagem. Android 12 (API 31) — Foreground Service Notification: todos os serviços em primeiro plano devem mostrar uma notificação em 10 segundos após a inicialização. Android 13 (API 33) — POST_NOTIFICATIONS: permissão em tempo de execução para notificações push. Android 14 (API 34) — Foreground Service Types: declaração obrigatória do tipo de serviço em primeiro plano no manifesto.

// Manipulação de mudanças comportamentais do Android 13 (API 33): POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // A permissão POST_NOTIFICATIONS funciona apenas com API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Abaixo da API 33 a permissão não é necessária
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Permissão já concedida, pode enviar notificações
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Mostrar explicação de por que a permissão é necessária
                activity.showRationale()
            }

            else -> {
                // Solicitar permissão
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Criar e exibir notificação
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Notificação")
            .setContentText("Nova mensagem")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Registrar requestPermissionLauncher na Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permissão concedida
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Exemplo de manipulação de POST_NOTIFICATIONS em Kotlin: verificar Build.VERSION.SDK_INT >= TIRAMISU, solicitar permissão em tempo de execução via ActivityResultContracts.RequestPermission, processar o resultado em um callback. Sem essa permissão, um aplicativo com targetSdk 33+ não pode mostrar notificações push. Abaixo da API 33, a permissão não é necessária — o código de verificação impede a chamada de APIs indisponíveis.

Scoped Storage (Android 10+)

Scoped Storage é uma das mudanças comportamentais mais significativas. A partir da API 29 (targetSdk 29+), o aplicativo não pode obter acesso direto a arquivos nos diretórios Pictures, Downloads, Music e Documents. Em vez disso, usa-se MediaStore para mídia, SAF (Storage Access Framework) para arquivos arbitrários e getExternalFilesDir() para seu próprio armazenamento. A exceção são aplicativos com permissão MANAGE_EXTERNAL_STORAGE, que requer aprovação do Google Play.

Requisitos do Google Play para API Level e targetSdk

Google Play estabelece requisitos obrigatórios de targetSdkVersion para publicar aplicativos. Desde agosto de 2024, o Google Play exige targetSdkVersion >= API 33 (Android 13). A cada ano o limite aumenta: novos aplicativos e atualizações devem especificar targetSdk não mais de 1 ano desde o API Level principal atual. A violação do requisito leva ao bloqueio da publicação e à remoção do aplicativo da loja.

Por que o Google Play endurece os requisitos

A principal razão é a segurança. Cada novo API Level do Android introduz mudanças comportamentais que fecham vetores de ataque: Scoped Storage (API 29) previne roubo de arquivos, POST_NOTIFICATIONS (API 33) protege contra notificações spam, Foreground Service Types (API 34) limita serviços em segundo plano ocultos. Aplicativos com targetSdk baixo não recebem essas proteções e se tornam uma ameaça para os usuários. O Google Play não pode permitir aplicativos desatualizados em dispositivos modernos.

Verificação de conformidade com requisitos

O Google Play Console verifica targetSdkVersion ao enviar APK/AAB. Se targetSdk estiver abaixo do exigido — o console bloqueia a publicação com a mensagem: "Your app currently targets API level X and must target at least API level Y". O desenvolvedor deve atualizar build.gradle, recompilar o aplicativo, testar as mudanças comportamentais e reenviar. O formato AAB é recomendado para todas as novas publicações (obrigatório desde agosto de 2021).

Verificação do API Level no código: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT é uma constante inteira estática que contém o API Level do dispositivo no qual o aplicativo está sendo executado. É a principal ferramenta para verificações de versão do Android em tempo de execução. Build.VERSION_CODES contém constantes nomeadas para cada API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). A comparação via if (SDK_INT >= VERSION_CODES.TIRAMISU) é o padrão comum.

// Exemplos de verificação de API Level em código Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Verificação básica de API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Chamada de API adaptativa com verificação
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable está disponível apenas com API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback para dispositivos antigos
    }

    // 3. Verificação de permissão POST_NOTIFICATIONS (apenas API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Seleção do provedor de imagens por API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ usa PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ usa Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (todas as versões)
                "get_content"
            }
        }
    }

    // 5. Verificação estilo Java via @TargetApi (para compatibilidade retroativa)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // O comportamento do Scoped Storage depende de targetSdk, não de SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informações de compilação para análise
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// Teste
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

A classe ApiLevelHelper demonstra todos os padrões principais de verificação de API Level: isAtLeastTiramisu com SDK_INT >= VERSION_CODES, getAdaptiveIcon com fallback para versões antigas, getImagePickerProvider with when multi-ramificação, getDeviceApiInfo para análise. A regra chave é não chamar novas APIs sem verificar SDK_INT, caso contrário o aplicativo falhará com NoSuchMethodError em dispositivos antigos.

ANT (Android New API) e lint

O Android Studio inclui o analisador estático lint, que adverte sobre o uso de APIs acima de minSdkVersion. Se um método for chamado sem verificar SDK_INT, o lint o destaca como erro: "Call requires API level 34 (current min is 26)". Soluções: adicionar @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) ao método ou uma verificação if de SDK_INT. @TargetApi é uma anotação obsoleta, @RequiresApi é recomendado.

Tabela de correspondência entre API Level e versões do Android

A tabela de API Level é uma ferramenta de referência para o desenvolvedor. Conhecendo o API Level do dispositivo, é possível determinar a versão do Android e os recursos disponíveis. A tabela lista todas as principais versões do Android do API Level 1 (2008) ao API Level 36 (2025). Os nomes de código (Cupcake, Donut, Tiramisu, VanillaIceCream) são usados internamente no Google e no VERSION_CODES.

Tabela: API Levels limite para mudanças comportamentais

A tabela a seguir mostra os principais API Levels que introduzem mudanças comportamentais que quebram a compatibilidade retroativa ao aumentar targetSdk: