API de Vibração do JavaScript

Introdução à API de Vibração

A API de Vibração permite que páginas web acionem o motor de vibração de um dispositivo, proporcionando aos utilizadores feedback háptico (baseado no toque). Destina-se a telemóveis e tablets que vibram fisicamente — num computador sem motor, as chamadas têm sucesso silenciosamente e não fazem nada.

Toda a API consiste num único método, navigator.vibrate(). Não existe pedido de permissão nem evento a escutar: basta chamar o método e o dispositivo vibra. A contrapartida é que os browsers restringem quando é possível chamá-lo, o que este capítulo explica em detalhe.

Esta página aborda as duas formas de argumento do método, como parar uma vibração, deteção de funcionalidades, as limitações de gesto do utilizador e de uso exclusivamente móvel, e como usar a vibração de forma adequada.

O método navigator.vibrate()

navigator.vibrate() aceita um de dois tipos de argumento:

• Um único número — vibra uma vez durante esse número de milissegundos.
• Um array de números — um padrão de durações alternadas de vibração/pausa.

Devolve um boolean: true se o pedido foi aceite, false se foi rejeitado (por exemplo, quando não ocorreu nenhum gesto do utilizador). Em dispositivos sem motor, o método ainda devolve true mas não produz qualquer vibração.

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

Padrões de vibração

Quando se passa um array, os números são lidos como vibrar, pausar, vibrar, pausar, …. As entradas com índice ímpar são intervalos silenciosos.

// 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]);

Uma pausa no final não tem efeito, pois não há nada depois dela para vibrar.

Parar uma vibração

Uma nova chamada substitui qualquer vibração já em curso. Para cancelar uma imediatamente, passe 0 ou um array vazio:

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

Isto é útil para redefinir o feedback quando o utilizador dispensa um alerta ou navega para outra página.

Deteção de funcionalidades

navigator.vibrate é undefined nos browsers que não o suportam, pelo que chamá-lo diretamente lançaria um erro. Proteja cada chamada:

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]);

Pode executar a deteção em qualquer lugar — incluindo no Node.js ou num browser de secretária — mesmo que a vibração real só aconteça em hardware compatível.

Aplicações Práticas

Compreender como incorporar a API de Vibração de forma eficaz em aplicações web pode melhorar significativamente o envolvimento e a satisfação dos utilizadores. Abaixo encontram-se exemplos de aplicações práticas que ilustram a versatilidade da API de Vibração.

Feedback em ações do utilizador

Uma vibração curta confirma um toque em dispositivos onde o utilizador nem sempre consegue ver a reação do ecrã. Note que o próprio handler de clique é o gesto do utilizador, pelo que a chamada é permitida:

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

Alertas de notificação

Quando uma indicação sonora ou visual pode ser ignorada ou inadequada (modo silencioso, acessibilidade), um padrão distintivo pode substituí-la:

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

Melhorar experiências de jogo

Em jogos web, a vibração adiciona feedback físico em momentos-chave — mas apenas se o momento se seguir a uma entrada recente do utilizador, caso contrário a chamada será ignorada:

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

Limitações que deve considerar

A API de Vibração parece trivial, mas os browsers envolvem-na em restrições que silenciosamente fazem com que "não faça nada":

• Apenas para dispositivos móveis na prática. A vibração requer um motor de hardware. Os browsers de secretária ou não têm o método (Safari, Firefox no desktop) ou aceitam a chamada sem vibrar. Trate a vibração como um aprimoramento, nunca como o único feedback.
• Requer um gesto do utilizador. Os browsers modernos ignoram navigator.vibrate() a não ser que seja executado em resposta a uma interação real (toque, clique ou tecla pressionada). Uma vibração acionada no carregamento da página, a partir de um setTimeout ou de um evento em segundo plano é silenciosamente descartada — o método devolve false. Acione a vibração diretamente dentro de um event handler.
• Sem permissão, sem canal de feedback. Não existe pedido nem evento de erro; uma chamada rejeitada simplesmente devolve false. Verifique esse valor de retorno se precisar de saber se funcionou.
• Separadores ocultos são bloqueados. Se a página não estiver visível (separador em segundo plano), o pedido é ignorado.
• Os padrões têm limite. Os browsers limitam a duração total máxima e o número de entradas num padrão; vibrações extremamente longas são truncadas.

Boas Práticas e Considerações

Embora a API de Vibração abra novos caminhos para o envolvimento dos utilizadores, a sua implementação deve ser abordada tendo em conta a experiência do utilizador.

• Respeitar as Preferências do Utilizador: Forneça sempre uma opção para os utilizadores desativarem o feedback de vibração, adaptando-se àqueles que possam achar intrusivo ou tenham preocupações de acessibilidade.
• Consumo de Bateria: Tenha em atenção o potencial impacto na vida útil da bateria do dispositivo, particularmente com o uso extensivo de padrões ou vibrações longas.
• Testar em Vários Dispositivos: A intensidade da vibração e a perceção dos padrões podem variar significativamente entre dispositivos. Testar em vários dispositivos garante uma experiência de utilizador consistente.
• Compatibilidade com Browsers: A API de Vibração é principalmente suportada em browsers móveis (Chrome, Firefox, Edge). Não é suportada no Safari nem na maioria dos browsers de secretária. Verifique sempre o suporte antes da implementação.

Conclusão

A API de Vibração do JavaScript oferece uma forma prática de envolver os utilizadores através de feedback tátil com um único método, navigator.vibrate(). Lembre-se dos pontos essenciais: detetar a funcionalidade antes de chamar, acionar apenas a partir de gestos do utilizador, manter uma abordagem mobile-first e combinar sempre o feedback háptico com uma alternativa visual ou sonora para que nada se perca em dispositivos sem suporte.

Para continuar a explorar APIs de browser orientadas ao dispositivo, consulte a API de Orientação do Ecrã para reagir a alterações entre retrato/paisagem, a API de Geolocalização para dados de localização, e Ambiente do Browser, Especificações para perceber como o navigator e outros objetos hospedeiros se encaixam.

Prática