compileSdkVersion: fundamentos, novas APIs e configuração no Gradle

O que é compileSdkVersion no Android?

compileSdkVersion é um parâmetro inteiro no build.gradle que especifica contra qual versão do Android SDK compilar o código. Quando você escreve código usando classes de android.* ou androidx.*, o compilador as verifica com as APIs disponíveis na versão compileSdk especificada. Se um método foi introduzido na API 36 e compileSdk = 35, o código não será compilado. Se compileSdk = 36, o código será compilado, mas chamar esse método em um dispositivo com API 35 sem uma verificação causará uma falha.

compileSdkVersion é carregado da plataforma Android SDK instalada via SDK Manager no Android Studio. Cada nível de API tem sua própria plataforma: android-21, android-29, android-34, android-35, android-36. A plataforma contém android.jar — um conjunto de classes, métodos e constantes que o compilador Kotlin/Java usa. Se a plataforma não estiver instalada, o Gradle a baixará automaticamente via sdkmanager na primeira compilação.

AGP (Android Gradle Plugin) versão 8.7+ recomenda especificar compileSdk como um inteiro via compileSdk = 36 no Kotlin DSL, sem o prefixo android-. compileSdk também pode ser definido via compileSdkVersion 36 no Groovy DSL ou compileSdkPreview para versões prévias do SDK (developer previews). compileSdkPreview é usado para testar níveis de API futuros antes do lançamento oficial.

// build.gradle.kts — configuração do compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — último nível de API estável (Android 16)
    compileSdk = 36

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

// Alternativamente: compileSdkPreview para versões de prévia
// compileSdkPreview = "Baklava"

No exemplo, compileSdk = 36 fornece acesso a todas as APIs do Android 16 (Baklava). A plataforma Android SDK 36 deve estar instalada no SDK Manager. compileSdkPreview com o nome "Baklava" pode ser usado para testar APIs instáveis antes do lançamento oficial da plataforma. Após o lançamento, a prévia é substituída pelo compileSdk = 36 estável.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Três parâmetros de nível de API no build.gradle — compileSdkVersion, targetSdkVersion e minSdkVersion — são frequentemente confundidos. Cada um é responsável por um aspecto diferente de compatibilidade, e seus valores devem seguir a regra compileSdk >= targetSdk >= minSdk. minSdk é o limite inferior: dispositivos abaixo dele não verão o aplicativo. targetSdk é o ponto de teste: as alterações comportamentais são ativadas até este nível. compileSdk é o teto: APIs acima deste nível ficam indisponíveis para o compilador.

Regra prática essencial: compileSdk pode ser aumentado sem qualquer teste em dispositivos. Esta é uma operação segura que simplesmente fornece ao compilador uma nova versão do android.jar. O único risco são APIs obsoletas que podem ser removidas na nova versão da plataforma, mas isso é detectado em tempo de compilação e facilmente corrigido. Aumentar targetSdk, por outro lado, requer um ciclo completo de QA.

Por que compileSdk pode ser maior que targetSdk? Imagine que o Android 16 (API 36) foi lançado com novas APIs que você deseja usar no código, mas você ainda não testou as alterações comportamentais da API 36. Você define compileSdk = 36 (novas APIs disponíveis), targetSdk = 35 (alterações comportamentais da API 36 desativadas). O código será compilado, usará novos métodos sob verificações SDK_INT, e as alterações comportamentais da API 36 não quebrarão o aplicativo porque targetSdk = 35.

Exemplos de combinações corretas

compileSdk = 36, targetSdk = 36, minSdk = 26 — compatibilidade total com as últimas APIs e alterações comportamentais, cobrindo 85% dos dispositivos. compileSdk = 36, targetSdk = 34, minSdk = 26 — novas APIs disponíveis, alterações comportamentais apenas até API 34. compileSdk = 35, targetSdk = 36 — incorreto: compileSdk é menor que targetSdk, API 36 indisponível enquanto as alterações comportamentais da 36 estão ativas.

Como atualizar compileSdkVersion: guia passo a passo

Atualizar compileSdkVersion é uma das operações mais simples e seguras em um projeto Android. Ao contrário de targetSdk, não requer testes extensivos de alterações comportamentais. No entanto, existem algumas etapas a seguir para evitar erros de compilação e avisos de obsolescência.

Etapa 1 — instale a nova plataforma via SDK Manager no Android Studio: Tools → SDK Manager → SDK Platforms → selecione o novo nível de API. Se você não instalar a plataforma, o Gradle tentará baixá-la automaticamente, mas isso pode atrasar a primeira compilação. Etapa 2 — altere compileSdk no build.gradle para o novo valor. Etapa 3 — compile (Build → Make Project) e corrija quaisquer erros de compilação.

Etapa 4 — verifique APIs obsoletas. Após atualizar compileSdk, alguns métodos podem ser marcados como @Deprecated com a nota "removed in API X". O Android Studio os destaca com tachado e exibe um aviso. Substitua chamadas obsoletas por novas alternativas. Se a alternativa exigir um nível de API superior a minSdk, adicione uma verificação em tempo de execução. Etapa 5 — verifique as dependências: algumas bibliotecas podem exigir uma versão específica de compileSdk. AGP 8.7+ recomenda compileSdk = 36.

// Após atualizar compileSdk: substituir APIs obsoletas
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ANTES: método obsoleto (pode ser removido na nova API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Pode ficar obsoleto na API 36
    }

    // DEPOIS: nova alternativa (se disponível)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nova API do compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Exemplo de nova API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

A classe CompileSdkMigration mostra o padrão de migração correto. O método antigo memoryClass pode ser removido na nova API — o compilador emitirá um erro. A nova alternativa getMemoryClassSafe está disponível apenas na API 36+, portanto é chamada sob uma verificação SDK_INT >= BAKLAVA. Para dispositivos antigos, um fallback com @Suppress("DEPRECATION") é usado.

Trabalhando com novas APIs: verificações condicionais e fallback

Novas APIs disponibilizadas pela atualização de compileSdkVersion não podem ser chamadas diretamente se minSdkVersion for inferior a esse nível de API. Sem uma verificação em tempo de execução, o aplicativo falhará com AbstractMethodError, NoSuchMethodError ou VerifyError em dispositivos antigos. O mecanismo de proteção principal é verificar Build.VERSION.SDK_INT, chamar a nova API somente quando o nível de API for suficiente e fornecer um fallback para versões antigas.

AndroidX fornece backports para muitas novas APIs, permitindo o uso de métodos modernos mesmo com um compileSdk baixo. Por exemplo, a API Activity Result de androidx.activity:activity-ktx:1.9.3 funciona em todas as versões do Android a partir da API 14. NotificationCompat do AndroidX permite notificações modernas em APIs antigas. PhotoPicker está disponível via ActivityResultContracts.PickVisualMedia a partir da API 34+.

// Chamada segura de nova API com compileSdk 36 e minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: novo método para trabalhar com cor
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nova API do compileSdk 36 — requer API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: formatação manual para APIs antigas
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: nenhum backport necessário — verificação SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Uso em Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

A classe NewApiHelper demonstra a chamada segura da nova API Color.toArgbHexString (API 36 hipotética) com formatação de fallback para versões antigas. O princípio-chave: compileSdk dá acesso para chamar novos métodos no código, mas uma verificação SDK_INT em tempo de execução protege contra falhas em dispositivos antigos. Sem uma verificação SDK_INT, um aplicativo com minSdk 26 e compileSdk 36 falhará no Android 8-15.

AGP (Android Gradle Plugin) e compileSdkVersion

Android Gradle Plugin (AGP) é a ferramenta de compilação principal para aplicativos Android. Cada versão do AGP suporta uma faixa específica de compileSdkVersion. AGP 8.7.x (lançado em 2026) requer compileSdk >= 34 e recomenda compileSdk = 36. AGP 8.5.x suporta compileSdk 33-35. Se compileSdk estiver abaixo do mínimo para AGP, a compilação falhará com o erro: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) também está vinculado ao compileSdkVersion. Se seu projeto usa código nativo em C/C++ via NDK, compileSdk determina a versão dos arquivos de cabeçalho e bibliotecas. NDK r27+ recomenda compileSdk 36. Para bibliotecas com arquivos .so, compileSdk afeta o nível de API mínimo para código nativo via APP_MIN_SDK_VERSION em Application.mk.

Gradle (7.6+) e Kotlin (2.0+) também afetam a compatibilidade com compileSdk. AGP 8.7+ requer Gradle 8.9+ e Kotlin 2.0+. Ao atualizar compileSdk, recomenda-se atualizar AGP, Gradle e Kotlin para as versões estáveis mais recentes. Verifique a compatibilidade na tabela oficial de compatibilidade do Android Gradle Plugin.

Problemas comuns ao atualizar compileSdk

Problemas ao atualizar compileSdkVersion se dividem em três categorias: erros de compilação, avisos de obsolescência e incompatibilidades em tempo de execução. Erros de compilação — métodos são removidos da API e o código não compila. Avisos de obsolescência — métodos são marcados como @Deprecated, o código compila com avisos. Incompatibilidades em tempo de execução — novas APIs são necessárias para certa funcionalidade e causam erros se o nível de API no dispositivo for insuficiente.

O primeiro problema comum — "Cannot resolve symbol X". Isso significa que uma classe ou método foi removido da API pública na nova versão do SDK. Solução: encontre uma alternativa na nova plataforma ou use um equivalente do AndroidX. Por exemplo, a classe AsyncTaskLoader foi obsoleta na API 28 e removida da API pública em versões mais recentes. Alternativas incluem Kotlin Coroutines ou WorkManager.

O segundo problema — mudança de assinatura de método. Na nova versão da API, um método pode ter alterado o número ou tipo de seus parâmetros. O compilador Kotlin/Java emite um erro: "None of the following functions can be called with the arguments supplied". Solução: atualize a chamada do método para corresponder à nova assinatura ou adicione uma verificação SDK_INT com a chamada da assinatura antiga para dispositivos antigos.

// Resolver problemas ao atualizar compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problema: método hasSystemFeature mudou a assinatura na API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nova assinatura: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Assinatura antiga: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problema: classe removida, use equivalente AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Em vez de android.app.FragmentManager (removido) use
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

A classe CompileSdkProblemFixer resolve problemas comuns: a assinatura alterada de hasSystemFeature (mudança hipotética na API 36) é tratada por meio de uma verificação SDK_INT chamando a versão correta do método. A classe removida android.app.FragmentManager é substituída pelo equivalente AndroidX. Para chamadas antigas onde não há alternativa, @Suppress("DEPRECATION") é usado com um comentário explicando o motivo da manutenção.