JavaScript Vibration API

Introduzione alla Vibration API

La Vibration API consente alle pagine web di far vibrare il motore di vibrazione di un dispositivo, fornendo agli utenti un feedback aptico (basato sul tatto). È pensata per smartphone e tablet che vibrano fisicamente — su un desktop privo di motore, le chiamate riescono silenziosamente e non producono alcun effetto.

L'intera API si riduce a un singolo metodo, navigator.vibrate(). Non è previsto alcun prompt di autorizzazione né alcun evento da ascoltare: si chiama il metodo e il dispositivo vibra. Il compromesso è che i browser limitano quando è possibile invocarlo, come spiegato in dettaglio in questo capitolo.

Questa pagina illustra le due forme di argomento del metodo, come interrompere una vibrazione, il rilevamento delle funzionalità, i vincoli legati al gesto dell'utente e all'utilizzo solo su mobile, e come usare la vibrazione in modo appropriato.

Il metodo navigator.vibrate()

navigator.vibrate() accetta uno dei due tipi di argomento seguenti:

• Un singolo numero — vibra una volta per quel numero di millisecondi.
• Un array di numeri — uno schema di durate alternate di vibrazione e pausa.

Restituisce un boolean: true se la richiesta è stata accettata, false se è stata rifiutata (ad esempio, quando non si è verificato alcun gesto dell'utente). Sui dispositivi senza motore il metodo restituisce comunque true ma non produce alcuna vibrazione.

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

Schemi di vibrazione

Quando si passa un array, i numeri vengono interpretati come vibra, pausa, vibra, pausa, …. Le voci con indice dispari sono intervalli silenziosi.

// 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 finale non ha alcun effetto, poiché non c'è nulla dopo di essa che possa vibrare.

Interrompere una vibrazione

Una nuova chiamata sostituisce qualsiasi vibrazione già in corso. Per annullarla immediatamente, passare 0 o un array vuoto:

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

Questo è utile per reimpostare il feedback quando un utente chiude un avviso o naviga altrove.

Rilevamento delle funzionalità

navigator.vibrate è undefined nei browser che non la supportano, quindi chiamarla direttamente genererebbe un errore. Proteggere ogni chiamata con una guardia:

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

Il rilevamento può essere eseguito ovunque — anche in Node o in un browser desktop — anche se la vibrazione effettiva avviene solo su hardware compatibile.

Applicazioni pratiche

Capire come integrare efficacemente la Vibration API nelle applicazioni web può migliorare significativamente il coinvolgimento e la soddisfazione degli utenti. Di seguito sono riportati esempi di applicazioni pratiche che illustrano la versatilità della Vibration API.

Feedback sulle azioni dell'utente

Una breve vibrazione conferma un tocco sui dispositivi in cui l'utente non sempre vede la reazione dello schermo. Si noti che il gestore del click stesso è il gesto dell'utente, quindi la chiamata è consentita:

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

Avvisi di notifica

Quando un segnale sonoro o visivo potrebbe essere perso o inappropriato (modalità silenziosa, accessibilità), uno schema distintivo può sostituirlo:

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

Migliorare l'esperienza di gioco

Nei giochi web, la vibrazione aggiunge un feedback fisico nei momenti chiave — ma solo se quel momento segue un input recente dell'utente, altrimenti la chiamata verrà ignorata:

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

Limitazioni da tenere in considerazione

La Vibration API sembra semplice, ma i browser la avvolgono in restrizioni che possono causare silenziosamente un comportamento "senza effetto":

• Solo su mobile in pratica. La vibrazione richiede un motore hardware. I browser desktop o non dispongono del metodo (Safari, Firefox su desktop) o accettano la chiamata senza produrre vibrazioni. Considerare la vibrazione come un miglioramento, non come l'unico feedback.
• Richiede un gesto dell'utente. I browser moderni ignorano navigator.vibrate() a meno che non venga eseguita in risposta a una vera interazione (tocco, click o pressione di un tasto). Una vibrazione attivata al caricamento della pagina, da un setTimeout o da un evento in background viene eliminata silenziosamente — il metodo restituisce false. Attivare la vibrazione direttamente all'interno di un gestore di eventi.
• Nessuna autorizzazione, nessun canale di feedback. Non esiste alcun prompt né alcun evento di errore; una chiamata rifiutata restituisce semplicemente false. Verificare quel valore restituito se è necessario sapere se ha funzionato.
• Le schede nascoste sono bloccate. Se la pagina non è visibile (scheda in background), la richiesta viene ignorata.
• I pattern hanno un limite. I browser limitano la durata totale massima e il numero di voci in un pattern; le vibrazioni molto lunghe vengono troncate.

Best practice e considerazioni

Sebbene la Vibration API apra nuove possibilità per il coinvolgimento degli utenti, la sua implementazione deve essere affrontata tenendo conto dell'esperienza utente.

• Rispettare le preferenze degli utenti: fornire sempre un'opzione per disabilitare il feedback vibrante, per venire incontro a chi lo trova intrusivo o ha esigenze di accessibilità.
• Consumo della batteria: tenere presente il potenziale impatto sulla durata della batteria del dispositivo, in particolare con un uso estensivo di pattern o vibrazioni lunghe.
• Testare su più dispositivi: l'intensità e la percezione dei pattern di vibrazione possono variare significativamente tra i dispositivi. Testare su vari dispositivi garantisce un'esperienza utente coerente.
• Compatibilità con i browser: la Vibration API è supportata principalmente dai browser mobile (Chrome, Firefox, Edge). Non è supportata in Safari o nella maggior parte dei browser desktop. Verificare sempre il supporto prima dell'implementazione.

Conclusione

La Vibration API di JavaScript offre un modo pratico per coinvolgere gli utenti attraverso il feedback tattile con un singolo metodo, navigator.vibrate(). Ricordare i punti essenziali: rilevare la funzionalità prima di chiamarla, attivarla solo dai gesti dell'utente, mantenerla orientata al mobile e abbinare sempre le apticità a un fallback visivo o audio affinché nulla vada perso sui dispositivi non supportati.

Per continuare a esplorare le API del browser orientate al dispositivo, consultare la Screen Orientation API per reagire ai cambiamenti tra orientamento verticale e orizzontale, la Geolocation API per i dati di localizzazione e Browser Environment, Specs per capire come navigator e altri oggetti host si integrano nel contesto complessivo.

Esercitazione