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 Haptik yang jelas Haptik kaya
HapticFeedbackConstants Android 1.5+
(per konstanta)
Predefined VibrationEffect Android 10+
Komposisi VibrationEffect Android 11+ (per konstanta)
Getaran on/off, one-shot, 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 permukaan API:

  • Apakah perangkat memiliki vibrator?
  • Kontrol amplitudo memungkinkan efek haptik yang lebih lancar dan kaya, tetapi tidak didukung oleh semua perangkat.
  • VibrationAttributes() membantu Anda mengklasifikasikan getaran berdasarkan penggunaannya, sehingga memastikan setelan pengguna yang sesuai akan diterapkan padanya dan dengan demikian menghindari kejutan bagi pengguna.

HapticFeedbackConstants

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

Kompatibilitas dan persyaratan

Penggunaan 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 umpan balik haptik pada tampilan, termasuk yang default.Setelan utama terkait adalah properti View.hapticFeedbackEnabled, yang jika disetel ke false akan menonaktifkan semua panggilan umpan balik haptik pada tampilan, termasuk yang default. Metode ini juga mematuhi setelan sistem pengguna untuk mengaktifkan feedback sentuhan.

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

Anda tidak perlu menyediakan 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 penerapan 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. Oleh karena itu, areEffectsSupportedAPI 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 akan melakukan penggantian secara dinamis.

Penggunaan VibrationEffect standar

Untuk mengetahui detail tentang penggunaan VibrationEffect yang telah ditentukan, lihat Menggunakan VibrationEffect yang telah ditentukan untuk menghasilkan umpan balik 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 menetapkan intensitas awal ke nol dan menampilkan 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 minimal 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 menciptakan 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 yang 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

Komposisi VibrationEffect adalah efek getaran yang dibuat menggunakan VibrationEffect.startComposition API. API ini memungkinkan haptik kaya yang ekspresif dengan membuat urutan primitif dengan penundaan dan intensitas yang disesuaikan. Namun, berhati-hatilah untuk memastikan bahwa perangkat mendukung fitur yang digabungkan untuk menghindari pengalaman keseluruhan yang tidak konsisten.

Kompatibilitas dan persyaratan

Memutar VibrationEffect apa pun memerlukan izin VIBRATE dalam manifes aplikasi.

Tidak semua perangkat mendukung semua fitur Composition API, dan penting untuk memastikan bahwa primitif tersedia.

Memeriksa dukungan primitif getaran

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 VibrationEffect

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

Getaran on-off, satu kali, 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, yang 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 saat perangkat nonaktif dan durasi saat perangkat aktif. Waktu dimulai dengan durasi saat perangkat tidak digunakan. Akibatnya, pola bentuk gelombang sering kali dimulai dengan nilai nol untuk menunjukkan bahwa perangkat harus segera bergetar.
  • Pengaturan waktu dan amplitudo. Jenis bentuk gelombang ini memiliki array amplitudo tambahan 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 Anda memastikan bahwa perangkat mendukung kontrol amplitudo.

Memeriksa dukungan kontrol amplitudo

Nilai amplitudo non-nol dibulatkan hingga 100% pada 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 on-off yang didesain secara eksplisit mungkin lebih baik.

Penggunaan getaran on-off

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 permukaan 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. Flag audio tidak berpengaruh pada getaran.

Kontrol amplitudo

Jika penggetar memiliki kontrol amplitudo, maka penggetar 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/aktif berdasarkan apakah nilainya nol/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 dan 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.