Google Play menggunakan atribut <uses-sdk>
yang dideklarasikan dalam manifes aplikasi untuk mengecualikan aplikasi Anda 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 menggunakan bilangan bulat level API. Level API yang diperlihatkan oleh aplikasi dibandingkan dengan level API dari sistem Android yang disediakan dan dapat bervariasi di antara perangkat Android.
Meskipun dinamai demikian, elemen ini digunakan untuk menentukan level API, bukan nomor versi software development kit (SDK) atau platform Android. Level API selalu berupa bilangan bulat tunggal. Anda tidak dapat memperoleh level API dari nomor versi Android terkait. Misalnya, versi ini tidak sama dengan versi utama atau jumlah dari versi utama dan minor.
Baca juga dokumen tentang pembuatan versi aplikasi Anda.
- atribut:
-
android:minSdkVersion
- bilangan bulat yang menentukan level API minimum yang diperlukan
agar aplikasi dapat berjalan. Sistem Android akan mencegah pengguna menginstal
aplikasi jika level API sistem lebih rendah dari nilai yang ditetapkan dalam
atribut ini. Selalu deklarasikan atribut ini.
Perhatian: Jika Anda tidak mendeklarasikan atribut ini, sistem akan mengasumsikan nilai default "1", yang menunjukkan bahwa aplikasi Anda kompatibel dengan semua versi Android. Jika bukan, dan Anda tidak mendeklarasikan
minSdkVersion
yang benar, saat diinstal pada sistem dengan level API yang tidak kompatibel, aplikasi akan error selama runtime ketika mencoba mengakses API yang tidak tersedia. Karena alasan ini, pastikan untuk mendeklarasikan level API yang tepat di dalam atributminSdkVersion
. android:targetSdkVersion
- Bilangan bulat yang menentukan level API target aplikasi. Jika tidak ditetapkan, 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 aplikasi Anda jika versi target yang lebih baru. Aplikasi masih dapat berjalan pada versi yang lebih rendah (hingga
minSdkVersion
).Karena Android berkembang dengan setiap versi baru, beberapa perilaku dan bahkan tampilan dapat berubah. Namun, jika level API platform lebih tinggi dari versi yang dideklarasikan oleh
targetSdkVersion
aplikasi Anda, sistem mungkin mengaktifkan perilaku kompatibilitas sehingga 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 Holo untuk aplikasi Anda saat berjalan pada Android 3.0 atau versi lebih tinggi dan juga menonaktifkan mode kompatibilitas layar ketika berjalan pada layar yang lebih besar karena level API 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 bersangkutan dalam referensi
Build.VERSION_CODES
.Untuk menjaga kesesuaian aplikasi dengan setiap rilis Android, naikkan nilai atribut ini untuk mencocokkan dengan level API terbaru, lalu uji aplikasi Anda secara menyeluruh pada versi platform yang sesuai.
Diperkenalkan di: level API 4
- Bilangan bulat yang menentukan level API maksimum tempat
aplikasi dirancang untuk berjalan.
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 level API 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 diterbitkan di Google Play jika mendeklarasikan
maxSdkVersion="5"
dalam manifesnya. Pengguna perangkat Android 1.6 (level API 4) men-download dan menginstal aplikasi. Setelah beberapa minggu, pengguna menerima update sistem over the air (OTA) ke Android 2.0 (level API 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 (level API 6). Setelah update, sistem tidak dapat lagi memvalidasi ulang aplikasi, karena level API (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: Anda sebaiknya tidak mendeklarasikan atribut ini. Pertama, tidak perlu menetapkan atribut untuk memblokir deployment aplikasi Anda ke versi platform Android baru ketika aplikasi dirilis. Versi platform baru telah dirancang agar sepenuhnya kompatibel dengan versi lama. Aplikasi Anda berfungsi dengan baik pada versi baru, asalkan menggunakan API standar dan mengikuti praktik terbaik pengembangan. Kedua, dalam beberapa kasus, mendeklarasikan atribut dapat menyebabkan aplikasi Anda dihapus dari perangkat pengguna setelah update sistem ke level API yang lebih tinggi. Sebagian besar perangkat yang menginstal aplikasi Anda akan menerima update sistem over the air (OTA) secara berkala. Jadi, pertimbangkan efeknya pada aplikasi sebelum menetapkan atribut ini.
Diperkenalkan di: level API 4
Beberapa versi Android (di atas Android 2.0.1) tidak memeriksa atau menerapkan atributmaxSdkVersion
selama penginstalan atau validasi ulang. Namun, Google Play akan terus menggunakan atribut sebagai filter saat menampilkan aplikasi yang tersedia untuk didownload kepada pengguna.
- diperkenalkan di:
- Level API 1
Apa itu level API?
Level API adalah nilai bilangan bulat 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 peningkatan platform Android dapat berisi update untuk API framework aplikasi Android yang diberikannya.
Update untuk API framework sudah dirancang agar API baru tetap kompatibel dengan 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 dan sudah diganti tidak digunakan lagi, tetapi tidak dihapus, sehingga aplikasi yang ada masih dapat menggunakannya.
Dalam kasus yang sangat jarang terjadi, sebagian dari API diubah atau dihapus. Namun, perubahan seperti itu biasanya hanya diperlukan untuk mendukung keandalan API dan aplikasi atau sistem keamanan. Semua bagian lain dari API di revisi sebelumnya tetap digunakan tanpa modifikasi.
API framework yang diberikan platform Android ditetapkan menggunakan ID bilangan bulat yang disebut level API. Setiap versi platform Android mendukung persis satu level API meskipun dukungan bersifat implisit untuk semua level API sebelumnya (sampai ke level API 1). Rilis awal platform Android menyediakan level API 1, sedangkan rilis berikutnya secara bertahap menaikkan level API.
Tabel berikut menetapkan level API yang didukung oleh setiap versi platform Android. Untuk informasi tentang jumlah relatif perangkat yang menjalankan setiap versi, lihat Dasbor distribusi.
Menggunakan level API di Android
ID level API berperan penting dalam membantu memastikan kemungkinan pengalaman untuk 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 level API secara internal dalam sistem Android itu sendiri.
Aplikasi dapat menggunakan elemen manifes yang disediakan oleh API
framework—<uses-sdk>
—untuk menjelaskan level API minimum dan maksimum tempat aplikasi dapat berjalan, serta level API pilihan yang
dirancang untuk didukung aplikasi. Elemen ini menawarkan tiga atribut utama:
android:minSdkVersion
: level API minimum tempat aplikasi dapat dijalankan. Nilai defaultnya adalah "1".android:targetSdkVersion
: level API tempat aplikasi dirancang untuk dijalankan. Dalam beberapa kasus, hal ini memungkinkan aplikasi menggunakan elemen atau perilaku manifes yang didefinisikan dalam level API target, bukan dibatasi pada penggunaan elemen atau perilaku manifes yang didefinisikan untuk level API minimum.android:maxSdkVersion
: level API maksimum tempat aplikasi dapat berjalan. Penting: Baca informasi tentang atribut ini di halaman ini sebelum menggunakannya.
Contohnya, untuk menentukan level API sistem minimum yang dibutuhkan aplikasi
untuk berjalan, aplikasi akan memasukkan elemen
<uses-sdk>
dengan atribut android:minSdkVersion
di dalam manifesnya. Nilai android:minSdkVersion
berupa bilangan bulat
yang sesuai dengan level API versi platform Android
awal tempat aplikasi dapat 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 level API internalnya sendiri. Sistem mengizinkan
penginstalan dimulai, hanya jika ketentuan ini terpenuhi:
- Jika atribut
android:minSdkVersion
dideklarasikan, nilainya harus kurang dari atau sama dengan bilangan bulat level API sistem. Jika tidak dideklarasikan, sistem akan berasumsi bahwa aplikasi membutuhkan level API 1. - Jika atribut
android:maxSdkVersion
dideklarasikan, nilainya harus sama atau lebih besar dari bilangan bulat level API sistem. Jika tidak dideklarasikan, sistem akan berasumsi bahwa aplikasi tidak memiliki level API maksimum. Baca deskripsi atribut ini untuk mengetahui informasi selengkapnya tentang cara sistem menanganinya.
Jika dideklarasikan dalam manifes aplikasi, elemen <uses-sdk>
mungkin terlihat seperti ini:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
Alasan utama aplikasi mendeklarasikan level API di
android:minSdkVersion
adalah untuk memberi tahu sistem Android bahwa
aplikasi menggunakan API yang diperkenalkan dalam level API yang ditentukan.
Jika aplikasi diinstal pada platform dengan level API yang lebih rendah, aplikasi tersebut akan error pada saat runtime ketika mencoba mengakses API yang tidak ada. Sistem mencegah hasil ini dengan tidak mengizinkan penginstalan aplikasi jika level API terendah yang diperlukan lebih tinggi daripada versi platform di perangkat target.
Pertimbangan pengembangan
Bagian berikut ini menyediakan informasi terkait level API yang perlu Anda pertimbangkan ketika mengembangkan aplikasi.
Kompatibilitas dengan versi baru aplikasi
Aplikasi Android biasanya kompatibel 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 level API-nya, akan kompatibel dengan versi platform Android yang lebih baru dan level API yang lebih tinggi. Aplikasi 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 runtime baru lingkungan, tetapi masih memiliki API dan kemampuan sistem yang diandalkan aplikasi.
Perubahan di bawah API, seperti perubahan dalam sistem dasar, dapat memengaruhi aplikasi Anda saat dijalankan di lingkungan baru. Anda, sebagai developer aplikasi, harus memahami tampilan dan perilaku aplikasi di setiap 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 dengan versi lama 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 ketika berjalan di versi platform yang lebih baru, seperti yang ditetapkan oleh level API. Namun, karena versi platform sebelumnya tidak memuat API baru, aplikasi yang menggunakan API baru tidak dapat dijalankan di platform tersebut.
Meskipun perangkat Android mungkin tidak akan didowngrade 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 level API
Saat mengembangkan aplikasi, Anda memilih versi platform tempat Anda mengompilasi aplikasi. Secara umum, kompilasi aplikasi Anda terhadap versi platform yang serendah mungkin yang dapat 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, buat AVD menggunakan versi platform
dan level API yang sesuai, lalu uji aplikasi Anda secara menyeluruh. Pastikan untuk mendeklarasikan
atribut android:minSdkVersion
dalam manifes aplikasi dan
menetapkan nilainya ke level API versi platform.
Mendeklarasikan level API minimum
Jika Anda mem-build aplikasi yang menggunakan API atau fitur sistem yang diperkenalkan dalam
versi platform terbaru, tetapkan
atribut android:minSdkVersion
ke level API dari versi
platform terbaru. Hal ini membuat pengguna hanya dapat menginstal aplikasi
Anda jika perangkat mereka menjalankan versi platform Android yang
kompatibel. Pada akhirnya, hal ini membantu memastikan 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 menggunakan API yang tidak
ada pada versi yang lebih lama.
Menguji level API 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, untuk memeriksa kompatibilitas maju, jalankan
dan uji aplikasi pada semua platform yang menggunakan level API yang 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 mendownload 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 setiap 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 Anda mengetahui level API platform Android yang dijalankan. Lihat tabel dalam dokumen ini untuk melihat daftar versi platform dan level API-nya.
Memfilter dokumentasi referensi dengan level API
Halaman dokumentasi referensi platform Android menawarkan
kontrol "level API" 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 level API yang ditetapkannya dalam
atribut android:minSdkVersion
file manifesnya.
Untuk menggunakan pemfilteran, pilih level API yang ditentukan oleh aplikasi Anda dari menu. API yang diperkenalkan dalam level API berikutnya berwarna abu-abu dan materinya disembunyikan, karena tidak dapat diakses oleh aplikasi Anda.
Pemfilteran menurut level API dalam dokumentasi tidak menyediakan tampilan mengenai apa yang baru atau diperkenalkan di setiap level API, tetapi hanya menyediakan cara untuk melihat seluruh API yang terkait dengan level API tertentu, sekaligus mengecualikan elemen API yang diperkenalkan di level API berikutnya.
Untuk kembali melihat dokumentasi lengkap, pilih REL di bagian atas menu level API. Secara default, pemfilteran level API dinonaktifkan sehingga Anda dapat melihat seluruh API framework, terlepas dari level API.
Dokumentasi referensi untuk setiap elemen API menetapkan level API yang memperkenalkan setiap elemen. Level API untuk paket dan class ditentukan sebagai "Ditambahkan di level API" di pojok kanan atas area konten pada setiap halaman dokumentasi. Level API bagi anggota class ditetapkan dalam header deskripsi mendetail, di margin kanan.