targetSdkVersion: Conceitos-chave, Behavioural Changes e Google Play

O que é targetSdkVersion no Android?

targetSdkVersion é um parâmetro inteiro no build.gradle que declara o API Level contra o qual o app foi testado. O sistema Android usa este parâmetro para decidir quais behavioural changes aplicar ao aplicativo em tempo de execução. Se targetSdkVersion = 33, o Android aplica todos os behavioural changes introduzidos até API 33 inclusive, mas não aplica as alterações da API 34+. Se targetSdkVersion = 34 — as alterações até API 34 são aplicadas, e assim por diante.

A principal diferença entre targetSdkVersion e minSdkVersion é o mecanismo de ação. minSdk é verificado uma vez durante a instalação e bloqueia a instalação se a condição não for atendida. targetSdkVersion afeta o comportamento em tempo de execução do sistema em cada dispositivo, independentemente da versão do Android em que o app está sendo executado. O mesmo app com targetSdk 31 se comportará de forma diferente no Android 13, 14 e 15, porque os behavioural changes acima de 31 estão desativados.

O mecanismo de targetSdkVersion é uma ferramenta de compatibilidade reversa incorporada ao Android. Sem ele, cada atualização do SO quebraria milhares de aplicativos antigos. O Google introduziu este mecanismo no Android 2.1 (API Level 7) e desde então o utiliza como forma padrão de introduzir novas regras de segurança, privacidade e gerenciamento de recursos sem quebrar os aplicativos existentes.

// build.gradle.kts — targetSdkVersion em defaultConfig
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

// Verificando targetSdk atual no código
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion contém o targetSdk do aplicativo
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

No exemplo, targetSdk = 36 ativa todos os behavioural changes do Android 16. O código verifica targetSdkVersion através de context.applicationInfo.targetSdkVersion — isso permite determinar dinamicamente qual modo de compatibilidade está ativado. A função auxiliar é útil para bibliotecas que precisam se adaptar ao targetSdk do aplicativo chamador.

Behavioural Changes: como o targetSdk afeta o aplicativo

Behavioural changes são modificações no comportamento do sistema Android que só se aplicam a aplicativos com targetSdkVersion >= um determinado API Level. Cada novo lançamento principal do Android introduz behavioural changes, e se um aplicativo não atualizar o targetSdk, essas alterações não entram em vigor. Este mecanismo permite que os desenvolvedores atualizem seu aplicativo no seu próprio ritmo, em vez de sincronizadamente com o lançamento de um novo SO.

Scoped Storage (API 29) é um dos behavioural changes mais significativos. Aplicativos com targetSdk 29+ não podem obter acesso File direto aos diretórios compartilhados Pictures, Downloads, Music, Documents. Em vez disso, o MediaStore é usado para multimídia, SAF (Storage Access Framework) para arquivos arbitrários e getExternalFilesDir() para armazenamento privado. Aplicativos antigos com targetSdk 28 ou inferior continuam funcionando com o legado Full Storage Access, mas isso cria um risco de segurança.

POST_NOTIFICATIONS (API 33) é uma permissão em tempo de execução para enviar notificações. Aplicativos com targetSdk 33+ devem solicitar a permissão Manifest.permission.POST_NOTIFICATIONS do usuário através do diálogo padrão. Se a permissão não for concedida, NotificationManager.silent() não mostra notificações ao usuário. No Android 13+ sem esta permissão, notificações push e notificações locais simplesmente não são exibidas, o que pode reduzir significativamente o engajamento do usuário.

Como verificar o targetSdk atual

O valor de targetSdkVersion pode ser obtido via ADB: o comando adb shell dumpsys package com.example.myapp | grep targetSdk exibe targetSdk=34. Em código, context.getApplicationInfo().targetSdkVersion retorna um número inteiro. Para análise, é útil registrar targetSdk junto com android.os.Build.VERSION.SDK_INT para entender quais behavioural changes estão realmente ativos em cada sessão.

Requisitos do Google Play para targetSdkVersion (2026)

Google Play estabelece requisitos obrigatórios de targetSdkVersion para todos os aplicativos publicados. Desde agosto de 2024, o targetSdk mínimo = 33 (Android 13). Desde agosto de 2025, targetSdk = 34. Espera-se que a partir de agosto de 2026, o Google exija targetSdk = 35 (Android 15). Novos aplicativos e atualizações de aplicativos existentes devem cumprir estes requisitos, caso contrário a console bloqueia a publicação. Esta é uma política do Google Play, não uma restrição do Android Runtime: um aplicativo com targetSdk 34 pode funcionar no Android 16, mas não pode ser publicado na Play Store.

Android App Bundle (AAB) é o formato de publicação obrigatório desde agosto de 2021. APK não é mais aceito no Google Play (exceto para aplicativos com mais de 150 MB e alguns projetos legados). O formato AAB permite que o Google gere APKs otimizados para cada API Level e densidade de tela, reduzindo o tamanho do download em 15-30%. Para verificar targetSdk, o Google Play analisa o manifesto AAB e emite um erro com o valor mínimo exigido se não estiver em conformidade.

O Google Play Console verifica targetSdkVersion não apenas ao enviar um novo AAB, mas também ao atualizar um aplicativo existente. Se seu aplicativo tiver targetSdk 33 e o Google elevar o limite mínimo para 34 — você não poderá lançar nenhuma atualização até aumentar o targetSdk. Para aplicativos que não são atualizados há muito tempo, o Google Play pode removê-los automaticamente da publicação (unpublish).

Como atualizar targetSdkVersion sem erros

Atualizar targetSdkVersion não é apenas mudar um número no build.gradle. Cada behavioural change pode quebrar a funcionalidade existente se o código não for preparado com antecedência. Recomenda-se começar a preparação 3-6 meses antes do prazo do Google Play, especialmente se o aplicativo for grande e usar muitas APIs do sistema.

Processo passo a passo: Passo 1 — estude os behavioural changes para o novo API Level na documentação do Android Developers (página "Behavioural Changes by API Level"). Passo 2 — crie um branch targetSdk-update e altere targetSdk para o novo valor. Passo 3 — execute o aplicativo em um emulador ou dispositivo com o novo API Level e verifique cada funcionalidade relacionada às alterações. Passo 4 — corrija erros: adicione permissões, altere o manuseio de arquivos, atualize o manifesto.

Passo 5 — teste em dispositivos antigos. Aumentar targetSdk não afeta dispositivos com API Level abaixo do novo targetSdk, mas os behavioural changes se aplicam a todos os dispositivos com API Level >= targetSdk. Se você aumentou targetSdk de 33 para 34, em dispositivos com API 34+ os behavioural changes da API 34 serão ativados. Em dispositivos com API 33 nada mudará.

// Preparação para targetSdk 35: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox restringe Advertising ID a partir da API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identificador indisponível, use MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Verificação: quais behavioural changes estão ativos
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

A classe AdsManager demonstra a preparação para o Privacy Sandbox (API 35). O Advertising ID fica indisponível a partir da API 35 com targetSdk 35+. A função getActiveChanges mostra o padrão correto para verificar behavioural changes: é necessário verificar tanto o SDK_INT do dispositivo quanto o targetSdk do aplicativo. Somente quando ambas as condições coincidem a alteração está realmente ativa.

Android 15 (API 35): principais behavioural changes

Android 15 (API 35, Vanilla Ice Cream) introduz vários behavioural changes críticos que os desenvolvedores devem considerar ao atualizar targetSdk para 35. Primeiro — Privacy Sandbox for Android. Esta é a iniciativa do Google para substituir o Advertising ID por APIs mais privadas: Topics API (interesses do usuário), Protected Audience (remarketing) e Attribution Reporting (conversões). A partir da API 35, o Advertising ID deixa de ser um identificador estável e pode retornar um valor nulo.

A segunda alteração — Foreground Service Types (API 34, continuada na API 35). A partir da API 34, cada aplicativo com targetSdk 34+ deve especificar o tipo de serviço em primeiro plano no manifesto: dataSync, systemExempted, shortService, location, mediaPlayback e outros. Sem isso, o sistema gera ForegroundServiceTypeNotAllowedException. Na API 35, um novo tipo health foi adicionado e a validação dos tipos existentes foi endurecida. Todos os serviços em primeiro plano devem ser revisados.

A terceira alteração — restrição no SCHEDULE_EXACT_ALARM. A partir da API 35, aplicativos com targetSdk 35+ não podem usar SCHEDULE_EXACT_ALARM sem permissão explícita do usuário. O sistema mostra um diálogo e o usuário deve aprovar o agendamento exato. Para alarmes e temporizadores, isso significa uma etapa adicional na UX. Uma alternativa é usar alarmes inexatos com uma margem de 10 minutos.

// Android 15 (API 35): verificação de SCHEDULE_EXACT_ALARM
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: permissão do usuário necessária
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Abaixo de API 35 — alarmes exatos disponíveis sem permissão
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox e a restrição de alarmes são os dois behavioural changes mais críticos da API 35. SDKs de anúncios precisarão migrar para Topics API e Attribution Reporting. Para aplicativos com alarmes e lembretes — adaptação de UX para o diálogo de permissão. Ignorar essas alterações levará a falhas do aplicativo em tempo de execução no Android 15 ou a monetização de anúncios quebrada.

Diferença entre targetSdk e compileSdk

A diferença entre targetSdkVersion e compileSdkVersion é uma das fontes mais comuns de confusão entre desenvolvedores Android. compileSdkVersion é a versão do SDK contra a qual o código é compilado. Ela determina quais APIs estão disponíveis em tempo de compilação, mas não afeta o comportamento em tempo de execução. targetSdkVersion é a versão contra a qual o aplicativo é testado — determina quais behavioural changes se aplicam em tempo de execução. compileSdk pode e deve ser maior ou igual a targetSdk.

A regra é simples: compileSdk >= targetSdk >= minSdk. compileSdk geralmente é igual ao último API Level estável (em 2026 — 36). targetSdk deve ser o mais alto possível entre as versões que você testou. minSdk deve ser o mais baixo possível para alcance máximo. Aumentar compileSdk não requer testar behavioural changes — apenas abre acesso a novas APIs para o compilador. Aumentar targetSdk requer um ciclo completo de testes de todos os behavioural changes.

Na prática: se você quiser usar uma nova API do Android 16 (API 36) mas ainda não testou os behavioural changes da API 36, defina compileSdk = 36, targetSdk = 35. O código será compilado com as novas APIs, mas os behavioural changes da API 36 não serão aplicados. Assim que testar todas as alterações — aumente targetSdk para 36.