Referensi API haptics Android

Bagian ini memberikan pengantar tentang berbagai API haptik yang tersedia di Android. Dokumen ini juga membahas kapan dan cara memeriksa dukungan perangkat yang diperlukan untuk memastikan efek haptik diputar sesuai keinginan Anda.

Ada beberapa cara berbeda untuk membuat efek haptik, dan penting untuk mempertimbangkan prinsip desain haptik Android saat memilih salah satu cara tersebut. Tabel berikut merangkum atribut tingkat tinggi dari setiap pendekatan:

  • Ketersediaan sangat penting saat merencanakan penggantian perilaku, dan harus digabungkan dengan memeriksa dukungan perangkat individual.
  • Haptik yang jelas memberikan sensasi yang tajam dan bersih yang tidak terlalu mengganggu pengguna.
  • Haptik kaya memiliki ekspresivitas yang lebih besar dan sering kali memerlukan hardware yang lebih kaya fitur.
Platform API Ketersediaan Hapus haptik Haptik kaya
HapticFeedbackConstants Android 1.5+
(per konstanta)
Predefined VibrationEffect Android 10+
Komposisi VibrationEffect (Pilihan) Android 16+ (Q4 2026)
Komposisi primitif VibrationEffect Android 11+ (per konstanta)
Getaran on/off, sekali sentuh, dan bentuk gelombang Android 1

Selain itu, API notifikasi, yang dijelaskan di halaman ini, memungkinkan Anda menyesuaikan efek haptik yang diputar untuk notifikasi masuk.

Halaman ini juga menjelaskan konsep tambahan yang mencakup platform API:

HapticFeedbackConstants

Class HapticFeedbackConstants menyediakan konstanta berbasis tindakan untuk memungkinkan aplikasi menambahkan respons haptik yang konsisten di seluruh pengalaman perangkat, bukan setiap aplikasi memiliki efek yang berbeda untuk tindakan umum.

Kompatibilitas dan persyaratan

Menggunakan metode View.performHapticFeedback dengan konstanta ini tidak memerlukan izin khusus untuk aplikasi. Metode ini tunduk pada properti View.hapticFeedbackEnabled, yang jika disetel ke false akan menonaktifkan semua panggilan respons haptik pada tampilan, termasuk yang default.Setelan terkait utama adalah properti View.hapticFeedbackEnabled, yang jika disetel ke false akan menonaktifkan semua panggilan respons haptik pada tampilan, termasuk yang default. Metode ini juga mematuhi setelan sistem pengguna untuk mengaktifkan feedback sentuh.

Satu-satunya pertimbangan kompatibilitas adalah tingkat SDK konstanta tertentu untuk tindakan.

Anda tidak perlu memberikan perilaku penggantian saat menggunakan HapticFeedbackConstants.

Penggunaan HapticsFeedbackConstants

Untuk mengetahui detail tentang penggunaan HapticFeedbackConstants, lihat Menambahkan umpan balik haptik ke peristiwa.

Ditentukan sebelumnya VibrationEffect

Class VibrationEffect menyediakan beberapa konstanta yang telah ditentukan sebelumnya seperti CLICK, TICK, dan DOUBLE_CLICK. Efek ini mungkin dioptimalkan untuk perangkat.

Kompatibilitas dan persyaratan

Memutar VibrationEffect apa pun memerlukan izin VIBRATE dalam manifes aplikasi.

Tidak perlu menyediakan perilaku penggantian saat menggunakan VibrationEffect yang telah ditentukan sebelumnya, karena konstanta yang tidak memiliki implementasi yang dioptimalkan untuk perangkat akan kembali ke penggantian platform standar.

API Vibrator.areEffectsSupported dan Vibrator.areAllEffectsSupported digunakan untuk menentukan apakah ada implementasi yang dioptimalkan untuk perangkat. Efek yang telah ditentukan sebelumnya tetap dapat digunakan tanpa penerapan yang dioptimalkan, dan menggunakan penggantian platform standar. Akibatnya, API areEffectsSupported ini hanya diperlukan jika aplikasi ingin mempertimbangkan apakah efek dioptimalkan untuk perangkat atau tidak.

Metode pemeriksaan efek dapat menampilkan salah satu dari tiga nilai:

Karena nilai UNKNOWN menunjukkan bahwa API pemeriksaan tidak tersedia, nilai ini biasanya ditampilkan untuk semua efek atau tidak sama sekali. Perangkat ini melakukan penggantian secara dinamis.

Penggunaan VibrationEffect standar

Untuk mengetahui detail tentang cara menggunakan VibrationEffect yang telah ditentukan, lihat Menggunakan VibrationEffect yang telah ditentukan untuk menghasilkan respons haptik.

Envelope VibrationEffect

Getaran berbasis amplop memungkinkan kontrol yang presisi atas amplitudo dan frekuensi getaran dari waktu ke waktu dengan menentukan urutan titik kontrol. Hal ini memungkinkan developer membuat pengalaman feedback haptik yang lebih kaya dan bernuansa. Getaran ini dapat dibuat menggunakan class BasicEnvelopeBuilder dan WaveformEnvelopeBuilder.

Kompatibilitas dan persyaratan

Untuk memutar efek getaran apa pun, aplikasi Anda harus mendeklarasikan izin VIBRATE dalam manifes aplikasi.

Untuk memeriksa dukungan efek amplop, panggil Vibrator.areEnvelopeEffectsSupported().

Basic Envelope Builder

Untuk menciptakan pengalaman haptik yang lancar dan mulus, efek amplop harus dimulai dan diakhiri dengan intensitas \( 0.0 \). API menerapkan hal ini dengan memperbaiki intensitas awal pada nol dan akan memunculkan pengecualian jika intensitas akhir bukan nol. Batasan ini mencegah efek dinamis yang tidak diinginkan dalam getaran karena diskontinuitas dalam amplitudo yang dapat berdampak negatif pada persepsi haptik pengguna.

Untuk memberikan rendering efek amplop yang konsisten di seluruh perangkat, framework mensyaratkan agar perangkat yang mendukung fitur ini dapat menangani durasi minimum 20 md di antara titik kontrol dan setidaknya 16 titik untuk efek amplop.

Waveform Envelope Builder

Framework tidak mengubah nilai frekuensi dan amplitudo yang diminta yang diberikan oleh developer. Namun, API juga memperbaiki amplitudo awal pada nol untuk membuat transisi yang lancar.

Untuk membantu Anda mengoptimalkan efek amplop bentuk gelombang aplikasi dan memberikan kompatibilitas di seluruh perangkat, Android menyediakan API untuk mengkueri kemampuan perangkat penting. Metode ini memberikan informasi tentang batasan perangkat, seperti durasi transisi maksimum dan minimum antara titik kontrol dan jumlah maksimum titik kontrol yang didukung untuk satu efek:

getMaxSize()
Mengambil jumlah maksimum titik kontrol yang didukung untuk efek amplop.
getMinControlPointDurationMillis()
Mengambil durasi minimum yang didukung, dalam milidetik, antara dua titik kontrol dalam efek amplop.
getMaxControlPointDurationMillis()
Mengambil durasi maksimum yang didukung, dalam milidetik, antara dua titik kontrol dalam efek amplop.
getMaxDurationMillis()
Mengambil durasi maksimum yang didukung untuk efek amplop, dalam milidetik.

Jika efek melampaui batasan perangkat—seperti mengizinkan terlalu banyak titik kontrol atau durasi yang melebihi maksimum—framework akan otomatis menyesuaikan efek agar sesuai dengan batas yang diizinkan. Proses penyesuaian ini mencoba mempertahankan maksud dan nuansa desain asli sebanyak mungkin.

Penggunaan Envelope VibrationEffects

Untuk mengetahui detail tentang cara membuat efek bentuk gelombang amplop, lihat membuat bentuk gelombang getaran dengan amplop.

Komposisi VibrationEffect

Mulai Android 16 (Q4 26), VibrationEffect.Builder adalah API pilihan untuk menyusun efek haptik yang kaya dan ekspresif dengan mengurutkan beberapa elemen haptik di sepanjang linimasa yang dirancang. Fitur ini menggantikan VibrationEffect.Composition dengan menawarkan penjadwalan yang ditambatkan ke linimasa, enkapsulasi atomik, dukungan peristiwa campuran (menggabungkan preset dan envelope), serta penggantian otomatis bawaan.

Elemen penyusun

Dengan builder, Anda dapat mengurutkan elemen haptik berikut:

  • VibrationEffect.Preset: Sensasi haptik yang telah ditentukan sebelumnya yang merepresentasikan pulsa pendek umum, seperti PRESET_CLICK, PRESET_TICK, dan PRESET_LOW_TICK. Preset menggantikan primitif pendek dari VibrationEffect.Composition API. Untuk efek yang lebih panjang, berkelanjutan, atau meningkat (sebelumnya ditangani oleh naik, turun, dan primitif lainnya), gunakan amplop (PWLE). Preset dapat diskalakan dari 0.0f hingga 1.0f menggunakan Preset.create(presetId, scale).
  • VibrationEffect.Envelope: Amplop linear sepotong-sepotong (PWLE) yang dibuat menggunakan BasicEnvelopeBuilder (dengan intensitas dan ketajaman) atau WaveformEnvelopeBuilder (dengan frekuensi dan amplitudo). Amplop dibuat menggunakan Envelope.create(builder).
  • VibrationEffect.Event: Peristiwa linimasa yang diambil dari VibrationEffect yang ada menggunakan getEvents(). Ini dapat ditambahkan dengan offset linimasa menggunakan addEvents(startTimeShiftMillis, events).

Penjadwalan dan validasi linimasa

Setiap elemen ditambahkan ke builder dengan startTimeMillis yang merepresentasikan selisih waktu (dalam milidetik) dari awal komposisi:

  • Validasi waktu pembuatan: Elemen harus ditambahkan dalam urutan waktu mulai yang meningkat secara ketat. Builder melakukan validasi upaya terbaik pada waktu build dengan memeriksa durasi minimum (seperti 1 mdtk untuk preset atau durasi yang diketahui untuk amplop). Jika tumpang-tindih terdeteksi pada waktu build, IllegalArgumentException akan ditampilkan.
  • Penyelarasan pengaturan waktu pemutaran: Framework ini memberikan dukungan pengaturan waktu upaya terbaik selama pemutaran. Jika peristiwa sebelumnya masih berjalan saat waktu mulai peristiwa terjadwal berikutnya tiba, framework akan otomatis mengalihkan peristiwa berikutnya ke slot paling awal yang tersedia. Hal ini mencegah peristiwa tumpang-tindih dalam pemutaran fisik sekaligus menjamin bahwa tidak ada peristiwa haptik yang terlewat.

Efek berulang

Efek berulang dapat ditambahkan ke komposisi menggunakan setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Setelah efek berulang dikonfigurasi, tidak ada elemen tambahan yang dapat ditambahkan ke builder.

Dukungan penggantian

Dukungan penggantian otomatis tingkat framework diaktifkan secara default untuk getaran yang dibuat oleh VibrationEffect.Builder:

  • Penggantian platform transparan: Jika perangkat tidak mendukung Preset yang diminta atau Envelope dasar, framework akan otomatis mengganti elemen yang tidak didukung dengan getaran yang didukung yang sesuai saat runtime dengan upaya terbaik. Aplikasi Anda tidak perlu memeriksa kemampuan perangkat secara manual (seperti isPresetSupported) sebelum memutar komposisi yang dibuat dengan VibrationEffect.Builder.
  • Pengecualian untuk WaveformEnvelopeBuilder: Efek amplop yang dibuat oleh WaveformEnvelopeBuilder (yang menentukan frekuensi fisik absolut dalam Hertz dan amplitudo dalam G) tidak memiliki dukungan penggantian otomatis. Karena PWLE lanjutan mengandalkan kurva frekuensi hardware tertentu (FOAM), menggantinya secara otomatis akan mengganggu maksud desain. Jika perangkat tidak mendukung efek PWLE atau frekuensi yang diminta, getaran tersebut tidak akan diputar. Untuk kompatibilitas universal, pilih BasicEnvelopeBuilder.

Penggunaan VibrationEffect.Builder

Untuk contoh kode tentang menyusun efek dengan VibrationEffect.Builder, lihat Membuat komposisi yang dijangkarkan linimasa dengan VibrationEffect.Builder.

Komposisi primitif VibrationEffect

Komposisi primitif VibrationEffect adalah efek getaran yang dibuat menggunakan VibrationEffect.startComposition API. API ini memungkinkan Anda membuat urutan elemen dasar.

Kompatibilitas dan persyaratan

Memutar VibrationEffect apa pun memerlukan izin VIBRATE dalam manifes aplikasi.

Memeriksa dukungan primitif

Oleh karena itu, saat menggunakan API VibrationEffect.Composition, Anda harus memeriksa dukungan per-primitif menggunakan Vibrator.arePrimitivesSupported atau Vibrator.areAllPrimitivesSupported sebelum memutar.

Dukungan per-primitif dapat diambil menggunakan metode Vibrator.arePrimitivesSupported. Atau, sekumpulan primitif dapat diperiksa bersama menggunakan metode Vibrator.areAllPrimitivesSupported - ini setara dengan AND-ing dukungan per-primitif.

Penggunaan komposisi primitif VibrationEffect

Untuk mengetahui detail tentang penggunaan komposisi primitif VibrationEffect, lihat Membuat komposisi primitif getaran.

Getaran on-off, one-shot, dan bentuk gelombang

Bentuk getaran tertua yang didukung di Android adalah pola getaran sederhana on-off dengan durasi yang dapat dikonfigurasi. API ini biasanya tidak selaras dengan prinsip desain Haptics karena dapat menghasilkan haptics yang bergetar; hindari API ini kecuali sebagai upaya terakhir.

Kasus penggunaan yang paling umum untuk getaran on-off adalah notifikasi, di mana, apa pun yang terjadi, beberapa getaran diinginkan. Getaran bentuk gelombang juga secara unik memungkinkan pola berulang tanpa batas, seperti yang mungkin Anda bayangkan untuk nada dering.

Pola sekali getar mengacu pada getaran sekali selama N milidetik.

Ada dua jenis pola bentuk gelombang:

  • Khusus pengaturan waktu. Jenis bentuk gelombang ini adalah deskripsi durasi alternatif yang dihabiskan saat tidak aktif, dan durasi yang dihabiskan saat aktif. Pengaturan waktu dimulai dengan durasi saat perangkat tidak digunakan. Akibatnya, pola bentuk gelombang sering kali dimulai dengan nilai nol untuk menunjukkan bahwa perangkat harus segera mulai bergetar.
  • Pengaturan waktu dan amplitudo. Jenis bentuk gelombang ini memiliki array tambahan amplitudo yang cocok dengan setiap angka waktu, bukan on-off implisit dari bentuk pertama. Namun, penting untuk memeriksa apakah perangkat mendukung kontrol amplitudo untuk memastikan penskalaan yang diinginkan dapat dicapai.

Kompatibilitas dan persyaratan

Karena getaran on-off adalah bentuk getaran tertua, getaran ini didukung di hampir semua perangkat dengan vibrator, seperti yang dijelaskan di halaman ini.

Memutar panggilan VibrationEffect atau vibrate gaya lama, memerlukan izin VIBRATE dalam manifes aplikasi.

Saat menggunakan nilai amplitudo yang berbeda dalam bentuk gelombang, sebaiknya pastikan perangkat mendukung kontrol amplitudo.

Memeriksa dukungan kontrol amplitudo

Nilai amplitudo bukan nol dibulatkan menjadi 100% di perangkat tanpa kontrol amplitudo, jadi penting untuk memeriksa apakah dukungan tersedia menggunakan Vibrator.hasAmplitudeControl. Lihat kontrol amplitudo untuk mengetahui detail selengkapnya.

Anda harus mempertimbangkan dengan cermat apakah efek Anda memiliki kualitas yang memadai tanpa kontrol amplitudo. Kembali ke getaran aktif/nonaktif yang didesain secara eksplisit mungkin lebih baik.

Penggunaan getaran aktif-nonaktif

Pada level SDK yang lebih baru, semua mode getaran digabungkan ke dalam satu class VibrationEffect yang ekspresif, tempat getaran sederhana ini dibuat menggunakan VibrationEffect.createOneShot atau VibrationEffect.createWaveform.

Notification API

Saat menyesuaikan notifikasi aplikasi, Anda dapat menggunakan salah satu API berikut untuk mengaitkan pola dengan setiap saluran notifikasi:

Semua bentuk ini menggunakan pola bentuk gelombang on-off dasar, seperti yang dijelaskan sebelumnya, dengan entri pertama adalah penundaan sebelum vibrator diaktifkan.

Konsep umum

Beberapa konsep berlaku di seluruh platform API yang dijelaskan di atas.

Apakah perangkat memiliki vibrator?

Anda dapat memperoleh class Vibrator non-null dari context.getSystemService(Vibrator.class). Jika perangkat tidak memiliki vibrator, panggilan ke API getaran tidak akan berpengaruh, sehingga aplikasi tidak perlu membatasi semua haptiknya berdasarkan kondisi. Namun, jika diperlukan, aplikasi dapat memanggil hasVibrator() untuk menentukan apakah ini adalah vibrator sebenarnya (true) atau stub (false).

Apakah pengguna telah menonaktifkan haptik sentuh?

Beberapa penerapan kustom mungkin memerlukan pemeriksaan manual apakah pengguna telah menonaktifkan sepenuhnya setelan Masukan sentuh Android, yang dalam hal ini efek masukan sentuh harus dihentikan. Setelan ini dapat dikueri menggunakan kunci HAPTIC_FEEDBACK_ENABLED, dengan nilai nol berarti dinonaktifkan.

Atribut getaran

Atribut getaran (saat ini dalam bentuk AudioAttributes) dapat diberikan untuk membantu memberi tahu sistem tentang tujuan getaran. Hal ini diperlukan saat memulai getaran saat aplikasi Anda berada di latar belakang, karena hanya haptik perhatian yang didukung untuk penggunaan di latar belakang.

Pembuatan AudioAttributes dibahas dalam dokumentasi kelasnya, dan harus dianggap sebagai getaran, bukan suara.

Sebagai panduan, dalam sebagian besar kasus, jenis konten adalah CONTENT_TYPE_SONIFICATION, dan penggunaannya mungkin berupa nilai seperti USAGE_ASSISTANCE_SONIFICATION untuk feedback sentuhan di latar depan, atau USAGE_ALARM untuk alarm di latar belakang. Bendera audio tidak berpengaruh pada getaran.

Kontrol amplitudo

Jika vibrator memiliki kontrol amplitudo, vibrator dapat memutar getaran dengan intensitas yang bervariasi. Ini adalah kemampuan penting untuk menghasilkan haptik yang kaya, serta berpotensi memungkinkan kontrol pengguna atas intensitas haptik default.

Dukungan kontrol amplitudo dapat diperiksa dengan memanggil Vibrator.hasAmplitudeControl. Jika vibrator tidak memiliki dukungan amplitudo, semua nilai amplitudo akan dipetakan ke nonaktif atau aktif berdasarkan apakah nilainya nol atau bukan nol. Oleh karena itu, aplikasi yang menggunakan haptik kaya dengan amplitudo yang bervariasi harus mempertimbangkan untuk menonaktifkannya jika perangkat tidak memiliki kontrol amplitudo.

Dukungan efek amplop

Vibrator dengan dukungan efek amplop memungkinkan pembuatan getaran yang lebih dinamis dan bernuansa, sehingga menawarkan kontrol yang lebih presisi atas intensitas dan ketajaman untuk pengalaman haptik yang lebih kaya. Gunakan Vibration.areEnvelopeEffectsSupported untuk menentukan apakah perangkat Anda mendukung fitur ini. Jika tidak, getaran berbasis amplop akan diabaikan.