API de Vibración de JavaScript

Introducción a la API de Vibración

La API de Vibración permite que las páginas web activen el motor de vibración de un dispositivo, proporcionando a los usuarios retroalimentación háptica (táctil). Está pensada para teléfonos móviles y tabletas que vibran físicamente; en un escritorio sin motor, las llamadas tienen éxito en silencio y no hacen nada.

Toda la API consiste en un único método, navigator.vibrate(). No hay solicitud de permiso ni evento que escuchar: simplemente se llama y el dispositivo vibra. La contrapartida es que los navegadores restringen cuándo se puede invocar, algo que este capítulo explica en detalle.

Esta página cubre las dos formas de argumento del método, cómo detener una vibración, la detección de características, las limitaciones de gesto de usuario y de uso solo en móvil, y cómo usar la vibración con discreción.

El método navigator.vibrate()

navigator.vibrate() acepta uno de dos tipos de argumento:

• Un número único — vibra una vez durante esa cantidad de milisegundos.
• Un array de números — un patrón de duraciones alternas de vibración y pausa.

Devuelve un boolean: true si la solicitud fue aceptada, false si fue rechazada (por ejemplo, cuando no ha ocurrido ningún gesto del usuario). En dispositivos sin motor, el método sigue devolviendo true pero no produce ninguna vibración.

// Single vibration for 500 milliseconds
navigator.vibrate(500);

Patrones de vibración

Cuando se pasa un array, los números se leen como vibrar, pausar, vibrar, pausar, …. Las entradas con índice impar son silencios.

// Vibrate 200 ms, pause 100 ms, vibrate 400 ms
navigator.vibrate([200, 100, 400]);

// "Morse"-like triple buzz: buzz, gap, buzz, gap, buzz
navigator.vibrate([100, 50, 100, 50, 100]);

Una pausa al final no tiene efecto, ya que no hay nada después de ella que vibre.

Detener una vibración

Una nueva llamada reemplaza cualquier vibración en curso. Para cancelarla de inmediato, se pasa 0 o un array vacío:

navigator.vibrate(0);   // stop immediately
navigator.vibrate([]);  // also stops — equivalent to 0

Esto resulta útil para restablecer la retroalimentación cuando el usuario cierra una alerta o navega a otra página.

Detección de características

navigator.vibrate es undefined en navegadores que no lo soportan, por lo que llamarlo directamente lanzaría un error. Proteja cada llamada:

function buzz(pattern) {
  if ('vibrate' in navigator) {
    return navigator.vibrate(pattern);
  }
  return false; // API not available — fall back to a visual cue
}

buzz(200);
buzz([100, 50, 100]);

La detección puede ejecutarse en cualquier entorno, incluido Node o un navegador de escritorio, aunque la vibración real solo ocurre en hardware compatible.

Aplicaciones prácticas

Entender cómo incorporar la API de Vibración de forma efectiva en aplicaciones web puede mejorar significativamente la participación y satisfacción del usuario. A continuación se presentan ejemplos de aplicaciones prácticas que ilustran la versatilidad de la API de Vibración.

Retroalimentación en acciones del usuario

Un zumbido breve confirma una pulsación en dispositivos donde el usuario no siempre puede ver la reacción de la pantalla. Nótese que el propio manejador de clic es el gesto del usuario, por lo que la llamada está permitida:

document.getElementById('button').addEventListener('click', () => {
  if ('vibrate' in navigator) {
    navigator.vibrate(100); // brief confirmation buzz
  }
});

Alertas de notificación

Cuando un sonido o señal visual puede pasarse por alto o resultar inapropiado (modo silencio, accesibilidad), un patrón distintivo puede sustituirlo:

function alertUser() {
  if ('vibrate' in navigator) {
    navigator.vibrate([500, 200, 500]); // buzz, pause, buzz
  }
}

Mejorar experiencias de juego

En juegos web, la vibración añade retroalimentación física en momentos clave; pero solo si el momento sigue una entrada reciente del usuario, o la llamada será ignorada:

function gameOver() {
  if ('vibrate' in navigator) {
    navigator.vibrate(1000); // one long buzz signals game over
  }
}

Limitaciones que hay que tener en cuenta

La API de Vibración parece trivial, pero los navegadores la envuelven en restricciones que silenciosamente hacen que "no haga nada":

• Solo en móviles en la práctica. La vibración requiere un motor de hardware. Los navegadores de escritorio carecen del método por completo (Safari, Firefox en escritorio) o aceptan la llamada sin vibrar. Trate la vibración como una mejora, nunca como el único tipo de retroalimentación.
• Requiere un gesto del usuario. Los navegadores modernos ignoran navigator.vibrate() a menos que se ejecute en respuesta a una interacción real (una pulsación, clic o tecla). Un zumbido activado al cargar la página, desde un setTimeout o desde un evento en segundo plano se descarta silenciosamente — el método devuelve false. Active la vibración directamente dentro de un manejador de eventos.
• Sin permiso ni canal de retroalimentación. No hay solicitud ni evento de error; una llamada rechazada simplemente devuelve false. Compruebe ese valor de retorno si necesita saber si funcionó.
• Las pestañas ocultas están bloqueadas. Si la página no está visible (pestaña en segundo plano), la solicitud se ignora.
• Los patrones tienen límites. Los navegadores limitan la duración total máxima y el número de entradas en un patrón; las vibraciones extremadamente largas se truncan.

Buenas prácticas y consideraciones

Aunque la API de Vibración abre nuevas posibilidades para la participación del usuario, su implementación debe abordarse con consideración por la experiencia de usuario.

• Respetar las preferencias del usuario: proporcione siempre una opción para que los usuarios puedan desactivar la retroalimentación por vibración, atendiendo a quienes la encuentren intrusiva o tengan necesidades de accesibilidad.
• Consumo de batería: tenga en cuenta el posible impacto en la vida útil de la batería del dispositivo, especialmente con el uso extensivo de patrones o vibraciones largas.
• Pruebas en múltiples dispositivos: la intensidad de la vibración y la percepción de los patrones pueden variar significativamente entre dispositivos. Probar en distintos dispositivos garantiza una experiencia de usuario consistente.
• Compatibilidad con navegadores: la API de Vibración es compatible principalmente con navegadores móviles (Chrome, Firefox, Edge). No está disponible en Safari ni en la mayoría de los navegadores de escritorio. Verifique siempre el soporte antes de implementarla.

Conclusión

La API de Vibración de JavaScript ofrece una forma práctica de involucrar a los usuarios mediante retroalimentación táctil con un único método, navigator.vibrate(). Recuerde lo esencial: detecte la característica antes de llamar, active la vibración solo desde gestos del usuario, mantenga un enfoque mobile-first, y combine siempre la háptica con un respaldo visual o de audio para que nada se pierda en dispositivos que no la soporten.

Para seguir explorando las API del navegador orientadas al dispositivo, consulte la API de Orientación de Pantalla para reaccionar a los cambios entre orientación vertical y horizontal, la API de Geolocalización para datos de ubicación, y Entorno del navegador, Especificaciones para entender cómo encajan navigator y otros objetos del entorno.

Práctica