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 atributminSdkVersion
. 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 menetapkantargetSdkVersion
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 memeriksamaxSdkVersion
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 atributmaxSdkVersion
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.