Google Play menggunakan atribut <uses-sdk> yang dideklarasikan dalam manifes aplikasi untuk memfilter aplikasi dari perangkat yang tidak memenuhi persyaratan versi platform. Sebelum menyetel atribut ini, pastikan Anda memahami filter Google Play.

sintaksis:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

terdapat dalam:

<manifest>

deskripsi:

Memungkinkan Anda untuk memperlihatkan kompatibilitas aplikasi dengan satu atau beberapa versi platform Android, dengan menggunakan integer API Level. API Level yang diperlihatkan oleh aplikasi akan dibandingkan dengan API Level dari sistem Android yang disediakan, yang mungkin berbeda di antara perangkat Android.

Meskipun memiliki nama seperti itu, elemen ini digunakan untuk menentukan API Level, bukan nomor versi SDK (software development kit) atau platform Android. API Level selalu berupa integer tunggal. Anda tidak dapat memperoleh API Level dari nomor versi Android terkait (contohnya, ini tidak sama dengan versi utama atau jumlah dari versi utama dan minor).

Baca juga dokumen tentang Pembuatan Versi Aplikasi Anda.

atribut:

android:minSdkVersion

Integer yang menentukan API Level minimum yang diperlukan agar aplikasi dapat berjalan. Sistem Android akan mencegah pengguna menginstal aplikasi jika API Level sistem lebih rendah dari nilai yang ditetapkan dalam atribut ini. Anda harus selalu mendeklarasikan atribut ini.

Perhatian: Jika Anda tidak mendeklarasikan atribut ini, sistem akan mengasumsikan nilai default adalah "1", yang menunjukkan bahwa aplikasi Anda kompatibel dengan semua versi Android. Jika aplikasi Anda tidak kompatibel dengan semua versi (misalnya, aplikasi menggunakan API yang diperkenalkan di API Level 3) dan Anda belum mendeklarasikan minSdkVersion, yang tepat, maka ketika diinstal pada sistem dengan API Level yang kurang dari 3, aplikasi akan error saat runtime ketika mencoba untuk mengakses API yang tidak tersedia. Karena alasan ini, pastikan untuk mendeklarasikan API Level yang tepat di dalam atribut minSdkVersion.

android:targetSdkVersion

Integer yang menentukan API Level yang ditargetkan aplikasi. Jika tidak disetel, nilai default adalah sama dengan yang diberikan pada minSdkVersion.

Atribut ini memberi tahu sistem bahwa Anda telah melakukan pengujian terhadap versi target dan sistem tidak boleh mengaktifkan perilaku kompatibilitas apa pun untuk mempertahankan kompatibilitas dengan versi baru aplikasi Anda dengan versi target. Aplikasi masih dapat berjalan pada versi yang lebih lama (hingga minSdkVersion).

Karena Android berkembang dengan setiap versi baru, beberapa perilaku dan bahkan tampilan dapat berubah. Namun, jika API level platform lebih tinggi dari versi yang dideklarasikan oleh targetSdkVersion aplikasi Anda, sistem mungkin mengaktifkan perilaku kompatibilitas untuk memastikan bahwa aplikasi Anda terus bekerja seperti yang diharapkan. Anda dapat menonaktifkan perilaku kompatibilitas seperti ini dengan menetapkan targetSdkVersion untuk mencocokkan dengan API level tempat platform tersebut berjalan. Contohnya, menyetel nilai ini ke "11" atau lebih tinggi memungkinkan sistem untuk menerapkan tema default baru (Holo) untuk aplikasi Anda saat berjalan pada Android 3.0 atau yang lebih tinggi dan juga menonaktifkanmode kompatibilitas layar ketika berjalan pada layar yang lebih besar (karena dukungan untuk API level 11 secara implisit mendukung layar yang lebih besar).

Ada banyak perilaku kompatibilitas yang dapat diaktifkan sistem berdasarkan nilai yang Anda tetapkan untuk atribut ini. Beberapa perilaku ini dijelaskan oleh versi platform yang sesuai dalam referensi Build.VERSION_CODES.

Untuk menjaga aplikasi Anda agar cocok dengan setiap rilis Android, Anda harus menaikkan nilai atribut ini untuk mencocokkan dengan API level terbaru, kemudian menguji aplikasi Anda secara menyeluruh pada versi platform yang sesuai.

Diperkenalkan di: API Level 4.

android:maxSdkVersion

Integer yang menentukan API Level maksimum yang akan digunakan untuk menjalankan aplikasi yang didesain.

Di Android 1.5, 1.6, 2.0, dan 2.0.1, sistem memeriksa nilai atribut ini ketika menginstal aplikasi dan ketika memvalidasi ulang aplikasi setelah update sistem. Dalam kedua kasus, jika atribut maxSdkVersion aplikasi lebih rendah dari API Level yang digunakan oleh sistem itu sendiri, sistem tidak akan mengizinkan penginstalan aplikasi. Jika terjadi validasi ulang setelah update sistem, aplikasi Anda akan langsung dihapus dari perangkat.

Untuk menggambarkan cara atribut ini dapat memengaruhi aplikasi Anda setelah update sistem, pertimbangkan contoh berikut:

Aplikasi mendeklarasikan maxSdkVersion="5" di dalam manifesnya diterbitkan di Google Play. Pengguna perangkat Android 1.6 (API Level 4) men-download dan menginstal aplikasi. Setelah beberapa minggu, pengguna menerima update sistem over the air (OTA) ke Android 2.0 (API Level 5). Setelah update diiinstal, sistem akan memeriksa maxSdkVersion aplikasi dan berhasil memvalidasi ulang aplikasi. Aplikasi berfungsi normal. Namun, beberapa waktu kemudian, perangkat menerima update sistem lainnya, kali ini ke Android 2.0.1 (API Level 6). Setelah update, sistem tidak dapat lagi memvalidasi ulang aplikasi, karena API Level (6) sistem itu sendiri sekarang lebih tinggi dari level maksimum yang didukung oleh aplikasi (5). Sistem mencegah aplikasi ini terlihat oleh pengguna, dengan menghapusnya dari perangkat.

Peringatan: Mendeklarasikan atribut ini tidak disarankan. Pertama, tidak perlu menyetel atribut untuk memblokir deployment aplikasi Anda ke versi platform Android baru ketika aplikasi dirilis. Versi platform baru telah dirancang agar sepenuhnya kompatibel dengan versi sebelumnya. Aplikasi Anda seharusnya bekerja dengan baik pada versi baru, selama hanya menggunakan API standar dan mengikuti praktik terbaik pengembangan. Kedua, perhatikan bahwa dalam beberapa kasus, mendeklarasikan atribut dapat menyebabkan aplikasi Anda dihapus dari perangkat pengguna setelah update sistem ke API Level yang lebih tinggi. Sebagian besar perangkat yang menginstal aplikasi Anda akan menerima update sistem over the air (OTA) secara berkala, sehingga Anda harus mempertimbangkan efeknya pada aplikasi sebelum menetapkan atribut ini.

Diperkenalkan di: API Level 4.

Versi Android mendatang (di atas Android 2.0.1) tidak akan lagi memeriksa atau menerapkan atribut maxSdkVersion selama penginstalan atau validasi ulang. Namun, Google Play akan melanjutkan penggunaan atribut tersebut sebagai filter, saat menampilkan ke pengguna aplikasi yang tersedia untuk didownload.

diperkenalkan di:

API Level 1

Apa itu API Level?

API Level adalah nilai integer yang secara unik mengidentifikasi revisi API framework yang ditawarkan oleh versi platform Android.

Platform Android menyediakan API framework yang dapat digunakan aplikasi untuk berinteraksi dengan sistem Android yang mendasarinya. API framework terdiri dari:

• Sekumpulan inti dari paket dan class
• Sekumpulan elemen dan atribut XML untuk mendeklarasikan file manifes
• Sekumpulan elemen dan atribut XML untuk mendeklarasikan dan mengakses sumber daya
• Sekumpulan Intent
• Sekumpulan izin yang dapat diminta aplikasi, serta penerapan izin yang dimasukkan ke dalam sistem

Setiap versi platform Android secara berurutan dapat berisi update untuk API framework aplikasi Android yang diberikannya.

Update untuk API framework sudah dirancang sehingga API baru tetap kompatibel dengan API versi sebelumnya. Artinya, sebagian besar perubahan API bersifat tambahan dan memperkenalkan fungsi baru atau pengganti. Karena sebagian dari API di-upgrade versinya, bagian yang lebih lama yang sudah diganti tidak digunakan lagi, tetapi tidak dihapus, sehingga aplikasi yang ada masih dapat menggunakannya. Dalam kasus yang sangat jarang terjadi, sebagian dari API dapat diubah atau dihapus, meskipun biasanya perubahan seperti itu hanya diperlukan untuk memastikan keandalan API dan aplikasi atau sistem keamanan. Semua bagian API lain dari revisi sebelumnya tetap dibawa dan digunakan tanpa modifikasi.

API framework yang diberikan platform Android ditentukan menggunakan ID integer yang disebut "API Level". Setiap versi platform Android mendukung persis satu API Level, meskipun dukungan bersifat implisit untuk semua API Level sebelumnya (sampai ke API Level 1). Rilis awal platform Android menyediakan API Level 1 dan rilis berikutnya secara bertahap menaikkan API Level.

Tabel di bawah ini menetapkan API Level yang didukung oleh setiap versi platform Android. Untuk informasi tentang jumlah relatif perangkat yang menjalankan setiap versi, lihat halaman dasbor Versi Platform.

Menggunakan API Level di Android

ID API Level mempunyai peranan penting dalam memastikan pengalaman terbaik bagi pengguna dan developer aplikasi:

• ID ini memungkinkan platform Android menjelaskan revisi API framework maksimum yang didukungnya
• ID ini memungkinkan aplikasi menjelaskan revisi API framework yang mereka butuhkan
• ID ini memungkinkan sistem menegosiasikan penginstalan aplikasi pada perangkat pengguna, sehingga versi aplikasi yang tidak-kompatibel tidak diinstal.

Setiap versi platform Android menyimpan ID API Level secara internal, dalam sistem Android itu sendiri.

Aplikasi dapat menggunakan elemen manifes yang disediakan oleh API framework — <uses-sdk> — untuk menjelaskan API Level minimum dan maksimum tempat aplikasi dapat berjalan, serta API Level pilihan yang dirancang untuk didukung aplikasi Elemen ini menawarkan tiga atribut utama:

• android:minSdkVersion — Menetapkan API Level minimum yang dapat menjadi tempat aplikasi dijalankan. Nilai defaultnya adalah "1".
• android:targetSdkVersion — Menetapkan API Level yang akan digunakan untuk menjalankan aplikasi yang didesain. Dalam beberapa kasus, hal ini memungkinkan aplikasi menggunakan elemen atau perilaku manifes yang didefinisikan dalam API Level target, bukan dibatasi pada penggunaan elemen atau perilaku manifes yang didefinisikan untuk API Level minimum.
• android:maxSdkVersion — Menetapkan API Level maksimum yang dapat menjadi tempat aplikasi berjalan. Penting: Baca dokumentasi <uses-sdk> sebelum menggunakan atribut ini.

Contohnya, untuk menentukan API Level sistem minimum yang dibutuhkan aplikasi untuk berjalan, aplikasi akan memasukkan elemen <uses-sdk> dengan atribut android:minSdkVersion di dalam manifesnya. Nilai android:minSdkVersion akan berupa integer yang sesuai dengan API Level versi platform Android awal yang dapat menjadi tempat aplikasi dijalankan.

Jika pengguna mencoba untuk menginstal aplikasi, atau memvalidasi ulang aplikasi setelah update sistem, sistem Android akan terlebih dahulu memeriksa atribut <uses-sdk> di dalam manifes aplikasi dan membandingkan nilainya terhadap API Level internalnya sendiri. Sistem mengizinkan penginstalan untuk dimulai hanya jika ketentuan ini terpenuhi:

• Jika atribut android:minSdkVersion dideklarasikan, nilainya harus kurang dari atau sama dengan integer API Level sistem. Jika tidak dideklarasikan, sistem akan berasumsi bahwa aplikasi membutuhkan API Level 1.
• Jika atribut android:maxSdkVersion dideklarasikan, nilainya harus sama atau lebih besar dari integer API Level sistem. Jika tidak dideklarasikan, sistem akan berasumsi bahwa aplikasi tidak memiliki API Level maksimum. Baca dokumentasi <uses-sdk> untuk informasi lebih lanjut cara sistem menangani atribut ini.

Jika dideklarasikan dalam manifes aplikasi, elemen <uses-sdk> mungkin terlihat seperti ini:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Alasan utama mengapa aplikasi mendeklarasikan API Level di android:minSdkVersion adalah untuk memberi tahu sistem Android bahwa aplikasi menggunakan API yang diperkenalkan dalam API Level yang ditetapkan. Jika diinstal pada platform dengan API Level yang lebih rendah, aplikasi tersebut akan error pada saat run-time ketika mencoba mengakses API yang tidak ada. Sistem mencegah hasil seperti itu dengan tidak mengizinkan aplikasi diinstal jika API Level terendah yang diperlukan lebih tinggi daripada versi platform pada perangkat target.

Contohnya, paket android.appwidget diperkenalkan dengan API Level 3. Jika menggunakan API tersebut, aplikasi harus mendeklarasikan atribut android:minSdkVersion dengan nilai "3". Aplikasi kemudian dapat diinstal pada platform seperti Android 1.5 (API Level 3) dan Android 1.6 (API Level 4), namun tidak pada platform Android 1.1 (API Level 2) dan Android 1.0 (API Level 1).

Untuk informasi selengkapnya tentang cara menentukan persyaratan API Level aplikasi, lihat bagian <uses-sdk> dari dokumentasi file manifes.

Pertimbangan Pengembangan

Bagian di bawah ini menyediakan informasi yang berkaitan dengan API level yang harus Anda pertimbangkan ketika mengembangkan aplikasi.

Kompatibilitas dengan versi baru aplikasi

Aplikasi Android biasanya kompatibel dengan versi yang lebih baru dengan versi baru platform Android.

Karena hampir semua perubahan pada API framework bersifat tambahan, aplikasi Android yang dikembangkan menggunakan versi API tertentu (sebagaimana ditetapkan oleh API Level-nya) akan kompatibel dengan versi yang lebih baru dengan versi platform Android berikutnya dan API level yang lebih tinggi. Aplikasi seharusnya dapat berjalan di semua versi platform Android yang lebih baru, kecuali dalam kasus-kasus terisolasi ketika aplikasi menggunakan bagian API yang kemudian dihapus karena beberapa alasan.

Kompatibilitas dengan versi baru ini penting karena banyak perangkat yang didukung Android menerima update sistem over-the-air (OTA). Pengguna mungkin menginstal aplikasi dan berhasil menggunakannya, kemudian menerima update OTA ke versi platform Android yang baru. Setelah update terinstal, aplikasi akan berjalan di versi run-time lingkungan yang baru, tetapi yang memiliki API dan kemampuan sistem yang diandalkan aplikasi.

Dalam beberapa kasus, perubahan di bawah API, seperti perubahan dalam sistem dasar, dapat memengaruhi aplikasi Anda ketika dijalankan di lingkungan baru. Sehingga sebagai developer aplikasi, Anda harus memahami akan seperti apa tampilan dan perilaku aplikasi di masing-masing lingkungan sistem. Untuk membantu Anda menguji aplikasi di berbagai versi platform Android, Android SDK memuat beberapa platform yang dapat Anda download. Setiap platform berisi gambar sistem kompatibel yang dapat Anda jalankan di AVD, untuk menguji aplikasi Anda.

Kompatibilitas mundur aplikasi

Aplikasi Android tidak selalu kompatibel dengan versi platform Android yang lebih lama dari versi kompilasinya.

Setiap versi platform Android yang baru dapat memuat API framework baru, seperti memberikan akses aplikasi ke kemampuan platform baru atau mengganti bagian API yang ada. API baru dapat diakses oleh aplikasi ketika berjalan di platform baru dan, seperti disebutkan di atas, saat berjalan di versi platform yang lebih baru, seperti yang ditetapkan oleh API Level. Sebaliknya, karena versi platform sebelumnya tidak memuat API baru, aplikasi yang menggunakan API baru tidak dapat berjalan di platform tersebut.

Meskipun tidak mungkin perangkat Android akan turun versi ke versi platform sebelumnya, penting untuk menyadari bahwa mungkin saja ada banyak perangkat lain di kolom yang menjalankan versi platform sebelumnya. Bahkan di antara perangkat yang menerima update OTA, beberapa mungkin tertinggal dan mungkin tidak menerima update untuk jangka waktu lama.

Memilih versi platform dan API Level

Ketika mengembangkan aplikasi, Anda harus memilih versi platform tempat Anda akan mengompilasi aplikasi. Biasanya, Anda harus mengompilasi aplikasi terhadap versi serendah mungkin dari platform yang didukung aplikasi Anda.

Anda dapat menentukan versi platform serendah mungkin dengan mengompilasi aplikasi terhadap target versi yang lebih rendah secara berurutan. Setelah menentukan versi terendah, Anda harus membuat AVD menggunakan versi platform yang sesuai (dan API Level) serta menguji aplikasi Anda secara menyeluruh. Pastikan untuk mendeklarasikan atribut android:minSdkVersion dalam manifes aplikasi dan menetapkan nilainya ke API Level versi platform.

Mendeklarasikan API Level minimum

Jika Anda mem-build aplikasi yang menggunakan API atau fitur sistem yang diperkenalkan dalam versi platform terbaru, Anda harus menetapkan atribut android:minSdkVersion ke API Level dari versi platform terbaru. Ini memastikan bahwa pengguna hanya dapat menginstal aplikasi Anda jika perangkat pengguna menjalankan versi platform Android yang kompatibel. Pada akhirnya, ini memastikan bahwa aplikasi Anda dapat berfungsi dengan baik pada perangkat pengguna.

Jika aplikasi Anda menggunakan API yang diperkenalkan dalam versi platform terbaru tetapi tidak mendeklarasikan atribut android:minSdkVersion, aplikasi dapat berjalan dengan baik pada perangkat yang menjalankan versi platform terbaru, tetapi tidak pada perangkat yang menjalankan versi platform yang lebih lama. Dalam kasus yang terakhir, aplikasi akan mengalami error saat runtime ketika mencoba untuk menggunakan API yang tidak ada pada versi yang lebih lama.

Pengujian terhadap API Level yang lebih tinggi

Setelah mengompilasi aplikasi, pastikan Anda mengujinya pada platform yang ditetapkan dalam atribut android:minSdkVersion aplikasi. Untuk melakukannya, buat AVD yang menggunakan versi platform yang diperlukan oleh aplikasi Anda. Selain itu, guna memastikan kompatibilitas dengan versi baru, Anda harus menjalankan dan menguji aplikasi pada semua platform yang menggunakan API Level lebih tinggi daripada yang digunakan oleh aplikasi Anda.

Android SDK berisi beberapa versi platform yang dapat Anda gunakan, termasuk versi terbaru, dan menyediakan alat updater yang dapat Anda gunakan untuk men-download versi platform lain jika diperlukan.

Untuk mengakses updater, gunakan alat command line android yang berada di direktori <sdk>/tools. Anda dapat meluncurkan SDK updater dengan menjalankan android sdk. Anda juga dapat mengklik dua kali file android.bat (Windows) atau android (OS X/Linux).

Untuk menjalankan aplikasi terhadap versi platform berbeda dalam emulator, buat AVD untuk masing-masing versi platform yang ingin Anda uji. Untuk informasi selengkapnya tentang AVD, lihat Membuat dan Mengelola Perangkat Virtual. Jika Anda menggunakan perangkat fisik untuk pengujian, pastikan bahwa Anda mengetahui API Level platform Android yang dijalankan. Lihat tabel di bagian atas dokumen ini untuk melihat daftar versi platform dan API Level mereka.

Memfilter Dokumentasi Referensi dengan API Level

Halaman dokumentasi referensi platform Android menawarkan kontrol "API Level" di sisi kiri atas setiap halaman. Anda dapat menggunakan kontrol tersebut agar hanya menampilkan dokumentasi untuk bagian API yang benar-benar dapat diakses oleh aplikasi Anda, berdasarkan API Level yang ditetapkannya dalam atribut android:minSdkVersion file manifesnya.

Untuk menggunakan pemfilteran, pilih kotak centang untuk mengaktifkan pemfilteran, tepat di bawah kotak penelusuran halaman. Kemudian setel kontrol "Filter menurut API Level" ke API Level yang sama seperti yang ditetapkan oleh aplikasi Anda. Perhatikan bahwa API yang diperkenalkan di API Level berikutnya berwarna abu-abu dan materinya disamarkan, karena API tersebut tidak dapat diakses oleh aplikasi Anda.

Pemfilteran menurut API Level dalam dokumentasi tidak akan menyediakan tampilan mengenai apa yang baru atau diperkenalkan di setiap API Level — tetapi hanya menyediakan cara melihat seluruh API yang terkait dengan API Level yang diberikan, sekaligus mengecualikan elemen API yang diperkenalkan di API Level berikutnya.

Jika Anda memutuskan bahwa Anda tidak ingin memfilter dokumentasi API, cukup nonaktifkan fitur tersebut menggunakan kotak centang. Secara default, pemfilteran API Level dinonaktifkan, sehingga Anda dapat melihat seluruh API framework, terlepas dari API Level.

Perhatikan juga bahwa dokumentasi referensi untuk elemen API individual menetapkan API Level yang memperkenalkan setiap elemen. API Level untuk paket dan class ditentukan sebagai "Sejak <api level>" di pojok kanan atas area konten di setiap halaman dokumentasi. API Level bagi anggota kelas ditetapkan dalam header deskripsi mendetail, di margin kanan.