compileSdkVersion: mga batayan, bagong API at configuration sa Gradle

Ano ang compileSdkVersion sa Android?

compileSdkVersion — isang integer parameter sa build.gradle na tumutukoy kung aling bersyon ng Android SDK ang gagamitin sa pag-compile ng code. Kapag sumulat ka ng code na gumagamit ng mga klase mula sa android.* o androidx.*, sinusuri ng compiler ang mga ito sa mga API na available sa tinukoy na bersyon ng compileSdk. Kung ang isang pamamaraan ay lumitaw sa API 36 at compileSdk = 35, ang code ay hindi magko-compile. Kung compileSdk = 36 — ang code ay magko-compile, ngunit sa isang device na may API 35 kapag tinawag ang pamamaraang ito nang walang pagsusuri ay magkakaroon ng error.

Ang compileSdkVersion ay naglo-load mula sa Android SDK Platform, na naka-install sa pamamagitan ng SDK Manager sa Android Studio. Ang bawat API Level ay may sariling platform: android-21, android-29, android-34, android-35, android-36. Ang platform ay naglalaman ng android.jar — isang set ng mga klase, pamamaraan at constant na ginagamit ng Kotlin/Java compiler. Kung hindi naka-install ang platform, awtomatikong dina-download ito ng Gradle sa pamamagitan ng sdkmanager sa unang build.

AGP (Android Gradle Plugin) bersyon 8.7+ ay nagrerekomenda na tukuyin ang compileSdk bilang isang integer sa pamamagitan ng compileSdk = 36 sa Kotlin DSL, nang walang android- prefix. Ang compileSdk ay maaari ring tukuyin sa pamamagitan ng compileSdkVersion 36 sa Groovy DSL o compileSdkPreview para sa preview na bersyon ng SDK (developer previews). Ang compileSdkPreview ay ginagamit para sa pag-test ng mga darating na API Level bago ang opisyal na release.

// build.gradle.kts — configuration ng compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — pinakabagong stable na API Level (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Alternatibo: compileSdkPreview para sa preview na bersyon
// compileSdkPreview = "Baklava"

Sa halimbawa, ang compileSdk = 36 ay nagbibigay ng access sa lahat ng API ng Android 16 (Baklava). Ang Android SDK Platform 36 ay dapat naka-install sa SDK Manager. Ang compileSdkPreview na may pangalang "Baklava" ay maaaring gamitin para sa pag-test ng mga hindi stable na API bago ang opisyal na release ng platform. Pagkatapos ng release, ang preview ay pinapalitan ng stable na compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Tatlong parameter ng API Level sa build.gradle — compileSdkVersion, targetSdkVersion at minSdkVersion — ay madalas na napagkakamalan. Bawat isa ay responsable para sa iba't ibang aspeto ng compatibility, at ang kanilang mga halaga ay dapat na nakaayon sa panuntunang compileSdk >= targetSdk >= minSdk. minSdk — ibabang hangganan: ang mga device na mas mababa dito ay hindi makakakita ng application. targetSdk — punto ng pagsubok: ang behavioural changes ay isina-activate hanggang sa antas na ito. compileSdk — kisame: ang mga API na mas mataas sa antas na ito ay hindi available sa compiler.

Pangunahing praktikal na panuntunan: ang compileSdk ay maaaring itaas nang walang anumang pagsubok sa mga device. Ito ay isang ligtas na operasyon na nagbibigay lamang sa compiler ng bagong bersyon ng android.jar. Ang tanging panganib — mga deprecated na API na maaaring alisin sa bagong bersyon ng platform, ngunit ito ay natutuklasan sa yugto ng pag-compile at madaling ayusin. Ang pagtaas ng targetSdk, sa kabaligtaran, ay nangangailangan ng buong QA cycle.

Bakit ang compileSdk ay maaaring mas mataas kaysa sa targetSdk? Isipin na ang Android 16 (API 36) ay lumabas na may mga bagong API na gusto mong gamitin sa code, ngunit ang behavioural changes ng API 36 ay hindi mo pa nasusubukan. Itinakda mo ang compileSdk = 36 (mga bagong API available), targetSdk = 35 (behavioural changes ng API 36 ay hindi aktibo). Ang code ay magko-compile, gagamit ng mga bagong pamamaraan sa ilalim ng mga pagsusuri ng SDK_INT, at ang behavioural changes ng API 36 ay hindi makakasira ng application dahil ang targetSdk = 35.

Mga halimbawa ng tamang kombinasyon

compileSdk = 36, targetSdk = 36, minSdk = 26 — buong compatibility sa mga pinakabagong API at behavioural changes, coverage 85% ng mga device. compileSdk = 36, targetSdk = 34, minSdk = 26 — mga bagong API available, behavioural changes hanggang API 34 lamang. compileSdk = 35, targetSdk = 36 — hindi tama: compileSdk mas mababa kaysa sa targetSdk, API 36 hindi available, kahit na ang behavioural changes 36 ay aktibo.

Paano i-update ang compileSdkVersion: step-by-step na gabay

Pag-update ng compileSdkVersion — isa sa pinakasimple at pinakaligtas na operasyon sa isang Android project. Hindi tulad ng targetSdk, hindi ito nangangailangan ng mahabang pagsubok ng behavioural changes. Gayunpaman, may ilang hakbang na kailangang gawin upang maiwasan ang mga error sa pag-compile at mga babala ng deprecated.

Hakbang 1 — i-install ang bagong platform sa pamamagitan ng SDK Manager sa Android Studio: Tools → SDK Manager → SDK Platforms → piliin ang bagong API Level. Kung hindi mo i-install ang platform, susubukan ng Gradle na i-download ito nang awtomatiko, ngunit maaaring pabagalin nito ang unang build. Hakbang 2 — baguhin ang compileSdk sa build.gradle sa bagong halaga. Hakbang 3 — isagawa ang build (Build → Make Project) at ayusin ang mga error sa pag-compile.

Hakbang 4 — suriin ang mga deprecated na API. Pagkatapos itaas ang compileSdk, ang ilang pamamaraan ay maaaring mamarkahan ng @Deprecated na may tala na "removed in API X". Ang Android Studio ay nagha-highlight sa kanila ng strikethrough at nagbibigay ng babala. Palitan ang mga deprecated na tawag ng mga bagong alternatibo. Kung ang alternatibo ay nangangailangan ng API Level na mas mataas kaysa sa minSdk, magdagdag ng runtime check. Hakbang 5 — suriin ang dependencies: ang ilang library ay maaaring mangailangan ng partikular na bersyon ng compileSdk. Ang AGP 8.7+ ay nagrerekomenda ng compileSdk = 36.

// Pagkatapos itaas ang compileSdk: pagpapalit ng mga deprecated na API
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // BAGO: deprecated na pamamaraan (maaaring alisin sa bagong API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Maaaring maging deprecated sa API 36
    }

    // PAGKATAPOS: bagong alternatibo (kung available)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Bagong API mula sa compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Halimbawa ng bagong API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Ang klase na CompileSdkMigration ay nagpapakita ng tamang pattern ng migration. Ang lumang pamamaraan na memoryClass ay maaaring alisin sa bagong API — ang compiler ay magbibigay ng error. Ang bagong alternatibo na getMemoryClassSafe ay available lamang sa API 36+, kaya ito ay tinatawag sa ilalim ng pagsusuri na SDK_INT >= BAKLAVA. Para sa mga lumang device, ginagamit ang fallback na may @Suppress("DEPRECATION").

Pagtatrabaho sa mga bagong API: conditional checks at fallback

Mga bagong API, na available dahil sa pagtaas ng compileSdkVersion, ay hindi direktang matawag kung ang minSdkVersion ay mas mababa kaysa sa API Level na ito. Kung walang runtime check, ang application ay mag-crash na may AbstractMethodError, NoSuchMethodError o VerifyError sa mga lumang device. Ang pangunahing mekanismo ng proteksyon — pagsusuri ng Build.VERSION.SDK_INT na may pagtawag ng bagong API lamang sa sapat na API Level at fallback para sa mga lumang bersyon.

AndroidX ay nagbibigay ng mga backport ng maraming bagong API, na nagpapahintulot sa paggamit ng mga modernong pamamaraan kahit na sa mababang compileSdk. Halimbawa, ang Activity Result API mula sa androidx.activity:activity-ktx:1.9.3 ay gumagana sa lahat ng bersyon ng Android simula sa API 14. Ang NotificationCompat mula sa AndroidX ay nagpapahintulot sa paggamit ng mga modernong notification sa mga lumang API. Ang PhotoPicker ay available sa pamamagitan ng ActivityResultContracts.PickVisualMedia simula sa API 34+.

// Ligtas na pagtawag ng bagong API na may compileSdk 36 at minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: bagong pamamaraan para sa pagtatrabaho sa kulay
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Bagong API mula sa compileSdk 36 — nangangailangan ng API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: manu-manong pag-format para sa mga lumang API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: hindi kinakailangan ang backport — SDK_INT check
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Paggamit sa Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

Ang klase na NewApiHelper ay nagpapakita ng ligtas na pagtawag ng bagong API na Color.toArgbHexString (hypothetical na API 36) na may fallback-formatting para sa mga lumang bersyon. Pangunahing prinsipyo: ang compileSdk ay nagbibigay ng access sa pagtawag ng mga bagong pamamaraan sa code, ngunit ang runtime check na SDK_INT ay nagpoprotekta laban sa crash sa mga lumang device. Kung walang SDK_INT check, ang application na may minSdk 26 at compileSdk 36 ay mag-crash sa Android 8-15.

AGP (Android Gradle Plugin) at compileSdkVersion

Android Gradle Plugin (AGP) — ang pangunahing tool sa pag-build ng mga Android application. Bawat bersyon ng AGP ay sumusuporta sa isang partikular na saklaw ng compileSdkVersion. Ang AGP 8.7.x (inilabas noong 2026) ay nangangailangan ng compileSdk >= 34 at nagrerekomenda ng compileSdk = 36. Ang AGP 8.5.x ay sumusuporta sa compileSdk 33-35. Kung ang compileSdk ay mas mababa kaysa sa minimum para sa AGP, ang build ay magtatapos sa error na "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) ay nakatali rin sa compileSdkVersion. Kung ang project ay gumagamit ng native code sa C/C++ sa pamamagitan ng NDK, ang compileSdk ay tumutukoy sa bersyon ng mga header file at library. Ang NDK r27+ ay nagrerekomenda ng compileSdk 36. Para sa mga library na may .so file, ang compileSdk ay nakakaapekto sa minimum na API Level para sa native code sa pamamagitan ng APP_MIN_SDK_VERSION sa Application.mk.

Gradle (7.6+) at Kotlin (2.0+) ay nakakaapekto rin sa compatibility sa compileSdk. Ang AGP 8.7+ ay nangangailangan ng Gradle 8.9+ at Kotlin 2.0+. Sa pagtaas ng compileSdk, inirerekomenda na i-update ang AGP, Gradle at Kotlin sa pinakabagong stable na bersyon. Suriin ang compatibility sa opisyal na talahanayan ng Android Gradle Plugin compatibility.

Mga karaniwang problema sa pagtaas ng compileSdk

Mga problema sa pagtaas ng compileSdkVersion ay nahahati sa tatlong kategorya: compilation errors, deprecated warnings at runtime incompatibilities. Compilation errors — mga pamamaraan na inalis mula sa API at ang code ay hindi nagko-compile. Deprecated warnings — mga pamamaraan na minarkahan ng @Deprecated, ang code ay nagko-compile na may mga babala. Runtime incompatibilities — mga bagong API ay sapilitan para sa partikular na functionality at nagdudulot ng error kapag hindi sapat ang API Level sa device.

Unang karaniwang problema — "Cannot resolve symbol X". Ito ay nangangahulugan na ang isang klase o pamamaraan ay inalis mula sa pampublikong API sa bagong bersyon ng SDK. Solusyon: maghanap ng alternatibo sa bagong platform o gumamit ng AndroidX na katumbas. Halimbawa, ang klase na AsyncTaskLoader ay deprecated sa API 28 at inalis mula sa pampublikong API sa mas bagong mga bersyon. Alternatibo — Kotlin Coroutines o WorkManager.

Pangalawang problema — pagbabago ng signature ng pamamaraan. Sa bagong bersyon ng API, ang pamamaraan ay maaaring nagbago ng bilang o uri ng mga parameter. Ang Kotlin/Java compiler ay nagbibigay ng error na "None of the following functions can be called with the arguments supplied". Solusyon: i-update ang tawag ng pamamaraan sa bagong signature o magdagdag ng SDK_INT check na may pagtawag ng lumang signature para sa mga lumang device.

// Paglutas ng mga problema sa pagtaas ng compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problema: ang pamamaraang hasSystemFeature ay nagbago ng signature sa API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Bagong signature: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Lumang signature: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problema: klase ay inalis, gumagamit ng AndroidX na katumbas
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Sa halip na android.app.FragmentManager (inalis) gumagamit
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Ang klase na CompileSdkProblemFixer ay lumulutas ng mga karaniwang problema: ang binagong signature ng hasSystemFeature (hypothetical na pagbabago sa API 36) ay pinangangasiwaan sa pamamagitan ng SDK_INT check na may pagtawag ng tamang bersyon ng pamamaraan. Ang inalis na klase na android.app.FragmentManager ay pinalitan ng AndroidX na katumbas. Para sa mga lumang tawag na walang alternatibo, ginagamit ang @Suppress("DEPRECATION") na may komento tungkol sa dahilan ng pagpapanatili.