API Level: τι είναι, εκδόσεις API και targetSdk

Τι είναι το API Level Android;

API Level Android είναι ένα ακέραιο αναγνωριστικό που εκχωρείται σε κάθε δημόσια έκδοση του Android Framework API. Η πρώτη έκδοση Android 1.0 είχε 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. Κάθε νέο API Level μπορεί να προσθέσει νέες κλάσεις, μεθόδους, σταθερές, δικαιώματα και να αλλάξει τη συμπεριφορά των υπαρχόντων.

Το API Level δεν αυξάνεται αυστηρά κατά 1 με κάθε έκδοση. Για παράδειγμα, το Android 4.4W (Wear) έχει API 20, ενώ το Android 5.0 — API 21. Τα κενά σχετίζονται με εσωτερικές επαναλήψεις και συσκευές Wear OS. Για τον προγραμματιστή είναι σημαντικό να γνωρίζει όχι το όνομα της έκδοσης (KitKat, Lollipop, Tiramisu), αλλά το API Level της — αυτό χρησιμοποιείται στον κώδικα για ελέγχους συμβατότητας.

Ο βασικός σκοπός του API Level είναι η προς τα πίσω συμβατότητα. Μια εφαρμογή μεταγλωττισμένη για API 34 μπορεί να λειτουργήσει σε συσκευές με API 34 και χαμηλότερο (αν δεν χρησιμοποιεί νέα API χωρίς έλεγχο). Το Android Runtime (ART) ελέγχει τις κλήσεις API σε επίπεδο συστήματος και εφαρμόζει αλλαγές συμπεριφοράς ανάλογα με το targetSdkVersion της εφαρμογής.

Πώς το Android χειρίζεται το API Level

Κατά την εγκατάσταση μιας εφαρμογής, το PackageManager ελέγχει αν το API Level της συσκευής >= minSdkVersion από το AndroidManifest.xml. Εάν η συνθήκη δεν ικανοποιείται — η εγκατάσταση αποκλείεται με το μήνυμα "App not installed". Κατά τη διάρκεια εκτέλεσης, το Android Runtime παρακολουθεί κλήσεις API που απαιτούν υψηλότερο API Level και δημιουργεί NoSuchMethodError ή UnsatisfiedLinkError εάν η μέθοδος δεν υπάρχει στην τρέχουσα έκδοση.

minSdk, targetSdk, compileSdk: διαφορές και ρόλος κάθε παραμέτρου

Στο αρχείο build.gradle (Module: app), ο προγραμματιστής καθορίζει τρεις παραμέτρους API Level: minSdkVersion, targetSdkVersion και compileSdkVersion. Η σύγχυσή τους είναι ένα από τα πιο συνηθισμένα λάθη αρχάριων προγραμματιστών Android. Κάθε παράμετρος είναι υπεύθυνη για μια διαφορετική πτυχή της συμβατότητας και οι τιμές τους πρέπει να είναι συνεπείς.

minSdkVersion

minSdkVersion είναι το ελάχιστο API Level στο οποίο η εφαρμογή μπορεί να εγκατασταθεί και να εκτελεστεί. Συσκευές με API Level χαμηλότερο από το minSdk δεν βλέπουν την εφαρμογή στο Google Play και δεν μπορούν να την εγκαταστήσουν. Η τιμή επιλέγεται με βάση το κοινό-στόχο: minSdk 21 (Android 5.0) καλύπτει το 97% των συσκευών, minSdk 26 (Android 8.0) — περίπου 85%, minSdk 31 (Android 12) — περίπου 55% (δεδομένα από το Android Studio Distribution Dashboard, 2026). Όσο χαμηλότερο είναι το minSdk, τόσο μεγαλύτερη είναι η κάλυψη, αλλά τόσο περισσότερος κώδικας προς τα πίσω συμβατότητας απαιτείται.

targetSdkVersion

targetSdkVersion είναι το API Level στο οποίο δοκιμάστηκε η εφαρμογή. Το Android χρησιμοποιεί το targetSdk για να εφαρμόσει αλλαγές συμπεριφοράς: εάν η εφαρμογή καθορίζει targetSdk 33, το σύστημα ενεργοποιεί όλες τις αλλαγές συμπεριφοράς που εισήχθησαν στο API 33. Εάν το targetSdk είναι 31, το σύστημα δεν εφαρμόζει αλλαγές API 32-33, διατηρώντας τη συμβατότητα με παλιά συμπεριφορά. Αυτή είναι η πιο σημαντική παράμετρος για την ασφάλεια: το Google Play απαιτεί το targetSdk να μην είναι παλαιότερο του 1 έτους από το τρέχον API Level.

compileSdkVersion

compileSdkVersion είναι η έκδοση του Android SDK στην οποία μεταγλωττίζεται ο κώδικας. Καθορίζει ποια API είναι διαθέσιμα κατά τη μεταγλώττιση. Το compileSdk πρέπει να είναι >= targetSdk και, ιδανικά, ίσο με το τελευταίο σταθερό API Level. Η αύξηση του compileSdk δεν επηρεάζει τη συμπεριφορά κατά την εκτέλεση — μόνο τη διαθεσιμότητα νέων API για τον μεταγλωττιστή. Μετά την αύξηση του compileSdk, πρέπει να ελέγξετε τον κώδικα για παρωχημένα API και νέες απαιτήσεις δικαιωμάτων.

// build.gradle.kts — παράδειγμα διαμόρφωσης 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")
}

Στο παράδειγμα build.gradle.kts, compileSdk = 36 (το νεότερο τη στιγμή της γραφής), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 παρέχει πρόσβαση σε όλα τα API του Android 16. targetSdk 36 ενεργοποιεί όλες τις αλλαγές συμπεριφοράς του Android 16. minSdk 26 καλύπτει ~85% των συσκευών. Τα AndroidX Activity KTX και AppCompat παρέχουν προς τα πίσω συμβατότητα για τμήματα και θέματα.

AndroidManifest.xml

Οι παράμετροι minSdk και targetSdk μπορούν επίσης να καθοριστούν στο AndroidManifest.xml, αλλά τα σύγχρονα έργα χρησιμοποιούν build.gradle — οι τιμές από το Gradle παρακάμπτουν το manifest. Στο manifest, μπορεί να είναι χρήσιμο να καθορίσετε για βιβλιοθήκες και ενότητες που δεν χρησιμοποιούν διαμόρφωση build Gradle.

Αλλαγές συμπεριφοράς: πώς το targetSdk επηρεάζει τη συμπεριφορά της εφαρμογής

Αλλαγές συμπεριφοράς είναι τροποποιήσεις στον τρόπο λειτουργίας του συστήματος Android που εφαρμόζονται μόνο σε εφαρμογές με targetSdk >= ένα συγκεκριμένο API Level. Κάθε νέα έκδοση Android εισάγει αλλαγές συμπεριφοράς που μπορούν να σπάσουν υπάρχουσες εφαρμογές εάν δεν ενημερωθούν. Αυτός είναι ένας βασικός μηχανισμός ασφαλείας του Android: οι παλιές εφαρμογές συνεχίζουν να λειτουργούν όπως πριν, οι νέες ακολουθούν τους τρέχοντες κανόνες.

Κύριες αλλαγές συμπεριφοράς ανά έκδοση

Android 10 (API 29) — Scoped Storage: εφαρμογές με targetSdk 29+ δεν έχουν άμεση πρόσβαση στο κοινόχρηστο σύστημα αρχείων, μόνο μέσω MediaStore, SAF ή δικής τους αποθήκευσης. Android 11 (API 30) — Package Visibility: φίλτρο πακέτων, οι εφαρμογές βλέπουν μόνο εγκατεστημένα πακέτα με τα οποία αλληλεπιδρούν. Android 12 (API 31) — Foreground Service Notification: όλες οι υπηρεσίες προσκηνίου υποχρεούνται να εμφανίζουν ειδοποίηση εντός 10 δευτερολέπτων από την εκκίνηση. Android 13 (API 33) — POST_NOTIFICATIONS: δικαίωμα χρόνου εκτέλεσης για ειδοποιήσεις push. Android 14 (API 34) — Foreground Service Types: υποχρεωτική δήλωση τύπου υπηρεσίας προσκηνίου στο manifest.

// Χειρισμός αλλαγών συμπεριφοράς 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) {
        // Το δικαίωμα POST_NOTIFICATIONS λειτουργεί μόνο με API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Κάτω από το API 33 δεν απαιτείται δικαίωμα
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Το δικαίωμα έχει ήδη δοθεί, μπορούν να σταλούν ειδοποιήσεις
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Εμφάνιση εξήγησης γιατί χρειάζεται το δικαίωμα
                activity.showRationale()
            }

            else -> {
                // Αίτηση δικαιώματος
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Δημιουργία και εμφάνιση ειδοποίησης
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Ειδοποίηση")
            .setContentText("Νέο μήνυμα")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Καταχώρηση requestPermissionLauncher στο Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Το δικαίωμα δόθηκε
        }
    }

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

Παράδειγμα χειρισμού POST_NOTIFICATIONS σε Kotlin: έλεγχος Build.VERSION.SDK_INT >= TIRAMISU, αίτηση δικαιώματος χρόνου εκτέλεσης μέσω ActivityResultContracts.RequestPermission, χειρισμός αποτελέσματος σε callback. Χωρίς αυτό το δικαίωμα, μια εφαρμογή με targetSdk 33+ δεν μπορεί να εμφανίζει ειδοποιήσεις push. Κάτω από το API 33 δεν απαιτείται δικαίωμα — ο κώδικας ελέγχου αποτρέπει την κλήση μη διαθέσιμων API.

Scoped Storage (Android 10+)

Scoped Storage είναι μία από τις πιο σημαντικές αλλαγές συμπεριφοράς. Ξεκινώντας από το API 29 (targetSdk 29+), η εφαρμογή δεν μπορεί να αποκτήσει άμεση πρόσβαση σε αρχεία στους καταλόγους Pictures, Downloads, Music και Documents. Αντ' αυτού, χρησιμοποιείται το MediaStore για πολυμέσα, το SAF (Storage Access Framework) για αυθαίρετα αρχεία και το getExternalFilesDir() για δική της αποθήκευση. Εξαίρεση αποτελούν εφαρμογές με δικαίωμα MANAGE_EXTERNAL_STORAGE, το οποίο απαιτεί έγκριση από το Google Play.

Απαιτήσεις του Google Play για API Level και targetSdk

Google Play θέτει υποχρεωτικές απαιτήσεις targetSdkVersion για τη δημοσίευση εφαρμογών. Από τον Αύγουστο του 2024, το Google Play απαιτεί targetSdkVersion >= API 33 (Android 13). Κάθε χρόνο το όριο αυξάνεται: νέες εφαρμογές και ενημερώσεις πρέπει να καθορίζουν targetSdk όχι παλαιότερο του 1 έτους από το τρέχον κύριο API Level. Η παραβίαση της απαίτησης οδηγεί σε αποκλεισμό δημοσίευσης και αφαίρεση της εφαρμογής από το κατάστημα.

Γιατί το Google Play αυστηροποιεί τις απαιτήσεις

Ο κύριος λόγος είναι η ασφάλεια. Κάθε νέο API Level Android εισάγει αλλαγές συμπεριφοράς που κλείνουν φορείς επίθεσης: το Scoped Storage (API 29) αποτρέπει την κλοπή αρχείων, το POST_NOTIFICATIONS (API 33) προστατεύει από ανεπιθύμητες ειδοποιήσεις, το Foreground Service Types (API 34) περιορίζει κρυφές υπηρεσίες παρασκηνίου. Εφαρμογές με χαμηλό targetSdk δεν λαμβάνουν αυτές τις προστασίες και γίνονται απειλή για τους χρήστες. Το Google Play δεν μπορεί να επιτρέπει παρωχημένες εφαρμογές σε σύγχρονες συσκευές.

Έλεγχος συμμόρφωσης με απαιτήσεις

Το Google Play Console ελέγχει το targetSdkVersion κατά τη μεταφόρτωση APK/AAB. Εάν το targetSdk είναι κάτω από την απαίτηση — η κονσόλα αποκλείει τη δημοσίευση με το μήνυμα: "Your app currently targets API level X and must target at least API level Y". Ο προγραμματιστής πρέπει να ενημερώσει το build.gradle, να μεταγλωττίσει ξανά την εφαρμογή, να δοκιμάσει τις αλλαγές συμπεριφοράς και να τη μεταφορτώσει ξανά. Η μορφή AAB συνιστάται για όλες τις νέες δημοσιεύσεις (υποχρεωτική από τον Αύγουστο του 2021).

Έλεγχος API Level στον κώδικα: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT είναι μια στατική ακέραια σταθερά που περιέχει το API Level της συσκευής στην οποία εκτελείται η εφαρμογή. Είναι το κύριο εργαλείο για ελέγχους έκδοσης Android κατά την εκτέλεση. Το Build.VERSION_CODES περιέχει ονομασμένες σταθερές για κάθε API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Η σύγκριση μέσω if (SDK_INT >= VERSION_CODES.TIRAMISU) είναι το τυπικό μοτίβο.

// Παραδείγματα ελέγχου API Level σε κώδικα Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Βασικός έλεγχος API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Προσαρμοστική κλήση API με έλεγχο
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // Το AdaptiveIconDrawable είναι διαθέσιμο μόνο με API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback για παλιές συσκευές
    }

    // 3. Έλεγχος δικαιώματος POST_NOTIFICATIONS (μόνο API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Επιλογή παρόχου εικόνων ανά API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // Το API 34+ χρησιμοποιεί PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // Το API 19+ χρησιμοποιεί Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (όλες οι εκδόσεις)
                "get_content"
            }
        }
    }

    // 5. Έλεγχος τύπου Java μέσω @TargetApi (για προς τα πίσω συμβατότητα)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Η συμπεριφορά Scoped Storage εξαρτάται από το targetSdk, όχι από το SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Πληροφορίες μεταγλώττισης για αναλυτικά στοιχεία
    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
        )
    }
}

// Δοκιμή
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

Η κλάση ApiLevelHelper παρουσιάζει όλα τα κύρια μοτίβα ελέγχου API Level: isAtLeastTiramisu με SDK_INT >= VERSION_CODES, getAdaptiveIcon με fallback για παλιές εκδόσεις, getImagePickerProvider με when πολλαπλής διακλάδωσης, getDeviceApiInfo για αναλυτικά στοιχεία. Ο βασικός κανόνας είναι να μην καλείτε νέα API χωρίς έλεγχο SDK_INT, διαφορετικά η εφαρμογή θα καταρρεύσει με NoSuchMethodError σε παλιές συσκευές.

ANT (Android New API) και lint

Το Android Studio περιλαμβάνει τον στατικό αναλυτή lint, ο οποίος προειδοποιεί για χρήση API άνω του minSdkVersion. Εάν μια μέθοδος καλείται χωρίς έλεγχο SDK_INT, το lint την επισημαίνει ως σφάλμα: "Call requires API level 34 (current min is 26)". Λύσεις: προσθέστε @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) στη μέθοδο ή έλεγχο if του SDK_INT. Το @TargetApi είναι μια παρωχημένη σημείωση, το @RequiresApi συνιστάται.

Πίνακας αντιστοιχίας API Level και εκδόσεων Android

Πίνακας API Level είναι ένα εργαλείο αναφοράς για τον προγραμματιστή. Γνωρίζοντας το API Level της συσκευής, μπορείτε να προσδιορίσετε την έκδοση Android και τις διαθέσιμες λειτουργίες. Ο πίνακας παραθέτει όλες τις κύριες εκδόσεις Android από το API Level 1 (2008) έως το API Level 36 (2025). Τα κωδικά ονόματα (Cupcake, Donut, Tiramisu, VanillaIceCream) χρησιμοποιούνται εσωτερικά στην Google και στο VERSION_CODES.

Πίνακας: οριακά API Level για αλλαγές συμπεριφοράς

Ο παρακάτω πίνακας δείχνει τα βασικά API Level που εισάγουν αλλαγές συμπεριφοράς που σπάζουν την προς τα πίσω συμβατότητα κατά την αύξηση του targetSdk: