En esta sección, se presenta una introducción a las diversas APIs de tecnología táctil disponibles en Android. También abarca cuándo y cómo verificar la compatibilidad del dispositivo necesaria para garantizar que los efectos hápticos se reproduzcan según lo previsto.
Existen varias formas diferentes de crear efectos hápticos, y es importante tener en cuenta los principios de diseño de la tecnología táctil de Android cuando elijas entre ellos. En la siguiente tabla, se resumen estos atributos de alto nivel de cada enfoque:
- La disponibilidad es especialmente importante cuando se planifica el comportamiento de resguardo y debe combinarse con la verificación de la compatibilidad de cada dispositivo.
- Las hápticas claras son sensaciones nítidas y limpias que resultan menos bruscas para los usuarios.
- Los hápticos enriquecidos tienen mayor expresividad y, a menudo, requieren hardware más completo.
| Superficie de la API | Disponibilidad | Tecnología táctil clara | Tecnología táctil enriquecida |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 y versiones posteriores (por constante) |
||
| Predefined VibrationEffect | Android 10 y versiones posteriores | ||
Composición de VibrationEffect (preferida) |
Android 16 y versiones posteriores (26Q4) | ||
Composición de primitivas VibrationEffect |
Android 11 y versiones posteriores (por constante) | ||
| Vibraciones de encendido/apagado, de un solo toque y de forma de onda | Android 1 |
Además, las APIs de notificaciones, que se describen en esta página, te permiten personalizar los efectos hápticos que se reproducen para las notificaciones entrantes.
En esta página, también se describen conceptos adicionales que abarcan las superficies de la API:
- ¿El dispositivo tiene un vibrador?
- El control de amplitud permite efectos hápticos más suaves y enriquecidos, pero no es compatible con todos los dispositivos.
VibrationAttributes()te ayuda a clasificar las vibraciones según el uso, lo que garantiza que se aplique la configuración del usuario adecuada para evitar sorprenderlo.
HapticFeedbackConstants
La clase HapticFeedbackConstants proporciona constantes basadas en acciones para permitir que las apps agreguen respuesta táctil coherente en toda la experiencia del dispositivo, en lugar de que cada app tenga efectos diferentes para las acciones comunes.
Compatibilidad y requisitos
El uso del método View.performHapticFeedback con estas constantes no requiere permisos especiales para la app. Está sujeto a la propiedad View.hapticFeedbackEnabled, que, si se establece en false, inhabilitará todas las llamadas de respuesta háptica en la vista, incluidas las predeterminadas.El parámetro de configuración principal relacionado es la propiedad View.hapticFeedbackEnabled, que, si se establece en false, inhabilitará todas las llamadas de respuesta háptica en la vista, incluidas las predeterminadas. El método también respeta el parámetro de configuración del sistema del usuario para habilitar la respuesta táctil.
La única consideración de compatibilidad es el nivel del SDK de la constante específica para la acción.
No es necesario proporcionar un comportamiento de resguardo cuando se usa HapticFeedbackConstants.
Uso de HapticsFeedbackConstants
Para obtener detalles sobre el uso de HapticFeedbackConstants, consulta Cómo agregar respuesta táctil a eventos.
Predefinido VibrationEffect
La clase VibrationEffect proporciona varias constantes predefinidas, como CLICK, TICK y DOUBLE_CLICK. Es posible que estos efectos estén optimizados para el dispositivo.
Compatibilidad y requisitos
Para reproducir cualquier VibrationEffect, se requiere el permiso VIBRATE en el manifiesto de la app.
No es necesario proporcionar un comportamiento de resguardo cuando se usa VibrationEffect predefinido, ya que las constantes que no tienen una implementación optimizada para dispositivos revierten a un resguardo estándar de la plataforma.
Las APIs de Vibrator.areEffectsSupported y Vibrator.areAllEffectsSupported sirven para determinar si hay una implementación optimizada para el dispositivo.
Los efectos predefinidos se pueden seguir usando sin una implementación optimizada y se usa la alternativa estándar de la plataforma. Por lo tanto, estas APIs de areEffectsSupported solo son necesarias si una aplicación quiere tener en cuenta si el efecto está optimizado para el dispositivo o no.
Los métodos de verificación de efectos pueden devolver uno de los siguientes tres valores:
VIBRATION_EFFECT_SUPPORT_YESindica que el dispositivo tiene compatibilidad optimizada con este efecto.VIBRATION_EFFECT_SUPPORT_NOindica que el dispositivo no tiene compatibilidad optimizada, pero sigue usando la plataforma alternativa.VIBRATION_EFFECT_SUPPORT_UNKNOWNindica que el sistema no sabe si la implementación está optimizada o no.
Como el valor de UNKNOWN indica que la API de verificación no está disponible, suele devolverse para todos los efectos o para ninguno de ellos. Estos dispositivos recurren a la copia de seguridad de forma dinámica.
Uso de VibrationEffect predefinido
Para obtener detalles sobre cómo usar un VibrationEffect predefinido, consulta Cómo usar un VibrationEffect predefinido para generar comentarios hápticos.
Envelope VibrationEffect
Las vibraciones basadas en envolventes permiten un control preciso de la amplitud y la frecuencia de la vibración a lo largo del tiempo definiendo una secuencia de puntos de control. Esto permite que los desarrolladores creen experiencias de respuesta táctil más ricas y matizadas. Estas vibraciones se pueden crear con las clases BasicEnvelopeBuilder y WaveformEnvelopeBuilder.
Compatibilidad y requisitos
Para reproducir cualquier efecto de vibración, tu app debe declarar el permiso VIBRATE en el manifiesto de la app.
Para verificar la compatibilidad con los efectos de envolvente, llama a Vibrator.areEnvelopeEffectsSupported().
Basic Envelope Builder
Para crear una experiencia háptica fluida y sin interrupciones, los efectos de envolvente deben comenzar y finalizar con una intensidad de \( 0.0 \). La API aplica esto fijando la intensidad inicial en cero y lanza una excepción si la intensidad final no es cero. Esta restricción evita efectos dinámicos no deseados en las vibraciones debido a discontinuidades en la amplitud que pueden afectar negativamente la percepción háptica del usuario.
Para proporcionar una renderización coherente del efecto de envolvente en todos los dispositivos, el framework requiere que los dispositivos que admiten esta función puedan controlar una duración mínima de 20 ms entre los puntos de control y, al menos, 16 puntos para los efectos de envolvente.
Creador de envolvente de forma de onda
El framework no modifica los valores de frecuencia y amplitud solicitados que proporciona el desarrollador. Sin embargo, la API también fija la amplitud inicial en cero para crear transiciones suaves.
Para ayudarte a optimizar los efectos de envolvente de forma de onda de tu app y proporcionar compatibilidad en todos los dispositivos, Android proporciona APIs para consultar las capacidades importantes del dispositivo. Estos métodos proporcionan información sobre las limitaciones del dispositivo, como la duración máxima y mínima de la transición entre los puntos de control y la cantidad máxima de puntos de control admitidos para un solo efecto:
getMaxSize()- Recupera la cantidad máxima de puntos de control admitidos para un efecto de envolvente.
getMinControlPointDurationMillis()- Recupera la duración mínima admitida, en milisegundos, entre dos puntos de control dentro de un efecto de envolvente.
getMaxControlPointDurationMillis()- Recupera la duración máxima admitida, en milisegundos, entre dos puntos de control dentro de un efecto de envolvente.
getMaxDurationMillis()- Recupera la duración máxima admitida para un efecto de envolvente, en milisegundos.
Si un efecto supera las limitaciones del dispositivo (por ejemplo, si permite demasiados puntos de control o una duración que supera el máximo), el framework ajusta automáticamente el efecto para que se ajuste a los límites permitidos. Este proceso de ajuste intenta conservar la intención y el estilo originales del diseño en la mayor medida posible.
Uso de Envelope VibrationEffects
Para obtener detalles sobre cómo crear efectos de forma de onda de envolvente, consulta cómo crear una forma de onda de vibración con envolventes.
Composición de VibrationEffect
A partir de Android 16 (26Q4), VibrationEffect.Builder es la API preferida para componer efectos hápticos enriquecidos y expresivos secuenciando varios elementos hápticos a lo largo de un cronograma diseñado. Reemplaza a VibrationEffect.Composition, ya que ofrece programación anclada en la línea de tiempo, encapsulación atómica, compatibilidad con eventos mixtos (que combinan ajustes predeterminados y envolventes) y una función automática integrada de resguardo.
Componentes básicos
El compilador te permite secuenciar los siguientes elementos hápticos:
VibrationEffect.Preset: Sensaciones hápticas predefinidas que representan pulsos cortos comunes, comoPRESET_CLICK,PRESET_TICKyPRESET_LOW_TICK. Los ajustes predeterminados reemplazan a los elementos primitivos cortos de la API deVibrationEffect.Composition. Para efectos más largos, continuos o graduales (anteriormente controlados por rise, fall y otras primitivas), usa envelopes (PWLE) en su lugar. Los ajustes predeterminados se pueden escalar de0.0fa1.0fconPreset.create(presetId, scale).VibrationEffect.Envelope: Son envolventes lineales por tramos (PWLE) creadas conBasicEnvelopeBuilder(con intensidad y nitidez) oWaveformEnvelopeBuilder(con frecuencia y amplitud). Los sobres se construyen conEnvelope.create(builder).VibrationEffect.Event: Son los eventos de la línea de tiempo recuperados de unVibrationEffectexistente congetEvents(). Se pueden agregar con un desplazamiento de la línea de tiempo usandoaddEvents(startTimeShiftMillis, events).
Programación y validación del cronograma
Cada elemento se agrega al compilador con un startTimeMillis que representa la compensación de tiempo (en milisegundos) desde el inicio de la composición:
- Validación en tiempo de compilación: Los elementos deben agregarse en orden estrictamente creciente de sus horas de inicio. El compilador realiza una validación del mejor esfuerzo en el tiempo de compilación verificando la duración mínima (como 1 ms para los ajustes predeterminados o las duraciones conocidas para los sobres). Si se detecta una superposición durante el tiempo de compilación, se arroja un
IllegalArgumentException. - Alineación de la sincronización de la reproducción: El framework proporciona compatibilidad con la sincronización durante la reproducción en la medida de lo posible. Si un evento anterior aún se está ejecutando cuando llega la hora de inicio del siguiente evento programado, el framework cambia automáticamente el evento posterior al siguiente horario disponible más cercano. Esto evita que los eventos se superpongan en la reproducción física y garantiza que no se descarten eventos hápticos.
Efectos repetidos
Se puede agregar un efecto de repetición a la composición con setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Una vez que se configura un efecto de repetición, no se pueden agregar elementos adicionales al compilador.
Compatibilidad con resguardo
El soporte automático de resguardo a nivel del framework está habilitado de forma predeterminada para la vibración creada por VibrationEffect.Builder:
- Respaldo transparente de la plataforma: Si un dispositivo no admite un
Presetsolicitado o unEnvelopebásico, el framework sustituye automáticamente el elemento no admitido por una vibración admitida adecuada en el tiempo de ejecución con el mejor esfuerzo. Tu app no necesita verificar manualmente las capacidades del dispositivo (comoisPresetSupported) antes de reproducir composiciones creadas conVibrationEffect.Builder. - Excepción para
WaveformEnvelopeBuilder: Los efectos de envolvente creados porWaveformEnvelopeBuilder(que especifican frecuencias físicas absolutas en Hertz y amplitudes en Gs) no tienen compatibilidad automática con copias de seguridad. Dado que las PWLE avanzadas se basan en curvas de frecuencia de hardware específicas (FOAM), sustituirlas automáticamente comprometería la intención del diseño. Si el dispositivo no admite los efectos de PWLE o las frecuencias solicitadas, no se reproducirán esas vibraciones. Para una compatibilidad universal, prefiereBasicEnvelopeBuilder.
Uso de VibrationEffect.Builder
Para ver ejemplos de código sobre cómo componer efectos con VibrationEffect.Builder, consulta Cómo crear composiciones ancladas en la línea de tiempo con VibrationEffect.Builder.
Composición de primitivos VibrationEffect
Una composición de primitivas VibrationEffect es un efecto de vibración creado con la API de VibrationEffect.startComposition. Esta API te permite crear una secuencia de elementos primitivos.
Compatibilidad y requisitos
Para reproducir cualquier VibrationEffect, se requiere el permiso VIBRATE en el manifiesto de la app.
Comprueba la compatibilidad con los tipos primitivos
Por lo tanto, cuando uses la API de VibrationEffect.Composition, debes verificar la compatibilidad por primitivas con Vibrator.arePrimitivesSupported o Vibrator.areAllPrimitivesSupported antes de reproducir.
La compatibilidad por primitiva se puede recuperar con el método Vibrator.arePrimitivesSupported. Como alternativa, se puede verificar un conjunto de elementos primitivos juntos con el método Vibrator.areAllPrimitivesSupported, que equivale a AND-ing la compatibilidad por elemento primitivo.
Uso de composiciones de elementos primitivos de VibrationEffect
Para obtener detalles sobre el uso de composiciones de primitivas de VibrationEffect, consulta Cómo crear composiciones de primitivas de vibración.
Vibraciones de encendido y apagado, de un solo toque y de forma de onda
La forma más antigua de vibración compatible con Android son los patrones simples de encendido y apagado del vibrador con duraciones configurables. Por lo general, estas APIs no se alinean bien con los principios de diseño de hápticos porque pueden generar hápticos con vibraciones. Evítalas, excepto como último recurso.
El caso de uso más común para las vibraciones de encendido y apagado son las notificaciones, en las que, sin importar qué, se desea alguna vibración. Las vibraciones de forma de onda también permiten que un patrón se repita de forma indefinida, como podrías imaginar para un tono de llamada.
Un patrón de un solo toque se refiere a vibrar una vez durante N milisegundos.
Existen dos tipos de patrones de formas de onda:
- Solo los tiempos. Este tipo de forma de onda es una descripción de las duraciones alternadas de apagado y encendido. Los tiempos comienzan con la duración del tiempo de inactividad. Por lo tanto, los patrones de forma de onda suelen comenzar con un valor cero para indicar que se debe comenzar a vibrar de inmediato.
- Tiempos y amplitudes. Este tipo de forma de onda tiene un array adicional de amplitudes para que coincidan con cada cifra de tiempo, en lugar del encendido y apagado implícito de la primera forma. Sin embargo, es importante verificar que el dispositivo admita el control de amplitud para garantizar que se pueda lograr el ajuste deseado.
Compatibilidad y requisitos
Dado que las vibraciones de encendido y apagado son la forma más antigua de vibraciones, son compatibles con casi todos los dispositivos con vibrador, como se describe más adelante en esta página.
Para reproducir cualquier llamada de VibrationEffect o de vibrate de estilo anterior, se requiere el permiso VIBRATE en el manifiesto de la app.
Cuando uses diferentes valores de amplitud en una forma de onda, te recomendamos que el dispositivo admita el control de amplitud.
Comprueba la compatibilidad con el control de amplitud
Los valores de amplitud distintos de cero se redondean al 100% en los dispositivos sin control de amplitud, por lo que es importante verificar si la compatibilidad está presente con Vibrator.hasAmplitudeControl. Consulta el control de amplitud para obtener más detalles.
Debes considerar cuidadosamente si tu efecto tiene la calidad suficiente sin control de amplitud. Puede ser mejor recurrir a una vibración de encendido y apagado diseñada de forma explícita.
Uso de vibraciones intermitentes
En los niveles de SDK más recientes, todos los modos de vibración se consolidaron en una sola clase VibrationEffect expresiva, en la que estas vibraciones simples se crean con VibrationEffect.createOneShot o VibrationEffect.createWaveform.
APIs de Notifications
Cuando personalices las notificaciones de tu app, puedes usar una de las siguientes APIs para asociar un patrón con cada canal de notificación:
- AndroidX
- Android
Todas estas formas adoptan un patrón de forma de onda de encendido y apagado básico, como se describió anteriormente, en el que la primera entrada es la demora antes de encender el vibrador.
Conceptos generales
Varios conceptos se aplican a las plataformas de APIs que se detallaron anteriormente.
¿El dispositivo tiene un vibrador?
Puedes obtener una clase Vibrator no nula de context.getSystemService(Vibrator.class). Si el dispositivo no tiene un vibrador, las llamadas a las APIs de vibración no tienen ningún efecto, por lo que las apps no necesitan restringir todos sus hápticos en una condición. Sin embargo, si es necesario, una aplicación puede llamar a hasVibrator() para determinar si se trata de un vibrador real (true) o de un código auxiliar (false).
¿El usuario inhabilitó la respuesta háptica táctil?
Algunas implementaciones personalizadas pueden requerir que se verifique manualmente si el usuario inhabilitó por completo el parámetro de configuración Comentarios táctiles de Android, en cuyo caso se deben suprimir los efectos de comentarios táctiles. Este parámetro de configuración se puede consultar con la clave HAPTIC_FEEDBACK_ENABLED, en la que un valor de cero significa que está inhabilitado.
Atributos de vibración
Se pueden proporcionar atributos de vibración (actualmente en forma de AudioAttributes) para ayudar a informar al sistema sobre el propósito de la vibración. Esto es necesario cuando se inicia una vibración mientras la app está en segundo plano, ya que solo se admiten los hápticos de atención para el uso en segundo plano.
La creación de AudioAttributes se explica en la documentación de su clase y debe considerarse como vibración en lugar de sonido.
Como guía, en la mayoría de los casos, el tipo de contenido es CONTENT_TYPE_SONIFICATION, y el uso puede tener valores como USAGE_ASSISTANCE_SONIFICATION para la respuesta táctil en primer plano o USAGE_ALARM para una alarma en segundo plano. Los parámetros de audio no afectan las vibraciones.
Control de amplitud
Si un vibrador tiene control de amplitud, puede reproducir vibraciones con diferentes intensidades. Esta es una capacidad importante para producir tecnología táctil enriquecida, además de permitir potencialmente el control del usuario de las intensidades hápticas predeterminadas.
Para verificar si se admite el control de amplitud, llama a Vibrator.hasAmplitudeControl. Si un vibrador no admite la amplitud, todos los valores de amplitud se asignarán a apagado o encendido según sean cero o distintos de cero. Por lo tanto, las aplicaciones que usan tecnología táctil enriquecida con amplitudes variables deben considerar desactivarlos si el dispositivo no tiene control de amplitud.
Compatibilidad con efectos de envolvente
Los vibradores con efectos de envolvente admiten y permiten la creación de vibraciones más dinámicas y sutiles, lo que ofrece un control más preciso sobre la intensidad y la nitidez para brindar experiencias hápticas más enriquecedoras. Usa Vibration.areEnvelopeEffectsSupported para determinar si tu dispositivo admite esta función. Si no lo hace, se ignoran las vibraciones basadas en el sobre.