lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

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

Memungkinkan Anda untuk menyatakan kompatibilitas aplikasi dengan satu atau beberapa versi platform Android, dengan menggunakan integer API Level. API Level yang diperlihatkan oleh sebuah aplikasi akan dibandingkan dengan API Level dari sistem Android yang disediakan, yang mungkin berbeda pada berbagai 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).

Bacalah 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 memasang 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 dipasang pada sistem dengan API Level kurang dari 3, aplikasi akan mogok saat waktu proses 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 memasang aplikasi dan ketika memvalidasi-ulang aplikasi setelah pemutakhiran sistem. Dalam kedua kasus, jika atribut maxSdkVersion aplikasi lebih rendah dari API Level yang digunakan oleh sistem itu, maka sistem tidak akan mengizinkan aplikasi dipasang. Bila terjadi validasi-ulang setelah pemutakhiran sistem, aplikasi Anda akan langsung dibuang dari perangkat.

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

Sebuah aplikasi mendeklarasikan maxSdkVersion="5" dalam manifesnya dan diterbitkan di Google Play. Pengguna perangkat Android 1.6 (API Level 4) mengunduh dan memasang aplikasi. Setelah beberapa minggu, pengguna menerima pemutakhiran sistem melalui udara ke Android 2.0 (API Level 5). Setelah pemutakhiran dipasang, sistem akan memeriksa maxSdkVersion aplikasi dan berhasil memvalidasi-ulang aplikasi. Aplikasi berfungsi dengan normal. Namun, beberapa waktu kemudian, perangkat menerima pemutakhiran sistem lain, kali ini ke Android 2.0.1 (API Level 6). Setelah pemutakhiran, 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 mereka 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 development. Kedua, perhatikan bahwa dalam beberapa kasus, mendeklarasikan atribut bisa menyebabkan aplikasi Anda dihapus dari perangkat pengguna setelah pemutakhiran sistem ke API Level yang lebih tinggi. Sebagian besar perangkat yang memasang aplikasi Anda akan menerima pemutakhiran 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 pemasangan atau validasi-ulang. Namun, Google Play akan melanjutkan penggunaan atribut tersebut sebagai filter, saat menampilkan ke pengguna aplikasi yang tersedia untuk diunduh.
diperkenalkan dalam:
API Level 1

Apa yang dimaksud API Level?

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

Platform Android menyediakan API kerangka kerja yang bisa digunakan aplikasi untuk berinteraksi dengan sistem Android pokok. API kerangka kerja 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 Maksud
  • Satu set izin yang bisa diminta aplikasi, serta pemberlakuan izin yang dimasukkan ke dalam sistem

Setiap versi platform Android secara berurutan bisa berisi pembaruan untuk API kerangka kerja aplikasi Android yang diberikannya.

Pembaruan untuk API kerangka kerja 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 dibuang, sehingga aplikasi yang ada masih bisa menggunakannya. Dalam kasus yang sangat jarang terjadi, sebagian dari API bisa diubah atau dibuang, 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 kerangka kerja 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 laman dasbor Versi Platform.

Versi PlatformAPI LevelVERSION_CODECatatan
Android 7.0 24 N Unggulan Platform
Android 6.0 23 M Unggulan Platform
Android 5.1 22 LOLLIPOP_MR1 Unggulan Platform
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat Hanya untuk Perangkat yang Dapat Dikenakan
Android 4.4 19 KITKAT Unggulan Platform
Android 4.3 18 JELLY_BEAN_MR2 Unggulan Platform
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 Unggulan Platform
Android 4.1, 4.1.1 16 JELLY_BEAN Unggulan Platform
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Unggulan 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 Unggulan Platform
Android 3.0.x 11 HONEYCOMB Unggulan Platform
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Unggulan Platform
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Unggulan Platform
Android 2.1.x 7 ECLAIR_MR1 Unggulan Platform
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Unggulan Platform
Android 1.5 3 CUPCAKE Unggulan 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 kerangka kerja maksimum yang didukungnya
  • Identifier ini memungkinkan aplikasi menjelaskan revisi API kerangka kerja yang mereka butuhkan
  • Identifier ini memungkinkan sistem merundingkan pemasangan aplikasi pada perangkat pengguna, sehingga versi aplikasi yang tidak-kompatibel tidak dipasang.

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

Aplikasi bisa menggunakan elemen manifes yang disediakan oleh API kerangka kerja — <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: Bacalah 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.

Bila pengguna mencoba untuk memasang aplikasi, atau bila memvalidasi-ulang suatu aplikasi setelah pemutakhiran sistem, sistem Android akan terlebih dahulu memeriksa atribut <uses-sdk> dalam manifes aplikasi dan membandingkan nilainya terhadap API Level internalnya sendiri. Sistem mengizinkan pemasangan 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. Silakan baca dokumentasi <uses-sdk> untuk informasi selengkapnya tentang bagaimana sistem menangani atribut ini.

Bila 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 itu entah bagaimana dipasang pada platform dengan API Level yang lebih rendah, maka aplikasi akan mogok pada saat waktu proses ketika mencoba untuk mengakses API yang tidak ada. Sistem mencegah hal seperti ini dengan tidak mengizinkan aplikasi dipasang jika API Level terendah yang dibutuhkan 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 dipasang 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 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 kerangka kerja 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 dibuang karena beberapa alasan.

Kompatibilitas-maju ini penting karena banyak perangkat Android menerima pemutakhiran sistem melalui udara atau over-the-air (OTA). Pengguna mungkin memasang aplikasi Anda dan berhasil menggunakannya, kemudian menerima pembaruan OTA ke versi platform Android yang baru. Setelah pembaruan terpasang, 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 unduh. 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 kerangka kerja 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 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 membangun 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 memasang 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 waktu proses 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 mengunduh versi platform lain bila 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 mengeklik 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

Laman dokumentasi referensi pada situs Android Developer menawarkan kontrol "Filter by API Level" di sebelah kanan atas dari setiap laman. 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 manifes-nya.

Untuk menggunakan pemfilteran, pilih kotak centang untuk mengaktifkan pemfilteran, tepat di bawah kotak telusur laman. 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 kerangka kerja 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 laman dokumentasi. API Level bagi anggota kelas ditetapkan dalam header deskripsi mendetail, di margin kanan.