API Level: nó là gì, các phiên bản API và targetSdk

API Level Android là gì?

API Level Android là một định danh số nguyên được gán cho mỗi bản phát hành công khai của Android Framework API. Bản phát hành đầu tiên Android 1.0 có 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. Mỗi API Level mới có thể thêm các lớp, phương thức, hằng số, quyền mới và thay đổi hành vi của những cái hiện có.

API Level không tăng chính xác 1 với mỗi bản phát hành. Ví dụ, Android 4.4W (Wear) có API 20, trong khi Android 5.0 — API 21. Các khoảng trống liên quan đến các lần lặp nội bộ và thiết bị Wear OS. Đối với nhà phát triển, điều quan trọng là biết không phải tên phiên bản (KitKat, Lollipop, Tiramisu), mà là API Level của nó — nó được sử dụng trong mã để kiểm tra tương thích.

Mục đích chính của API Level là tương thích ngược. Một ứng dụng được biên dịch chống lại API 34 có thể chạy trên các thiết bị có API 34 trở xuống (nếu nó không sử dụng API mới mà không kiểm tra). Android Runtime (ART) kiểm tra các lệnh gọi API ở cấp hệ thống và áp dụng các thay đổi hành vi tùy thuộc vào targetSdkVersion của ứng dụng.

Cách Android xử lý API Level

Khi cài đặt ứng dụng, PackageManager kiểm tra API Level của thiết bị >= minSdkVersion từ AndroidManifest.xml. Nếu điều kiện không được đáp ứng — quá trình cài đặt bị chặn với thông báo "App not installed". Trong thời gian chạy, Android Runtime giám sát các lệnh gọi API yêu cầu API Level cao hơn và tạo ra NoSuchMethodError hoặc UnsatisfiedLinkError nếu phương thức không có trong phiên bản hiện tại.

minSdk, targetSdk, compileSdk: sự khác biệt và vai trò của từng tham số

Trong tệp build.gradle (Module: app), nhà phát triển chỉ định ba tham số API Level: minSdkVersion, targetSdkVersion và compileSdkVersion. Nhầm lẫn chúng là một trong những lỗi phổ biến nhất của các nhà phát triển Android mới bắt đầu. Mỗi tham số chịu trách nhiệm cho một khía cạnh khác nhau của tương thích và giá trị của chúng phải nhất quán.

minSdkVersion

minSdkVersion là API Level tối thiểu mà ứng dụng có thể được cài đặt và chạy. Các thiết bị có API Level dưới minSdk không thấy ứng dụng trên Google Play và không thể cài đặt nó. Giá trị được chọn dựa trên đối tượng mục tiêu: minSdk 21 (Android 5.0) bao phủ 97% thiết bị, minSdk 26 (Android 8.0) — khoảng 85%, minSdk 31 (Android 12) — khoảng 55% (dữ liệu từ Android Studio Distribution Dashboard, 2026). minSdk càng thấp, phạm vi bao phủ càng lớn, nhưng càng cần nhiều mã tương thích ngược.

targetSdkVersion

targetSdkVersion là API Level mà ứng dụng đã được kiểm thử. Android sử dụng targetSdk để áp dụng các thay đổi hành vi: nếu ứng dụng chỉ định targetSdk 33, hệ thống sẽ bật tất cả các thay đổi hành vi được giới thiệu trong API 33. Nếu targetSdk là 31, hệ thống không áp dụng các thay đổi API 32-33, duy trì tương thích với hành vi cũ. Đây là tham số quan trọng nhất cho bảo mật: Google Play yêu cầu targetSdk không quá 1 năm so với API Level hiện tại.

compileSdkVersion

compileSdkVersion là phiên bản Android SDK mà mã được biên dịch chống lại. Nó xác định API nào có sẵn tại thời điểm biên dịch. compileSdk phải >= targetSdk và lý tưởng nhất là bằng với API Level ổn định mới nhất. Tăng compileSdk không ảnh hưởng đến hành vi thời gian chạy — chỉ ảnh hưởng đến sự sẵn có của các API mới cho trình biên dịch. Sau khi tăng compileSdk, bạn cần kiểm tra mã để tìm các API không được dùng nữa và các yêu cầu quyền mới.

// build.gradle.kts — ví dụ cấu hình 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")
}

Trong ví dụ build.gradle.kts, compileSdk = 36 (mới nhất tại thời điểm viết), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 cung cấp quyền truy cập vào tất cả các API Android 16. targetSdk 36 bật tất cả các thay đổi hành vi Android 16. minSdk 26 bao phủ ~85% thiết bị. AndroidX Activity KTX và AppCompat cung cấp tương thích ngược cho các fragment và chủ đề.

AndroidManifest.xml

Các tham số minSdk và targetSdk cũng có thể được chỉ định trong AndroidManifest.xml, nhưng các dự án hiện đại sử dụng build.gradle — các giá trị từ Gradle ghi đè lên tệp kê khai. Trong tệp kê khai, có thể hữu ích khi chỉ định cho các thư viện và mô-đun không sử dụng cấu hình build Gradle.

Thay đổi hành vi: targetSdk ảnh hưởng đến hành vi ứng dụng như thế nào

Thay đổi hành vi là những sửa đổi trong cách hệ thống Android hoạt động chỉ được áp dụng cho các ứng dụng có targetSdk >= một API Level nhất định. Mỗi bản phát hành Android mới giới thiệu các thay đổi hành vi có thể làm hỏng các ứng dụng hiện có nếu chúng không được cập nhật. Đây là cơ chế bảo mật chính của Android: các ứng dụng cũ tiếp tục hoạt động như trước, các ứng dụng mới tuân theo các quy tắc hiện tại.

Các thay đổi hành vi chính theo phiên bản

Android 10 (API 29) — Scoped Storage: ứng dụng có targetSdk 29+ không có quyền truy cập trực tiếp vào hệ thống tệp chia sẻ, chỉ thông qua MediaStore, SAF hoặc bộ nhớ riêng của chúng. Android 11 (API 30) — Package Visibility: bộ lọc gói, ứng dụng chỉ thấy các gói đã cài đặt mà chúng tương tác. Android 12 (API 31) — Foreground Service Notification: tất cả các dịch vụ nền trước phải hiển thị thông báo trong vòng 10 giây sau khi khởi động. Android 13 (API 33) — POST_NOTIFICATIONS: quyền thời gian chạy cho thông báo đẩy. Android 14 (API 34) — Foreground Service Types: khai báo bắt buộc loại dịch vụ nền trước trong tệp kê khai.

// Xử lý thay đổi hành vi 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) {
        // Quyền POST_NOTIFICATIONS chỉ hoạt động với API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Dưới API 33 không yêu cầu quyền
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Quyền đã được cấp, có thể gửi thông báo
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Hiển thị giải thích tại sao cần quyền
                activity.showRationale()
            }

            else -> {
                // Yêu cầu quyền
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Tạo và hiển thị thông báo
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Thông báo")
            .setContentText("Tin nhắn mới")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Đăng ký requestPermissionLauncher trong Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Quyền đã được cấp
        }
    }

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

Ví dụ về xử lý POST_NOTIFICATIONS trong Kotlin: kiểm tra Build.VERSION.SDK_INT >= TIRAMISU, yêu cầu quyền thời gian chạy qua ActivityResultContracts.RequestPermission, xử lý kết quả trong callback. Không có quyền này, ứng dụng có targetSdk 33+ không thể hiển thị thông báo đẩy. Dưới API 33, quyền không được yêu cầu — mã kiểm tra ngăn chặn việc gọi API không khả dụng.

Scoped Storage (Android 10+)

Scoped Storage là một trong những thay đổi hành vi quan trọng nhất. Bắt đầu từ API 29 (targetSdk 29+), ứng dụng không thể có quyền truy cập tệp trực tiếp vào các thư mục Pictures, Downloads, Music và Documents. Thay vào đó, MediaStore được sử dụng cho đa phương tiện, SAF (Storage Access Framework) cho các tệp tùy ý và getExternalFilesDir() cho bộ nhớ riêng. Ngoại lệ là các ứng dụng có quyền MANAGE_EXTERNAL_STORAGE, yêu cầu sự chấp thuận của Google Play.

Yêu cầu của Google Play đối với API Level và targetSdk

Google Play đặt ra các yêu cầu bắt buộc về targetSdkVersion để xuất bản ứng dụng. Kể từ tháng 8 năm 2024, Google Play yêu cầu targetSdkVersion >= API 33 (Android 13). Mỗi năm ngưỡng tăng lên: các ứng dụng và bản cập nhật mới phải chỉ định targetSdk không quá 1 năm so với API Level chính hiện tại. Vi phạm yêu cầu dẫn đến chặn xuất bản và xóa ứng dụng khỏi cửa hàng.

Tại sao Google Play thắt chặt yêu cầu

Lý do chính là bảo mật. Mỗi API Level Android mới giới thiệu các thay đổi hành vi đóng các vectơ tấn công: Scoped Storage (API 29) ngăn chặn trộm tệp, POST_NOTIFICATIONS (API 33) bảo vệ khỏi thông báo rác, Foreground Service Types (API 34) hạn chế các dịch vụ nền ẩn. Các ứng dụng có targetSdk thấp không nhận được các bảo vệ này và trở thành mối đe dọa cho người dùng. Google Play không thể cho phép các ứng dụng lỗi thời trên các thiết bị hiện đại.

Kiểm tra tuân thủ yêu cầu

Google Play Console kiểm tra targetSdkVersion khi tải lên APK/AAB. Nếu targetSdk thấp hơn yêu cầu — bảng điều khiển chặn xuất bản với thông báo: "Your app currently targets API level X and must target at least API level Y". Nhà phát triển phải cập nhật build.gradle, biên dịch lại ứng dụng, kiểm tra các thay đổi hành vi và tải lên lại. Định dạng AAB được khuyến nghị cho tất cả các bản xuất bản mới (bắt buộc từ tháng 8 năm 2021).

Kiểm tra API Level trong mã: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT là một hằng số nguyên tĩnh chứa API Level của thiết bị đang chạy ứng dụng. Đây là công cụ chính để kiểm tra phiên bản Android trong thời gian chạy. Build.VERSION_CODES chứa các hằng số được đặt tên cho mỗi API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). So sánh qua if (SDK_INT >= VERSION_CODES.TIRAMISU) là mẫu tiêu chuẩn.

// Ví dụ về kiểm tra API Level trong mã Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Kiểm tra API Level cơ bản
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Gọi API thích ứng với kiểm tra
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable chỉ khả dụng với API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback cho các thiết bị cũ
    }

    // 3. Kiểm tra quyền POST_NOTIFICATIONS (chỉ API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Chọn nhà cung cấp hình ảnh theo API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ sử dụng PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ sử dụng Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (tất cả phiên bản)
                "get_content"
            }
        }
    }

    // 5. Kiểm tra kiểu Java qua @TargetApi (để tương thích ngược)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Hành vi Scoped Storage phụ thuộc vào targetSdk, không phải SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Thông tin bản dựng để phân tích
    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
        )
    }
}

// Kiểm thử
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

Lớp ApiLevelHelper trình bày tất cả các mẫu kiểm tra API Level chính: isAtLeastTiramisu với SDK_INT >= VERSION_CODES, getAdaptiveIcon với fallback cho các phiên bản cũ, getImagePickerProvider với when đa nhánh, getDeviceApiInfo cho phân tích. Quy tắc chính là không gọi API mới mà không kiểm tra SDK_INT, nếu không ứng dụng sẽ bị lỗi NoSuchMethodError trên các thiết bị cũ.

ANT (Android New API) và lint

Android Studio bao gồm trình phân tích tĩnh lint, cảnh báo về việc sử dụng API trên minSdkVersion. Nếu một phương thức được gọi mà không kiểm tra SDK_INT, lint sẽ đánh dấu nó là lỗi: "Call requires API level 34 (current min is 26)". Giải pháp: thêm @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) vào phương thức hoặc kiểm tra if của SDK_INT. @TargetApi là chú thích không được dùng nữa, @RequiresApi được khuyến nghị.

Bảng tương ứng giữa API Level và các phiên bản Android

Bảng API Level là công cụ tham khảo cho nhà phát triển. Biết API Level của thiết bị, bạn có thể xác định phiên bản Android và các tính năng khả dụng. Bảng liệt kê tất cả các bản phát hành Android chính từ API Level 1 (2008) đến API Level 36 (2025). Tên mã (Cupcake, Donut, Tiramisu, VanillaIceCream) được sử dụng nội bộ tại Google và trong VERSION_CODES.

Bảng: API Level ngưỡng cho các thay đổi hành vi

Bảng sau đây hiển thị các API Level chính giới thiệu các thay đổi hành vi phá vỡ tương thích ngược khi tăng targetSdk: