minSdkVersion: ce este, cum să alegi versiunea minimă de Android

Ce este minSdkVersion în Android?

minSdkVersion — un parametru întreg în build.gradle care stabilește nivelul minim API Android pentru instalarea aplicației. Dacă nivelul API al dispozitivului este sub valoarea specificată, PackageManager blochează instalarea, iar Google Play Store ascunde aplicația din rezultatele căutării pentru un astfel de dispozitiv. minSdkVersion se scrie în AndroidManifest.xml în etapa de compilare prin tagul <uses-sdk android:minSdkVersion> și se verifică la fiecare instalare.

Valoarea minSdkVersion este un compromis între acoperirea publicului și accesul la API-uri noi. Cu cât minSdk este mai mic, cu atât mai multe dispozitive pot instala aplicația, în special în regiunile în curs de dezvoltare unde smartphone-urile Android vechi sunt populare. Cu cât minSdk este mai mare, cu atât mai puțin cod de compatibilitate inversă este necesar și mai multe API-uri moderne sunt disponibile fără verificări la runtime. Android Jetpack și bibliotecile AndroidX oferă backporturi ale multor API-uri noi pe versiunile vechi de Android, permițând alegerea unui minSdk mai mic fără pierderea funcționalității.

minSdkVersion afectează toate etapele de dezvoltare: analiza statică (lint folosește minSdk pentru avertismente), compatibilitatea dependențelor (bibliotecile pot cere propriul minSdk), testarea (trebuie testat pe dispozitive cu minSdk) și Google Play Console (acoperirea publicului se calculează pe baza minSdk). Schimbarea minSdkVersion este una dintre cele mai responsabile decizii în configurarea proiectului, deoarece afectează codul, testele și baza de utilizatori.

Unde se specifică minSdkVersion

Build.gradle.kts (Kotlin DSL) — standardul modern în proiectele Android. Parametrul minSdk se setează în blocul defaultConfig la nivel de modul. Valoarea poate fi suprascrisă pentru diferite tipuri de compilare și arome de produs, permițând testarea pe API-uri mai mici fără a schimba valoarea principală.

// build.gradle.kts — configurarea de bază a 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"
    }

    // Suprascrierea minSdk pentru diferite flavor-uri
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

În exemplu minSdk = 26 corespunde Android 8.0 Oreo. Aceasta este o valoare populară în 2026: elimină doar ~15% dispozitive conform Android Studio Distribution Dashboard. compileSdk = 36 oferă acces la toate API-urile Android 16, iar targetSdk = 36 activează modificările comportamentale ale ultimei versiuni. Pentru compilările debug, minSdk poate fi redus pentru testarea pe emulatoare vechi.

Cum să alegi minSdkVersion: factori și strategie

Alegerea minSdkVersion — o decizie strategică bazată pe analiza publicului țintă, cerințelor API și ecosistemului de biblioteci. Nu există o singură valoare corectă pentru toate proiectele. În 2026, Android Studio recomandă minSdk = 26 (Android 8.0) ca nivel de bază pentru proiecte noi, dar pentru aplicațiile B2B sau soluțiile corporative sunt acceptabile valori mai mici sau mai mari.

Factori de alegere a minSdkVersion

Primul factor — Distribution Dashboard. Android Studio oferă statistici ale dispozitivelor active după nivelul API pe baza datelor Google Play, actualizate lunar. minSdkVersion trebuie să acopere cel puțin 90-95% din dispozitivele active ale pieței țintă. Pentru aplicații internaționale cu public în Africa și Asia de Sud-Est, minSdk ar trebui redus la 21 (Android 5.0) din cauza ponderii ridicate a dispozitivelor vechi.

Al doilea factor — cerințele dependențelor. Fiecare bibliotecă are propriul minSdkVersion specificat în manifestul său. Dacă biblioteca necesită minSdk 29, iar aplicația — minSdk 26, compilarea se va încheia cu eroare manifest merger. Bibliotecile moderne Google Play Services au minSdk 21, Firebase — minSdk 21, majoritatea bibliotecilor Jetpack — minSdk 21 sau 26, Compose BOM — minSdk 21. Pentru Compose pragul minim — API 21.

Al treilea factor — API-urile necesare. Dacă funcționalitatea cheie a aplicației necesită un API disponibil doar de la un anumit nivel (de exemplu, PhotoPicker — API 34, Predicted Navigation — API 35), aceasta poate justifica creșterea minSdk. Cu toate acestea, mai des se folosește o combinație de backporturi AndroidX (Activity Result API, NotificationCompat) și verificări la runtime pentru a păstra un minSdk scăzut.

Strategia de alegere pas cu pas

Pasul 1: deschideți Android Studio, File → New Project și uitați-vă la minSdk recomandat în asistent. Pasul 2: verificați Distribution Dashboard în Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Pasul 3: analizați dependențele proiectului — efectuați compilarea și rezolvați conflictele manifest merger. Pasul 4: evaluați care API-uri de nivel X sunt folosite efectiv fără backporturi. Pasul 5: setați minSdk ca valoare minimă care acoperă 90%+ din publicul țintă și este compatibilă cu toate dependențele.

Acoperirea dispozitivelor: distribuția nivelurilor API (2026)

Distribuția dispozitivelor după nivelul API — un indicator dinamic care se schimbă trimestrial. Conform Android Studio Distribution Dashboard pentru iunie 2026, aproximativ 85% din dispozitivele Android active rulează pe API 26 (Android 8.0) și superior, 72% — pe API 29 (Android 10) și superior, 55% — pe API 31 (Android 12) și superior. Piața chineză are propria statistică din cauza lipsei Google Play Services pe multe dispozitive Huawei.

Dispozitivele GMS (Google Mobile Services) se actualizează mai rapid: ponderea API 31+ pe ele atinge 68% datorită cerințelor obligatorii Google Play pentru producători. Dispozitivele non-GMS (Huawei, Honor, unele mărci chinezești) au o distribuție mai veche: ponderea API 31+ pe ele este de aproximativ 35%. Dacă aplicația este orientată spre piața internațională, bazați-vă pe statisticile globale. Dacă spre cea chineză — luați în considerare segmentul non-GMS.

Concluzie: pentru o aplicație internațională minSdk 26 acoperă 85% din dispozitive cu costuri minime de compatibilitate inversă. Pentru aplicații cu public în regiuni în curs de dezvoltare, minSdk 21 (97% acoperire) este justificat, dar va necesita mai mult cod pentru a lucra cu API-uri învechite. Pentru aplicațiile Enterprise cu un parc controlat de dispozitive, puteți seta minSdk 31 și scăpa complet de codul fallback.

Compatibilitate inversă: AndroidX, lint și @RequiresApi

Compatibilitatea inversă — principala dificultate la un minSdkVersion scăzut. AndroidX (fosta Support Library) oferă backporturi ale API-urilor moderne pe versiunile vechi de Android: AppCompatActivity pentru Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat și zeci de alte componente. Utilizarea echivalentelor AndroidX în locul API-urilor native — primul pas către compatibilitate.

lint (analizorul static Android Studio) scanează codul pentru apeluri API peste minSdkVersion. Dacă o metodă este marcată cu @RequiresApi cu un nivel API mai mare decât minSdk și este apelată fără verificare, lint evidențiază eroarea. Pentru a suprima avertismentul, folosiți adnotarea @SuppressLint("NewApi") pe metodă sau @RequiresApi(Build.VERSION_CODES.TIRAMISU) pe întreaga funcție. Verificările la runtime prin Build.VERSION.SDK_INT — mecanismul principal de apelare sigură a API-urilor noi pe dispozitive vechi.

// Exemplu de compatibilitate inversă: PhotoPicker (API 34+) și 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) — funcționează la orice nivel API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker disponibil doar de la API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Folosim PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (funcționează pe toate versiunile)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Această metodă nu poate fi apelată pe API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Clasa ImagePickerActivity demonstrează trei niveluri de compatibilitate inversă. Activity Result API din AndroidX funcționează la toate nivelurile API, deci pentru selectarea de bază a imaginii minSdk nu contează. PhotoPicker (ACTION_PICK_IMAGES) este disponibil doar de la API 34 și este apelat sub verificarea SDK_INT cu fallback pe GetContent. Metoda usePhotoPickerOnly este marcată cu @RequiresApi — lint nu va permite apelarea ei fără verificare. AppCompat din AndroidX adaptează automat tema, fragmentele și animațiile la versiunea sistemului de operare.

minSdkVersion în biblioteci și module

Bibliotecile (AAR, JAR) au, de asemenea, minSdkVersion specificat în manifestul lor. La conectarea bibliotecii, Gradle verifică compatibilitatea: dacă minSdk al bibliotecii este mai mare decât minSdk al aplicației, compilarea eșuează cu eroare. Pentru bibliotecile publice se recomandă specificarea celui mai mic minSdk posibil (21 în majoritatea cazurilor) pentru a nu limita consumatorii. Dacă biblioteca necesită API 29+, pierde ~28% din potențialii utilizatori.

Proiectele multi-modul pot avea minSdkVersion diferite pentru module diferite. De exemplu, modulul :core:network poate avea minSdk 26, iar modulul :feature:camera — minSdk 29 (din cauza CameraX cu cerințe specifice). Google Play cere ca minSdk al modulului principal :app să fie mai mic sau egal cu minSdk al tuturor modulelor dependente. În practică, toate modulele unei aplicații au de obicei același minSdk pentru simplificarea întreținerii.

// build.gradle.kts — modul bibliotecă cu minSdk scăzut
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Minim pentru acoperire maximă
        targetSdk = 36
    }
}

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

Modulul de bibliotecă cu minSdk = 21 este compatibil cu 97% din dispozitive și nu limitează consumatorii. Dacă biblioteca folosește API-uri peste 21, dezvoltatorul trebuie să adauge verificări la runtime sau să specifice @RequiresApi pe metodele corespunzătoare. AndroidX Core KTX (minSdk 21) oferă backporturi pentru Context, Bundle, Locale și alte clase sistemice, permițând bibliotecii să păstreze un minSdk scăzut.

Erori tipice la alegerea minSdkVersion

Erorile la alegerea minSdk pot costa mii de instalări sau săptămâni de dezvoltare suplimentară. Prima eroare tipică — copierea minSdk din șablonul proiectului fără a analiza Distribution Dashboard. Mulți dezvoltatori lasă minSdk = 21 din șablonul Android Studio, deși pentru publicul lor minSdk 26 ar fi suficient și ar reduce numărul de verificări SDK_INT în cod.

A doua eroare — minSdk prea mare fără a lua în considerare piața. Dacă setați minSdk = 31 (Android 12) pentru o aplicație internațională, pierdeți ~45% din dispozitive. Pentru un startup sau o aplicație cu public de masă, aceasta este o catastrofă. Verificați întotdeauna Distribution Dashboard înainte de a crește minSdk și folosiți testarea A/B în Google Play Console dacă nu sunteți sigur.

A treia eroare — ignorarea minSdk al dependențelor. La adăugarea unei biblioteci noi, verificați minSdk-ul acesteia în documentație sau fișierul POM. Firebase ML Kit necesită minSdk 21, unele biblioteci personalizate pentru cameră necesită minSdk 29. Dacă manifest merger eșuează în producție din cauza unei biblioteci noi, remedierea poate dura zile.

// Exemplu: verificarea compatibilității API la runtime
fun checkFeatureAvailability(): Boolean {
    // Eroare tipică — apel API fără verificarea SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — folosim PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — folosim MediaStore
            true
        }
        else -> {
            // API < 29 — folosim ACTION_GET_CONTENT
            true
        }
    }
}

Arhitectura corectă a verificărilor nivelului API — when cu intervale care acoperă toate valorile posibile de la minSdk la compileSdk. Regula cheie: orice apel API de nivel X trebuie protejat cu verificarea VERSION.SDK_INT pentru toate dispozitivele cu nivel API de la minSdk la X. lint ajută la detectarea apelurilor neverificate, dar nu poate garanta acoperirea completă pentru codul dinamic.