<uses-sdk>

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 atribut minSdkVersion.

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 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 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

android:maxSdkVersion

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 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 (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 atribut maxSdkVersion 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:

API level 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 mempunyai peranan penting dalam membantu 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 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.