targetSdkVersion: Khái niệm chính, Behavioural Changes và Google Play

targetSdkVersion trong Android là gì?

targetSdkVersion là một tham số nguyên trong build.gradle khai báo API Level mà ứng dụng đã được kiểm thử. Hệ thống Android sử dụng tham số này để quyết định behavioural changes nào sẽ áp dụng cho ứng dụng trong thời gian chạy. Nếu targetSdkVersion = 33, Android áp dụng tất cả behavioural changes được giới thiệu đến API 33, nhưng không áp dụng các thay đổi của API 34+. Nếu targetSdkVersion = 34 — các thay đổi đến API 34 được áp dụng, và cứ thế.

Sự khác biệt chính giữa targetSdkVersion và minSdkVersion là cơ chế hoạt động. minSdk được kiểm tra một lần trong quá trình cài đặt và chặn cài đặt nếu không đáp ứng điều kiện. targetSdkVersion ảnh hưởng đến hành vi runtime của hệ thống trên mỗi thiết bị, bất kể ứng dụng đang chạy trên phiên bản Android nào. Cùng một ứng dụng với targetSdk 31 sẽ hoạt động khác nhau trên Android 13, 14 và 15, vì các behavioural changes trên 31 bị tắt.

Cơ chế targetSdkVersion là một công cụ tương thích ngược được tích hợp trong Android. Nếu không có nó, mỗi bản cập nhật hệ điều hành sẽ phá vỡ hàng nghìn ứng dụng cũ. Google đã giới thiệu cơ chế này trong Android 2.1 (API Level 7) và từ đó sử dụng nó như cách tiêu chuẩn để đưa ra các quy tắc bảo mật, quyền riêng tư và quản lý tài nguyên mới mà không phá vỡ các ứng dụng hiện có.

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

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36   // Đã kiểm thử trên Android 16
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Kiểm tra targetSdk hiện tại trong mã
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion chứa targetSdk của ứng dụng
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

Trong ví dụ, targetSdk = 36 kích hoạt tất cả behavioural changes của Android 16. Mã kiểm tra targetSdkVersion qua context.applicationInfo.targetSdkVersion — điều này cho phép xác định động chế độ tương thích nào đang được kích hoạt. Hàm trợ giúp hữu ích cho các thư viện cần thích ứng với targetSdk của ứng dụng gọi.

Behavioural Changes: targetSdk ảnh hưởng đến ứng dụng như thế nào

Behavioural changes là các sửa đổi hành vi hệ thống Android chỉ áp dụng cho các ứng dụng có targetSdkVersion >= một API Level nhất định. Mỗi phiên bản Android chính mới đều giới thiệu behavioural changes, và nếu ứng dụng không cập nhật targetSdk, những thay đổi này không có hiệu lực. Cơ chế này cho phép nhà phát triển cập nhật ứng dụng theo tốc độ của riêng họ, thay vì đồng bộ với bản phát hành hệ điều hành mới.

Scoped Storage (API 29) là một trong những behavioural changes quan trọng nhất. Ứng dụng với targetSdk 29+ không thể truy cập tệp trực tiếp vào các thư mục chia sẻ Pictures, Downloads, Music, Documents. Thay vào đó, MediaStore được sử dụng cho đa phương tiện, SAF (Storage Access Framework) cho tệp tùy ý và getExternalFilesDir() cho bộ nhớ riêng tư. Các ứng dụng cũ với targetSdk 28 trở xuống tiếp tục hoạt động với Full Storage Access cũ, nhưng điều này tạo ra rủi ro bảo mật.

POST_NOTIFICATIONS (API 33) là quyền runtime để gửi thông báo. Ứng dụng với targetSdk 33+ phải yêu cầu quyền Manifest.permission.POST_NOTIFICATIONS từ người dùng qua hộp thoại tiêu chuẩn. Nếu không được cấp quyền, NotificationManager.silent() sẽ không hiển thị thông báo cho người dùng. Trên Android 13+ nếu không có quyền này, thông báo đẩy và thông báo cục bộ đơn giản là không hiển thị, điều này có thể làm giảm đáng kể mức độ tương tác của người dùng.

Cách kiểm tra targetSdk hiện tại

Giá trị targetSdkVersion có thể được lấy qua ADB: lệnh adb shell dumpsys package com.example.myapp | grep targetSdk xuất ra targetSdk=34. Trong mã, context.getApplicationInfo().targetSdkVersion trả về một số nguyên. Để phân tích, nên ghi log targetSdk cùng với android.os.Build.VERSION.SDK_INT để hiểu behavioural changes nào thực sự đang hoạt động trong mỗi phiên.

Yêu cầu của Google Play về targetSdkVersion (2026)

Google Play đặt ra các yêu cầu bắt buộc về targetSdkVersion cho tất cả ứng dụng được xuất bản. Từ tháng 8 năm 2024, targetSdk tối thiểu = 33 (Android 13). Từ tháng 8 năm 2025, targetSdk = 34. Dự kiến từ tháng 8 năm 2026, Google sẽ yêu cầu targetSdk = 35 (Android 15). Các ứng dụng mới và bản cập nhật của ứng dụng hiện có phải tuân thủ các yêu cầu này, nếu không bảng điều khiển sẽ chặn xuất bản. Đây là chính sách của Google Play, không phải hạn chế của Android Runtime: một ứng dụng với targetSdk 34 có thể chạy trên Android 16, nhưng không thể được xuất bản trên Play Store.

Android App Bundle (AAB) là định dạng xuất bản bắt buộc từ tháng 8 năm 2021. APK không còn được chấp nhận trên Google Play (ngoại trừ ứng dụng lớn hơn 150 MB và một số dự án cũ). Định dạng AAB cho phép Google tạo APK được tối ưu hóa cho từng API Level và mật độ màn hình, giảm kích thước tải xuống 15-30%. Để kiểm tra targetSdk, Google Play phân tích tệp kê khai AAB và đưa ra lỗi kèm giá trị tối thiểu yêu cầu nếu không tuân thủ.

Google Play Console kiểm tra targetSdkVersion không chỉ khi tải lên AAB mới mà còn khi cập nhật ứng dụng hiện có. Nếu ứng dụng của bạn có targetSdk 33 và Google nâng ngưỡng tối thiểu lên 34 — bạn sẽ không thể phát hành bất kỳ bản cập nhật nào cho đến khi nâng targetSdk. Đối với các ứng dụng đã lâu không được cập nhật, Google Play có thể tự động gỡ xuất bản (unpublish).

Cách cập nhật targetSdkVersion không lỗi

Cập nhật targetSdkVersion không chỉ là thay đổi một con số trong build.gradle. Mỗi behavioural change có thể phá vỡ chức năng hiện có nếu mã không được chuẩn bị trước. Khuyến nghị bắt đầu chuẩn bị 3-6 tháng trước hạn chót của Google Play, đặc biệt nếu ứng dụng lớn và sử dụng nhiều API hệ thống.

Quy trình từng bước: Bước 1 — nghiên cứu các behavioural changes cho API Level mới trong tài liệu Android Developers (trang "Behavioural Changes by API Level"). Bước 2 — tạo nhánh targetSdk-update và thay đổi targetSdk thành giá trị mới. Bước 3 — chạy ứng dụng trên trình giả lập hoặc thiết bị có API Level mới và kiểm tra mọi chức năng liên quan đến thay đổi. Bước 4 — sửa lỗi: thêm quyền, thay đổi cách xử lý tệp, cập nhật tệp kê khai.

Bước 5 — kiểm thử trên thiết bị cũ. Nâng targetSdk không ảnh hưởng đến thiết bị có API Level thấp hơn targetSdk mới, nhưng behavioural changes áp dụng cho tất cả thiết bị có API Level >= targetSdk. Nếu bạn nâng targetSdk từ 33 lên 34, trên thiết bị có API 34+ các behavioural changes của API 34 sẽ được kích hoạt. Trên thiết bị có API 33 sẽ không có gì thay đổi.

// Chuẩn bị cho 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 hạn chế Advertising ID từ API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — định danh không khả dụng, sử dụng MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Kiểm tra: behavioural changes nào đang hoạt động
    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")
        }
    }
}

Lớp AdsManager thể hiện sự chuẩn bị cho Privacy Sandbox (API 35). Advertising ID trở nên không khả dụng từ API 35 với targetSdk 35+. Hàm getActiveChanges cho thấy mẫu đúng để kiểm tra behavioural changes: cần kiểm tra cả SDK_INT của thiết bị và targetSdk của ứng dụng. Chỉ khi cả hai điều kiện khớp thì thay đổi mới thực sự hoạt động.

Android 15 (API 35): các behavioural changes chính

Android 15 (API 35, Vanilla Ice Cream) giới thiệu một số behavioural changes quan trọng mà nhà phát triển phải xem xét khi cập nhật targetSdk lên 35. Đầu tiên — Privacy Sandbox for Android. Đây là sáng kiến của Google nhằm thay thế Advertising ID bằng các API riêng tư hơn: Topics API (sở thích người dùng), Protected Audience (tiếp thị lại) và Attribution Reporting (chuyển đổi). Từ API 35, Advertising ID không còn là định danh ổn định và có thể trả về giá trị null.

Thay đổi thứ hai — Foreground Service Types (API 34, tiếp tục trong API 35). Từ API 34, mọi ứng dụng có targetSdk 34+ phải chỉ định loại dịch vụ nền trước trong tệp kê khai: dataSync, systemExempted, shortService, location, mediaPlayback và các loại khác. Nếu không, hệ thống sẽ tạo ra ForegroundServiceTypeNotAllowedException. Trong API 35, loại health mới đã được thêm vào và việc xác thực các loại hiện có được thắt chặt. Tất cả dịch vụ nền trước phải được xem xét.

Thay đổi thứ ba — hạn chế SCHEDULE_EXACT_ALARM. Từ API 35, ứng dụng có targetSdk 35+ không thể sử dụng SCHEDULE_EXACT_ALARM nếu không có sự cho phép rõ ràng của người dùng. Hệ thống hiển thị hộp thoại và người dùng phải phê duyệt lịch trình chính xác. Đối với báo thức và hẹn giờ, điều này có nghĩa là thêm một bước UX. Giải pháp thay thế là sử dụng báo thức không chính xác với khoảng đệm 10 phút.

// Android 15 (API 35): kiểm tra 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+: yêu cầu quyền người dùng
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Dưới API 35 — báo thức chính xác có sẵn không cần quyền
        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 và hạn chế báo thức là hai behavioural changes quan trọng nhất của API 35. SDK quảng cáo sẽ cần di chuyển sang Topics API và Attribution Reporting. Đối với ứng dụng có báo thức và lời nhắc — thích ứng UX cho hộp thoại cấp phép. Bỏ qua những thay đổi này sẽ dẫn đến ứng dụng bị treo khi chạy trên Android 15 hoặc kiếm tiền từ quảng cáo bị hỏng.

Sự khác biệt giữa targetSdk và compileSdk

Sự khác biệt giữa targetSdkVersion và compileSdkVersion là một trong những nguồn gây nhầm lẫn phổ biến nhất trong số các nhà phát triển Android. compileSdkVersion là phiên bản 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 nhưng không ảnh hưởng đến hành vi runtime. targetSdkVersion là phiên bản mà ứng dụng được kiểm thử — nó xác định behavioural changes nào áp dụng trong runtime. compileSdk có thể và nên cao hơn hoặc bằng targetSdk.

Quy tắc rất đơn giản: compileSdk >= targetSdk >= minSdk. compileSdk thường bằng API Level ổn định mới nhất (năm 2026 — 36). targetSdk nên cao nhất có thể trong số các phiên bản bạn đã kiểm thử. minSdk nên thấp nhất có thể để đạt phạm vi tiếp cận tối đa. Nâng compileSdk không yêu cầu kiểm thử behavioural changes — nó chỉ mở quyền truy cập vào API mới cho trình biên dịch. Nâng targetSdk yêu cầu một chu kỳ kiểm thử đầy đủ tất cả behavioural changes.

Thực tế: nếu bạn muốn sử dụng API mới từ Android 16 (API 36) nhưng chưa kiểm thử behavioural changes của API 36, hãy đặt compileSdk = 36, targetSdk = 35. Mã sẽ biên dịch với API mới, nhưng behavioural changes của API 36 sẽ không được áp dụng. Sau khi bạn kiểm thử tất cả thay đổi — hãy nâng targetSdk lên 36.