Rimani attivo con l'API Screen Wake Lock

Pete LePage

Thomas Steiner

Data di pubblicazione: 18 dicembre 2018

Browser Support

Che cos'è l'API Screen Wake Lock?

Per evitare di scaricare la batteria, la maggior parte dei dispositivi entra rapidamente in modalità sospensione quando viene lasciato inattivo. Anche se questa impostazione va bene la maggior parte delle volte, alcune applicazioni devono mantenere lo schermo attivo per completare il lavoro. Alcuni esempi includono app di cucina che mostrano i passaggi di una ricetta o un gioco come Ball Puzzle, che utilizza le API di movimento del dispositivo per l'input.

L'API Screen Wake Lock offre un modo per impedire al dispositivo di oscurare e bloccare lo schermo. Questa funzionalità consente nuove esperienze che, fino ad ora, richiedevano un'app specifica per la piattaforma.

L'API Screen Wake Lock riduce la necessità di soluzioni alternative complicate e potenzialmente dispendiose in termini di energia. Affronta le carenze di un'API precedente che si limitava a mantenere lo schermo acceso e presentava una serie di problemi di sicurezza e privacy.

Casi d'uso suggeriti per l'API Screen Wake Lock

RioRun, un'app web sviluppata da The Guardian, era un caso d'uso perfetto (anche se non è più disponibile). L'app ti accompagna in un tour audio virtuale di Rio, seguendo il percorso della maratona olimpica del 2016. Senza i wake lock, gli schermi degli utenti si spegnerebbero frequentemente durante la riproduzione del tour, rendendone difficile l'utilizzo.

Naturalmente, esistono molti altri casi d'uso:

Un'app di ricette che mantiene lo schermo acceso mentre prepari una torta o la cena
Un'app per carte d'imbarco o biglietti che mantiene lo schermo acceso finché il codice a barre non è stato scansionato
Un'app in stile chiosco che mantiene lo schermo sempre acceso
Un'app di presentazione basata sul web che mantiene lo schermo acceso durante una presentazione

Utilizzare l'API Screen Wake Lock

L'API Screen Wake Lock fornisce un solo tipo di wake lock: screen.

`screen` wake lock

Un screen wake lock impedisce lo spegnimento dello schermo del dispositivo in modo che l'utente possa vedere le informazioni visualizzate sullo schermo.

Ottenere un wakelock dello schermo

Per richiedere un blocco di riattivazione dello schermo, devi chiamare il metodo navigator.wakeLock.request() che restituisce un oggetto WakeLockSentinel. Se vuoi, puoi trasmettere il tipo, screen, come parametro. Il browser può rifiutare la richiesta per vari motivi (ad esempio, perché il livello di carica della batteria è troppo basso), quindi è buona norma racchiudere la chiamata in un'istruzione try...catch. In caso di errore, il messaggio dell'eccezione contiene ulteriori dettagli.

Rilasciare un wakelock dello schermo

Devi anche un modo per rilasciare il blocco di riattivazione dello schermo, che si ottiene chiamando il metodo release() dell'oggetto WakeLockSentinel. Se non memorizzi un riferimento a WakeLockSentinel, non è possibile rilasciare il blocco manualmente, ma verrà rilasciato quando la scheda corrente non sarà più visibile.

Se vuoi rilasciare automaticamente il blocco riattivazione schermo dopo un determinato periodo di tempo, puoi utilizzare window.setTimeout() per chiamare release(), come mostrato nell'esempio.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock released:', wakeLock.released);
    });
    console.log('Screen Wake Lock released:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Request a screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

L'oggetto WakeLockSentinel ha una proprietà chiamata released che indica se è già stato rilasciato un sentinel. Il suo valore è inizialmente false e diventa true una volta inviato un evento "release". Questa proprietà aiuta gli sviluppatori web a sapere quando un blocco è stato rilasciato, senza monitoraggio manuale.

Ciclo di vita del wakelock dello schermo

Quando giochi con la demo del blocco dell'attivazione schermo, puoi notare che i blocchi dell'attivazione schermo sono sensibili alla visibilità della pagina. Ciò significa che il wakelock dello schermo viene rilasciato automaticamente quando riduci a icona una scheda o una finestra oppure quando passi a una scheda o una finestra in cui è attivo un wakelock dello schermo.

Per acquisire nuovamente il wakelock dello schermo, ascolta l'evento visibilitychange e richiedi un nuovo wakelock dello schermo quando si verificano:

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

Ridurre al minimo l'impatto sulle risorse di sistema

Devi utilizzare un blocco di riattivazione dello schermo nella tua app? L'approccio che adotti dipende dalle esigenze della tua app. In ogni caso, devi utilizzare l'approccio più leggero possibile per la tua app per ridurre al minimo il suo impatto sulle risorse di sistema.

Prima di aggiungere un blocco di riattivazione dello schermo alla tua app, valuta se i tuoi casi d'uso potrebbero essere risolti con una delle seguenti soluzioni alternative:

Se la tua app esegue download di lunga durata, valuta la possibilità di utilizzare il recupero in background.
Se la tua app sincronizza i dati da un server esterno, valuta la possibilità di utilizzare la sincronizzazione in background.

Demo

Dai un'occhiata alla demo di Screen Wake Lock e al codice sorgente della demo. Nota come il blocco riattivazione schermo venga rilasciato automaticamente quando cambi scheda o app.

Wakelock dello schermo nel task manager del sistema operativo

Puoi utilizzare Task Manager del sistema operativo per verificare se un'applicazione impedisce al computer di entrare in modalità di sospensione. Il video mostra il Monitoraggio Attività di macOS che indica che Chrome ha un blocco di riattivazione dello schermo attivo che mantiene il sistema attivo.

Feedback

Hai trovato un bug nell'implementazione di Chrome? O l'implementazione è diversa dalla specifica?

Segnala un bug. nel modo più dettagliato possibile. Fornisci istruzioni chiare per riprodurre il bug e imposta Componenti su Blink>WakeLock.

Risorse

Specifica Candidate Recommendation | Editor's Draft
Demo del blocco dell'attivazione schermo | Origine della demo del blocco dell'attivazione schermo
Bug di monitoraggio
Voce di ChromeStatus.com
Sperimentare con l'API Wake Lock
Componente Blink: Blink>WakeLock

Ringraziamenti

Video di Task Manager per gentile concessione di Henry Lim.