This section gives an introduction to the various haptics APIs available in Android. It also covers when and how to check for any device support necessary to ensure your haptic effects play as you intend.
There are several different ways to create haptic effects, and it's important to consider Android haptics design principles when choosing among them. The following table summarizes these high level attributes of each approach:
- Availability is particularly important when planning behavior fallback, and needs to be combined with checking individual device support.
- Clear haptics are crisp and clean sensations that are less jarring for users.
- Rich haptics have greater expressiveness and often require more feature-rich hardware.
API surface | Availability | Clear haptics | Rich haptics |
---|---|---|---|
HapticFeedbackConstants | Android 1.5+ (per constant) |
||
Predefined VibrationEffect | Android 10+ | ||
VibrationEffect Composition | Android 11+ (per constant) | ||
On/off, one-shot and waveform vibrations | Android 1 |
Additionally, notification APIs, described on this page, allows you to customize the haptic effects that play for incoming notifications.
Also described on this page are additional concepts that span the API surfaces:
- Does the device have a vibrator?
- Amplitude control allows smoother, richer haptic effects, but is not supported by all devices.
VibrationAttributes()
helps you classify vibration based on its usage, ensuring the appropriate user settings will be applied to it and thus avoiding surprises to the user.
HapticFeedbackConstants
The HapticFeedbackConstants
class provides action-based constants to allow
apps to add haptic feedback that's consistent across the device experience,
rather than each app having different effects for common actions.
Compatibility and requirements
Using the View.performHapticFeedback
method with these constants does not
require any special permissions for the app. It is subject to the
View.hapticFeedbackEnabled
property, which if set to false
will disable
all haptic feedback calls on the view, including default ones.The primary
related setting the View.hapticFeedbackEnabled
property, which if set to
false
will disable all haptic feedback calls on the view, including default
ones. The method also honours the user's system setting for enabling touch
feedback.
The only compatibility consideration is the SDK-level of the specific constant for the action.
There is no need to provide fallback behavior when using
HapticFeedbackConstants
.
Usage of HapticsFeedbackConstants
For details on using HapticFeedbackConstants
, see Add haptic feedback to
events.
Predefined VibrationEffect
The VibrationEffect
class
provides several predefined constants such as CLICK
, TICK
and
DOUBLE_CLICK
. These effects may be optimized for the device.
Compatibility and requirements
Playing any VibrationEffect
requires the VIBRATE
permission in the app
manifest.
There is no need to provide fallback behavior when using predefined
VibrationEffect
, as constants that don't have a device-optimized
implementation revert to a standard platform fallback.
The Vibrator.areEffectsSupported
and Vibrator.areAllEffectsSupported
APIs are for determining if there is a device-optimized implementation.
Predefined effects can still be used without an optimized implementation, and
uses the standard platform fallback. Consequently, these
areEffectsSupported
APIs are only needed if an application wants to take into
consideration whether the effect is optimized for the device or not.
The effect-checking methods can return one of three values:
VIBRATION_EFFECT_SUPPORT_YES
indicates that the device has optimized support for this effect.VIBRATION_EFFECT_SUPPORT_NO
indicates that the device does not have optimized support, but still uses the platform fallback.VIBRATION_EFFECT_SUPPORT_UNKNOWN
indicates the system doesn't know if the implementation is optimized or not.
As the UNKNOWN
value indicates the checking API is unavailable, it's typically
returned for all effects or none of them. These devices fall back dynamically.
Usage of predefined VibrationEffect
For details on using a predefined VibrationEffect
, see Use a predefined VibrationEffect
to generate haptic feedback.
VibrationEffect
composition
A VibrationEffect
composition is a vibration effect created using the
VibrationEffect.startComposition
API. This API allows expressive
rich haptics by creating a sequence of primitives with
customized delays and intensities. However, take special care to ensure that the
device supports the features being combined to avoid an inconsistent overall
experience.
Compatibility and requirements
Playing any VibrationEffect
requires the VIBRATE
permission in the app
manifest.
Not all devices support all features of the composition API, and it is important to ensure that the primitives are available.
Check for vibration primitive support
Per-primitive support can be retrieved using the
Vibrator.arePrimitivesSupported
method. Alternatively, a set of primitives
may be checked together by using the Vibrator.areAllPrimitivesSupported
method - this is equivalent to AND
-ing the per-primitive support.
Usage of VibrationEffect
Compositions
For details on using VibrationEffect
compositions, see Create vibration compositions.
On-off, one-shot, and waveform vibrations
The oldest form of vibration supported on Android is simple vibrator on-off patterns with configurable durations. These APIs are typically not well aligned with Haptics design principles because they can generate buzzy haptics; avoid them except as a last resort.
The most common use case for on-off vibrations is notifications, where, no matter what, some vibration is desired. Waveform vibrations also uniquely allow a pattern to repeat indefinitely, as you might imagine for a ringtone.
A one-shot pattern refers to vibrating once for N milliseconds.
There are two types of waveform patterns:
- Timings-only. This type of waveform is a description of alternating durations spent off, and durations spent on. The timings start with the duration spent off. Consequently, waveform patterns often start with a zero value to indicate to immediately start vibrating.
- Timings and amplitudes. This type of waveform has an additional array of amplitudes to match with each timing figure, rather than the implicit on-off of the first form. However, it's important to check that the device supports amplitude control to ensure that the intended scaling can be achieved.
Compatibility and requirements
As on-off vibrations are the oldest form of vibrations, these are supported on virtually all devices with a vibrator, as described later on this page.
Playing any VibrationEffect
or the older style vibrate
calls, requires the
VIBRATE
permission in the app manifest.
When using different amplitude values in a waveform, we strongly recommend that you that the device supports amplitude control.
Check for amplitude control support
Non-zero amplitude values are rounded up to 100% on devices without amplitude
control, so it is important to check if the support is present using
Vibrator.hasAmplitudeControl
. See the amplitude control
for more details.
You should carefully consider whether your effect has sufficient quality without amplitude control. Falling back to an explicitly designed on-off vibration may be better.
Usage of on-off vibrations
In newer SDK levels, all vibration modes were consolidated into a single
expressive VibrationEffect
class, where these simple vibrations are created
using VibrationEffect.createOneshot
or VibrationEffect.createWaveform
.
Notification APIs
When customizing your app notifications, you can use one of the following APIs to associate a pattern with each notification channel:
- AndroidX
- Android
All of these forms take a basic on-off waveform pattern, as described earlier, where the first entry is the delay before turning the vibrator on.
General concepts
Several concepts apply across the API surfaces detailed above.
Does the device have a vibrator?
You can obtain a non-null Vibrator
class from
context.getSystemService(Vibrator.class)
. If the device doesn't have a
vibrator, calls to the vibration APIs don't have any effect, so apps don't need
to gate all of their haptics on a condition. However, if needed, an application
can call hasVibrator()
to
determine if this is a real vibrator (true
) or a stub (false
).
Has the user disabled touch haptics?
Some custom implementations may require manually checking whether the user has
entirely disabled Android's Touch feedback
setting, in which case touch feedback effects should be suppressed. This setting
can be queried using the HAPTIC_FEEDBACK_ENABLED
key, where a value of zero
means disabled.
Vibration attributes
Vibration attributes (currently in the form of AudioAttributes
) can be
provided to help inform the system of the purpose of the vibration. This is
required when initiating a vibration when your app is in the background,
as only attentional haptics are supported for background usage.
The creation of AudioAttributes
is covered in its class documentation, and
should be thought of as vibration rather than sound.
As a guide, in most cases, the content type is CONTENT_TYPE_SONIFICATION
,
and the usage might be values such as USAGE_ASSISTANCE_SONIFICATION
for
touch feedback in the foreground, or USAGE_ALARM
for an alarm in the
background. Audio flags have no effect on vibrations.
Amplitude control
If a vibrator has amplitude control, then it can play vibrations with varying intensities. This is an important capability for producing rich haptics, as well as potentially allowing user control of default haptic intensities.
Amplitude control support can be checked by calling
Vibrator.hasAmplitudeControl
. If a vibrator does not have amplitude support,
all amplitude values will map to off/on based on whether they are
zero/non-zero. Consequently, applications using rich haptics with varying
amplitudes should consider disabling them if the device lacks amplitude control.