Propriedades da versão do SDK do Android

Os apps Android podem definir várias propriedades da versão do SDK no arquivo build.gradle. A documentação do Android build.gradle explica o que essas propriedades significam para o aplicativo em geral. Este documento explica como essas propriedades afetam os builds do NDK.

compileSdkVersion

Essa propriedade não tem efeito nos builds do NDK. A disponibilidade da API para o NDK é regida por minSdkVersion. Isso ocorre porque os símbolos C++ são resolvidos prontamente no tempo de carregamento da biblioteca em vez de serem resolvidos lentamente quando são chamados pela primeira vez (como em Java). O uso de símbolos que não estão disponíveis na minSdkVersion vai fazer com que a biblioteca não carregue em versões do SO que não têm a API mais recente, independentemente de essas APIs serem chamadas ou não.

Para um novo app, escolha a versão mais recente disponível. Para um app já existente, atualize para a última versão quando for conveniente.

targetSdkVersion

Assim como o Java, a targetSdkVersion do app pode mudar o comportamento do ambiente de execução do código nativo. As mudanças de comportamento no sistema são, quando possível, aplicadas apenas a apps com uma targetSdkVersion maior ou igual à versão do SO que introduziu a mudança.

Para um novo app, escolha a versão mais recente disponível. Para um app já existente, atualize para a última versão quando for conveniente (depois de atualizar a compileSdkVersion).

Embora os desenvolvedores geralmente conheçam a targetSdkVersion do app deles, essa API é útil para os desenvolvedores de bibliotecas que não sabem qual targetSdkVersion os usuários vão escolher.

No tempo de execução, é possível receber a targetSdkVersion usada por um aplicativo chamando android_get_application_target_sdk_version(). Essa API está disponível na API de nível 24 e mais recentes. Essa função tem a seguinte assinatura:

/**
 * Returns the `targetSdkVersion` of the caller, or `__ANDROID_API_FUTURE__` if
 * there is no known target SDK version (for code not running in the context of
 * an app).
 *
 * The returned values correspond to the named constants in `<android/api-level.h>`,
 * and is equivalent to the AndroidManifest.xml `targetSdkVersion`.
 *
 * See also android_get_device_api_level().
 *
 * Available since API level 24.
 */
int android_get_application_target_sdk_version() __INTRODUCED_IN(24);

Outras mudanças de comportamento podem depender do nível da API do dispositivo. Para ver o nível da API do dispositivo em que seu aplicativo está sendo executado, chame android_get_device_api_level(). Essa função tem a seguinte assinatura:

/**
 * Returns the API level of the device we're actually running on, or -1 on failure.
 * The returned values correspond to the named constants in `<android/api-level.h>`,
 * and is equivalent to the Java `Build.VERSION.SDK_INT` API.
 *
 * See also android_get_application_target_sdk_version().
 */
int android_get_device_api_level();

maxSdkVersion

Essa propriedade não tem efeito nos builds do NDK.

minSdkVersion

A minSdkVersion definida no arquivo build.gradle determina quais APIs estão disponíveis no tempo de build e a versão mínima do SO compatível com seu código. Consulte compileSdkVersion para entender por que isso é diferente nos builds Java.

A minSdkVersion é usada pelo NDK para determinar quais recursos podem ser utilizados ao compilar seu código. Por exemplo, essa propriedade determina quais recursos FORTIFY (link em inglês) são usados na libc e também pode permitir melhorias de performance ou de tamanho, como hashes GNU ou RELR, para binários que não são compatíveis com versões mais antigas do Android. Mesmo que você não use nenhuma API nova, essa propriedade ainda rege a versão mínima do sistema operacional que pode ser usada com o código.

Aviso: o app pode funcionar em dispositivos mais antigos, mesmo que as bibliotecas nativas sejam criadas com uma minSdkVersion mais recente. No entanto, não confie nessa possibilidade. Não há garantias de que ele funcione, e pode não funcionar em outras versões do NDK, versões do SO ou dispositivos individuais.

Para um novo app, consulte os dados de distribuição de usuários no assistente de novo projeto do Android Studio ou em apilevels.com (link em inglês). Faça sua escolha de maneira a equilibrar possíveis custos de participação de mercado e de manutenção. Quanto menor a minSdkVersion, mais tempo você vai passar contornando bugs antigos e adicionando comportamentos substitutos para recursos ainda não implementados.

Para um app já existente, aumente a minSdkVersion sempre que os níveis antigos da API não compensarem mais os custos de manutenção ou diminua se essa for uma demanda dos usuários e se os novos custos de manutenção compensarem. O Play Console tem métricas específicas para a distribuição de usuários do seu app.

Observação: o NDK tem a própria minSdkVersion definida em <NDK>/meta/platforms.json. Esse é o nível de API mais baixo com suporte do NDK. Não defina a minSdkVersion do app como abaixo dessa. O Google Play pode permitir que o app seja instalado em dispositivos mais antigos, mas é possível que o código do NDK não funcione.

A minSdkVersion do aplicativo é disponibilizada para o pré-processador pela macro __ANDROID_MIN_SDK_VERSION__. A __ANDROID_API__ legada é idêntica, mas prefira a citada anteriormente porque o significado é mais claro. Essa macro é definida automaticamente pelo Clang, então nenhum cabeçalho precisa ser incluído para fazer uso dela. Para builds do NDK, essa macro sempre é definida.