En esta sección, se presenta una introducción a las diversas APIs de tecnología háptica disponibles en Android. También se explica cuándo y cómo verificar si se necesita compatibilidad con algún dispositivo para garantizar que los efectos tácticos 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 los efectos hápticos 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 alternativo 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 molestas para los usuarios.
- Los hápticos enriquecidos tienen mayor expresividad y, a menudo, requieren hardware con más funciones.
| Superficie de la API | Disponibilidad | Vibración clara | Tecnología háptica enriquecida |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 y versiones posteriores (por constante) |
||
| Predefined VibrationEffect | Android 10 y versiones posteriores | ||
| Composición de 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 distintas 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 la vibración según su uso, lo que garantiza que se le apliquen los parámetros de configuración del usuario adecuados y, de este modo, se evitan sorpresas para el usuario.
HapticFeedbackConstants
La clase HapticFeedbackConstants proporciona constantes basadas en acciones para permitir que las apps agreguen comentarios hápticos coherentes 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 la 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 alternativo cuando se usa HapticFeedbackConstants.
Uso de HapticsFeedbackConstants
Para obtener detalles sobre el uso de HapticFeedbackConstants, consulta Cómo agregar comentarios hápticos a eventos.
VibrationEffect predefinido
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 el dispositivo vuelven 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 de resguardo.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 una opción 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 retroalimentación háptica.
VibrationEffect de sobre
Las vibraciones basadas en envolventes permiten controlar con precisión 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 retroalimentación háptica más ricas y matizadas. Estas vibraciones se pueden crear con las clases BasicEnvelopeBuilder y WaveformEnvelopeBuilder.
Compatibilidad y requisitos
Para reproducir efectos 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 terminar con una intensidad de \( 0.0 \). La API aplica esta regla 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.
Compilador 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 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
Una composición de VibrationEffect es un efecto de vibración creado con la API de VibrationEffect.startComposition. Esta API permite crear hápticos enriquecidos expresivos creando una secuencia de elementos primitivos con retrasos e intensidades personalizados. Sin embargo, ten especial cuidado para asegurarte de que el dispositivo admita las funciones que se combinan y evitar una experiencia general incoherente.
Compatibilidad y requisitos
Para reproducir cualquier VibrationEffect, se requiere el permiso VIBRATE en el manifiesto de la app.
No todos los dispositivos admiten todas las funciones de la API de Composition, por lo que es importante asegurarse de que los elementos básicos estén disponibles.
Comprueba la compatibilidad con el elemento primitivo de vibración
La compatibilidad por primitivas 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, lo que equivale a AND-ing la compatibilidad por elemento primitivo.
Uso de composiciones de VibrationEffect
Para obtener detalles sobre el uso de composiciones de VibrationEffect, consulta Cómo crear composiciones 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 la tecnología háptica 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 de forma única que un patrón se repita indefinidamente, como podrías imaginar para un tono de llamada.
Un patrón único 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 apagado. 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 coincida 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 de escala previsto.
Compatibilidad y requisitos
Dado que las vibraciones de encendido y apagado son la forma más antigua de vibraciones, se admiten en prácticamente todos los dispositivos con vibrador, como se describe más adelante en esta página.
Para reproducir cualquier llamada de VibrationEffect o de vibrate con el 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 de encendido y apagado
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 básico de encendido y apagado, 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 superficies de la API 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 un stub (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 de 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 obligatorio 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 se debe considerar 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 tienen efecto en 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 hápticos enriquecidos, 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/encendido según sean cero/no cero. Por lo tanto, las aplicaciones que usan hápticos enriquecidos con amplitudes variables deben considerar inhabilitarlos 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. De lo contrario, se ignorarán las vibraciones basadas en el sobre.