Android haptics API reference

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:

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:

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:

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.