Pratinjau Developer Android 11 kedua kini tersedia, uji dan sampaikan masukan Anda.

<uses-sdk>

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.

sintaks:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
dimuat dalam:
<manifest>
keterangan:

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 menetapkan API Level, bukan nomor versi SDK (software development kit) atau platform Android. API Level selalu berupa integer tunggal. Anda tidak bisa memperoleh API Level dari nomor versi Android terkait (misalnya, ini tidak sama dengan versi mayor atau jumlah dari versi mayor dan minor).

Baca juga dokumen tentang Menetapkan Versi Aplikasi Anda.

atribut:
android:minSdkVersion
Integer menunjuk API Level minimum yang diperlukan agar aplikasi bisa 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 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 pada API Level 3) dan Anda belum mendeklarasikan minSdkVersion yang tepat, maka ketika diinstal pada sistem dengan API Level kurang dari 3, aplikasi akan mogok saat runtime ketika mencoba untuk mengakses API yang tidak tersedia. Karena hal ini, pastikan untuk mendeklarasikan API Level yang tepat dalam atribut minSdkVersion.

android:targetSdkVersion
Integer yang menunjuk API Level yang ditargetkan aplikasi. Jika tidak disetel, nilai default adalah sama dengan yang diberikan kepada 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-maju aplikasi Anda dengan versi target. Aplikasi masih bisa berjalan pada versi yang lebih lama (sampai ke minSdkVersion).

Karena Android berkembang dengan setiap versi baru, beberapa perilaku dan bahkan tampilan bisa saja berubah. Namun, jika API level platform lebih tinggi dari versi yang dideklarasikan oleh targetSdkVersion aplikasi Anda, sistem bisa mengaktifkan perilaku kompatibilitas untuk memastikan bahwa aplikasi Anda terus bekerja seperti yang diharapkan. Anda bisa menonaktifkan perilaku kompatibilitas seperti ini dengan menetapkan targetSdkVersion untuk mencocokkan dengan API level tempat platform tersebut berjalan. Misalnya, 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 menonaktifkan mode 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 bisa 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 secara menyeluruh pada versi platform yang sesuai.

Diperkenalkan dalam: API Level 4

android:maxSdkVersion
Integer menunjuk API Level maksimum yang akan digunakan untuk menjalankan aplikasi yang didesain.

Pada 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, maka sistem tidak akan mengizinkan aplikasi diinstal. Jika terjadi validasi-ulang setelah update sistem, aplikasi Anda akan langsung dihapus dari perangkat.

Untuk menggambarkan bagaimana atribut ini bisa memengaruhi aplikasi Anda setelah update sistem, pertimbangkan contoh berikut:

Sebuah aplikasi mendeklarasikan maxSdkVersion="5" dalam manifesnya dan diterbitkan di Google Play. Pengguna perangkat Android 1.6 (API Level 4) mendownload dan menginstal aplikasi. Setelah beberapa minggu, pengguna menerima update sistem melalui udara ke Android 2.0 (API Level 5). Setelah update terinstal, sistem akan memeriksa maxSdkVersion aplikasi dan berhasil memvalidasi-ulang aplikasi. Aplikasi berfungsi normal. Namun, beberapa waktu kemudian, perangkat menerima update sistem lain, kali ini ke Android 2.0.1 (API Level 6). Setelah update, sistem tidak bisa 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 penerapan aplikasi Anda ke versi platform Android baru ketika aplikasi dirilis. Versi platform baru sudah dirancang untuk bisa kompatibel-mundur sepenuhnya. Aplikasi Anda seharusnya bekerja dengan baik pada versi baru, asalkan aplikasi hanya menggunakan API standar dan mengikuti praktik terbaik pengembangan. Kedua, perhatikan bahwa dalam beberapa kasus, mendeklarasikan atribut bisa 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 secara periodik melalui udara, sehingga Anda harus mempertimbangkan efeknya pada aplikasi sebelum menetapkan atribut ini.

Diperkenalkan dalam: API Level 4

Versi Android mendatang (di atas Android 2.0.1) tidak akan lagi memeriksa atau memberlakukan 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 dalam:
API Level 1

Apa yang dimaksud 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 bisa digunakan aplikasi untuk berinteraksi dengan sistem Android yang mendasarinya. API framework terdiri dari:

  • Satu set inti dari paket dan kelas
  • Satu set elemen dan atribut XML untuk mendeklarasikan file manifes
  • Satu set elemen dan atribut XML untuk mendeklarasikan dan mengakses sumber daya
  • Satu set Intent
  • Serangkaian izin yang bisa diminta aplikasi, serta pemberlakuan izin yang dimasukkan ke dalam sistem

Setiap versi platform Android secara berurutan bisa berisi pembaruan 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 fungsionalitas baru atau pengganti. Karena sebagian dari API ditingkatkan versinya, bagian lama yang sudah diganti dan tidak digunakan lagi namun tidak dihapus, sehingga aplikasi yang ada masih bisa menggunakannya. Dalam kasus yang sangat jarang terjadi, sebagian dari API bisa diubah atau dihapus, meskipun biasanya perubahan seperti itu hanya diperlukan untuk memastikan ketangguhan 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 ditetapkan menggunakan identifier 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.

Versi PlatformAPI LevelVERSION_CODECatatan
Android 10.0 29 Q Sorotan Platform
Android 9 28 P Sorotan Platform
Android 8.1 27 O_MR1 Sorotan Platform
Android 8.0 26 O Sorotan Platform
Android 7.1.1
Android 7.1
25 N_MR1 Sorotan Platform
Android 7.0 24 N Sorotan Platform
Android 6.0 23 M Sorotan Platform
Android 5.1 22 LOLLIPOP_MR1 Sorotan Platform
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat untuk Perangkat Wearable Saja
Android 4.4 19 KITKAT Sorotan Platform
Android 4.3 18 JELLY_BEAN_MR2 Sorotan Platform
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 Sorotan Platform
Android 4.1, 4.1.1 16 JELLY_BEAN Sorotan Platform
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Sorotan Platform
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 Sorotan Platform
Android 3.0.x 11 HONEYCOMB Sorotan Platform
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Sorotan Platform
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Sorotan Platform
Android 2.1.x 7 ECLAIR_MR1 Sorotan Platform
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Sorotan Platform
Android 1.5 3 CUPCAKE Sorotan Platform
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Menggunakan API Level di Android

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

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

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

Aplikasi bisa menggunakan elemen manifes yang disediakan oleh API framework — <uses-sdk> — untuk mendeskripsikan API Level minimum dan maksimum aplikasi bisa berjalan, serta API Level disarankan yang didukung. Elemen ini menawarkan tiga atribut utama:

  • android:minSdkVersion — Menetapkan API Level minimum yang bisa menjadi tempat aplikasi dijalankan. Nilai default-nya 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 bisa menjadi tempat aplikasi dijalankan. Penting: Baca dokumen <uses-sdk> sebelum menggunakan atribut ini.

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

Jika pengguna mencoba untuk memasang aplikasi, atau memvalidasi-ulang suatu aplikasi setelah update sistem, sistem Android akan terlebih dahulu memeriksa atribut <uses-sdk> 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 selengkapnya tentang bagaimana sistem menangani atribut ini.

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

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

Alasan utama kenapa 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 aplikasi, entah bagaimana, diinstal pada platform dengan API Level yang lebih rendah, maka aplikasi tersebut akan crash pada saat run-time ketika mencoba mengakses API yang tidak ada. Sistem mencegah hasil seperti itu dengan tidak mengizinkan aplikasi diinstal jika Level API terendah yang diperlukan lebih tinggi daripada versi platform pada perangkat target.

Misalnya, paket android.appwidget diperkenalkan dengan API Level 3. Jika sebuah aplikasi menggunakan API tersebut, aplikasi harus mendeklarasikan atribut android:minSdkVersion dengan nilai "3". Aplikasi kemudian bisa diinstal pada platform seperti Android 1.5 (API Level3) 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 sebuah aplikasi, lihat bagian <uses-sdk> dari dokumentasi file manifes.

Pertimbangan Development

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

Kompatibilitas maju aplikasi

Aplikasi Android biasanya kompatibel-maju dengan versi baru platform Android.

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

Kompatibilitas-maju ini penting karena banyak perangkat Androidmenerima udara sistem melalui udara atau over-the-air (OTA). Pengguna mungkin memasang aplikasi Anda dan berhasil menggunakannya, kemudian menerima update OTA ke versi platform Android yang baru. Setelah update terinstal, aplikasi Anda akan dijalankan dalam versi waktu proses lingkungan yang baru, namun yang memiliki API dan kemampuan sistem yang dipercaya oleh aplikasi.

Dalam beberapa kasus, perubahan di bawah API, seperti perubahan dalam sistem dasar, bisa memengaruhi aplikasi Anda ketika dijalankan di lingkungan baru. Untuk alasan tersebut, penting bagi Anda, sebagai developer aplikasi, untuk memahami bagaimana aplikasi akan terlihat dan berperilaku di masing-masing lingkungan sistem. Untuk membantu Anda menguji aplikasi pada berbagai versi platform Android, Android SDK memuat beberapa platform yang bisa Anda download. Setiap platform memuat gambar sistem kompatibel yang bisa dijalankan dalam AVD, untuk menguji aplikasi Anda.

Kompatibilitas mundur aplikasi

Aplikasi Android belum tentu kompatibel mundur dengan versi platform Android yang lebih lama daripada versi yang mereka kompilasi.

Masing-masing versi platform Android yang baru bisa memuat API framework baru, seperti memberikan akses aplikasi ke kemampuan platform baru atau mengganti bagian API yang ada. API baru bisa diakses oleh aplikasi ketika berjalan pada platform baru dan, seperti disebutkan di atas, saat berjalan pada 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 bisa dijalankan pada 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 pembaruan OTA, beberapa mungkin tertinggal dan mungkin tidak menerima pembaruan 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 bisa menentukan versi platform serendah mungkin dengan mengompilasi aplikasi terhadap target versi yang lebih rendah secara berurutan. Setelah menentukan versi terendah, Anda harus membuat sebuah 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 menyetel nilainya ke API Level versi platform.

Mendeklarasikan API Level minimum

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

Jika aplikasi Anda menggunakan API yang diperkenalkan dalam versi platform terbaru namun tidak mendeklarasikan atribut android:minSdkVersion, maka aplikasi bisa berjalan dengan baik pada perangkat yang menjalankan versi platform terbaru, tapi tidak pada perangkat yang menjalankan versi platform sebelumnya. Dalam kasus yang terakhir, aplikasi akan mogok saat runtime ketika mencoba untuk menggunakan API yang tidak ada pada versi sebelumnya.

Pengujian terhadap API Level yang lebih tinggi

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

Android SDK memuat beberapa versi platform yang bisa 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 baris-perintah android, yang terletak di direktori <sdk>/tools. Anda bisa meluncurkan SDK updater dengan menjalankan android sdk. Anda juga bisa mengklik dua kali pada 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 pada situs Android Developer menawarkan kontrol "Filter by API Level" di sebelah kanan atas dari setiap halaman. Anda bisa menggunakan kontrol tersebut agar hanya menampilkan dokumentasi untuk bagian API yang benar-benar bisa 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 telusur halaman. Kemudian setel kontrol "Filter by API Level" ke API Level yang sama sebagaimana ditetapkan oleh aplikasi Anda. Perhatikan bahwa API yang diperkenalkan dalam API Level berikutnya berwarna abu-abu dan materi mereka disembunyikan, karena mereka tidak bisa diakses oleh aplikasi Anda.

Pemfilteran dengan API Level dalam dokumentasi tidak menyediakan tampilan mengenai apa yang baru atau diperkenalkan pada masing-masing API Level — itu hanya menyediakan cara untuk 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 bisa melihat API framework penuh, terlepas dari API Level.

Perhatikan juga bahwa dokumentasi referensi untuk elemen API individual menetapkan API Level yang memperkenalkan setiap elemen. API Level untuk paket-paket dan kelas-kelas ditetapkan sebagai "Since <api level>" pada sudut kanan atas area materi pada setiap halaman dokumentasi. API Level bagi anggota kelas ditetapkan dalam header deskripsi mendetail, di margin kanan.